API atual/Referência completa/Utilidades da vitrine

Mercado ativo

Descobre em que mercado (país, idioma e moeda) o visitante está e permite trocá-lo.

Uma loja pode vender em vários países. Cada mercado reúne países que compartilham idioma (lang_code), moeda (currency_code) e um ajuste de preço. Estas duas rotas dizem ao front-end em que mercado o visitante está e deixam o visitante trocar.

Ler o mercado ativo

GET/api/v1/storefront/marketPública

Mercado ativo do visitante

Não exige token. O mercado é resolvido nesta ordem: (1) o cookie venddor_market, se existir e apontar para um mercado válido; (2) o mercado cujo país corresponde à localização do visitante; (3) o mercado padrão da loja. A localização vem do cabeçalho CF-IPCountry (preenchido pela rede de borda) ou, na falta dele, da região do primeiro idioma de Accept-Language (pt-BR indica BR).

Cabeçalhos

Cookiestring

venddor_market=<uuid> quando o visitante já escolheu um mercado.

CF-IPCountrystring

País de duas letras (ISO 3166-1), normalmente preenchido pela borda.

Accept-Languagestring

Usado só se CF-IPCountry faltar.

Exemplo de requisição

Resposta

200Mercado ativo e sugestão

200Loja sem mercados

Campos da resposta

marketobject

O mercado que vale agora. null quando a loja não configurou nenhum mercado (o caso da maioria das lojas).

market.iduuid

Id do mercado.

market.namestring

Nome para exibição.

market.lang_codestring

Idioma do mercado, como pt-BR.

market.currency_codestring

Moeda ISO 4217, como BRL.

suggestedobject

Mercado que combina com a localização do visitante, quando difere do ativo. Só aparece se o visitante ainda não tem o cookie venddor_market. Mostre como um convite ("Ver a loja nos Estados Unidos?"), sem trocar sozinho.

suggested.country_codestring

País detectado.

Erros

Status	Quando	Corpo
500	Falha ao resolver o mercado.	`{"error":"failed to resolve market","detail":"..."}`

Escolher o mercado

POST/api/v1/storefront/market/selectPública

Escolhe o mercado do visitante

Grava o mercado escolhido no cookie venddor_market (90 dias, Path=/, SameSite=Lax, sem HttpOnly, para o front-end poder lê-lo; Secure em HTTPS) e devolve o mercado completo.

Corpo da requisição

market_iduuidobrigatório

Id do mercado escolhido.

Exemplo de requisição

Resposta

200Mercado gravado no cookie

Campos da resposta

iduuid

Id do mercado.

namestring

Nome do mercado.

statusstring

active ou inactive.

is_defaultboolean

true no mercado padrão da loja.

lang_codestring

Idioma.

currency_codestring

Moeda ISO 4217.

price_adjust_bpinteger

Ajuste de preço em pontos-base (500 = 5%).

incotermstring

Regra de entrega internacional: DDU (o comprador paga os impostos de importação na chegada) ou DDP (os impostos já entram no total).

country_codesstring[]

Países do mercado.

created_atstring

RFC 3339.

updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
404	Nenhum mercado com esse id (UUID válido, mas inexistente ou apagado).	`{"error":"market not found","detail":"market not found"}`
500	`market_id` ausente ou que não é UUID. Deveria ser 400, mas hoje é 500.	`{"error":"market operation failed","detail":"..."}`

Veja também

Mercado ativo

Descobre em que mercado (país, idioma e moeda) o visitante está e permite trocá-lo.

Ler o mercado ativo

GET/api/v1/storefront/marketPública

Mercado ativo do visitante

Cabeçalhos

Cookiestring

venddor_market=<uuid> quando o visitante já escolheu um mercado.

CF-IPCountrystring

País de duas letras (ISO 3166-1), normalmente preenchido pela borda.

Accept-Languagestring

Usado só se CF-IPCountry faltar.

Exemplo de requisição

Resposta

200Mercado ativo e sugestão

200Loja sem mercados

Campos da resposta

marketobject

O mercado que vale agora. null quando a loja não configurou nenhum mercado (o caso da maioria das lojas).

market.iduuid

Id do mercado.

market.namestring

Nome para exibição.

market.lang_codestring

Idioma do mercado, como pt-BR.

market.currency_codestring

Moeda ISO 4217, como BRL.

suggestedobject

suggested.country_codestring

País detectado.

Erros

Status	Quando	Corpo
500	Falha ao resolver o mercado.	`{"error":"failed to resolve market","detail":"..."}`

Escolher o mercado

POST/api/v1/storefront/market/selectPública

Escolhe o mercado do visitante

Grava o mercado escolhido no cookie venddor_market (90 dias, Path=/, SameSite=Lax, sem HttpOnly, para o front-end poder lê-lo; Secure em HTTPS) e devolve o mercado completo.

Corpo da requisição

market_iduuidobrigatório

Id do mercado escolhido.

Exemplo de requisição

Resposta

200Mercado gravado no cookie

Campos da resposta

iduuid

Id do mercado.

namestring

Nome do mercado.

statusstring

active ou inactive.

is_defaultboolean

true no mercado padrão da loja.

lang_codestring

Idioma.

currency_codestring

Moeda ISO 4217.

price_adjust_bpinteger

Ajuste de preço em pontos-base (500 = 5%).

incotermstring

Regra de entrega internacional: DDU (o comprador paga os impostos de importação na chegada) ou DDP (os impostos já entram no total).

country_codesstring[]

Países do mercado.

created_atstring

RFC 3339.

updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
404	Nenhum mercado com esse id (UUID válido, mas inexistente ou apagado).	`{"error":"market not found","detail":"market not found"}`
500	`market_id` ausente ou que não é UUID. Deveria ser 400, mas hoje é 500.	`{"error":"market operation failed","detail":"..."}`