Mercados internacionais

Um mercado é a regra de venda de um grupo de países: qual idioma e moeda o visitante vê, quanto o preço sobe ou desce, e quais produtos ficam de fora. É a ideia de "Markets" de outras plataformas. Um comprador de Portugal pode ver a loja em português europeu, em euros, com preço 12% maior e sem os produtos que a loja não envia para lá.

Como funciona

O comprador é associado a um mercado nesta ordem: o cookie venddor_market (escolha explícita), o país informado pelo CDN (CF-IPCountry), o primeiro país do Accept-Language, e por fim o mercado padrão. O pedido grava o market_id no momento da compra, e é por isso que as métricas continuam contando pedidos antigos mesmo que você mude o mercado depois.

1. Crie o mercado

   Cadastre nome, idioma (lang_code), moeda (currency_code), países e ajuste de preço.

2. Defina o que ele não vende

   Com o sortimento, exclua categorias (com todas as filhas) e produtos específicos daquele mercado.

3. Acompanhe

   Veja pedidos e receita de cada mercado.

Conceitos-chave

Incoterm

Define quem paga os impostos de importação. DDU: o comprador paga na chegada e a estimativa é só informativa. DDP: os impostos entram no total cobrado. Qualquer valor diferente de DDP vira DDU.

Países

country_codes são códigos ISO de 2 letras (PT, US). A API converte para maiúsculas, remove espaços e duplicatas.

Dinheiro

price_adjust_bp é inteiro em pontos-base. revenue_cents nas métricas é inteiro em centavos da moeda do mercado.

Exclusão

Excluir um mercado é lógico (ele some das listas). Os pedidos que o usaram mantêm o market_id.

Endpoints

Erros comuns

• Usar PATCH como parcial. Ele reescreve o mercado todo. Enviar só {"name":"X"} zera idioma, moeda, países e ajuste, e devolve o status para active.
• Criar sem validar. A API aceita {} e cria um mercado vazio (nome, idioma e moeda em branco). Valide no seu lado.
• País repetido. Dois mercados ativos com o mesmo país: 409. Inative o antigo ou tire o país dele antes.
• Tentar definir o padrão. is_default não é aceito no corpo; o campo é ignorado.
• Id inválido. Um id que não é UUID devolve 500 com a mensagem do banco, não 400. Um UUID inexistente devolve 404.
• Excluir o padrão. Devolve 404 market not found, igual a um id que não existe.

Próximos passos