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

bash

curl "$BASE_URL/api/v1/storefront/market" \
  -H "CF-IPCountry: US"

Resposta

200Mercado ativo e sugestão

json

{
  "market": {
    "id": "0b9f1c2e-6d3a-4f57-8a14-2c7e5b9d1a30",
    "name": "Brasil",
    "lang_code": "pt-BR",
    "currency_code": "BRL"
  },
  "suggested": {
    "id": "7a41e8d2-93bc-4c06-b5f0-1d2e3a4b5c6d",
    "name": "Estados Unidos",
    "lang_code": "en-US",
    "currency_code": "USD",
    "country_code": "US"
  }
}

200Loja sem mercados

json

{ "market": null, "suggested": null }

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

bash

curl -X POST "$BASE_URL/api/v1/storefront/market/select" \
  -H "Content-Type: application/json" \
  -d '{
  "market_id": "7a41e8d2-93bc-4c06-b5f0-1d2e3a4b5c6d"
}'

Resposta

200Mercado gravado no cookie

json

{
  "id": "7a41e8d2-93bc-4c06-b5f0-1d2e3a4b5c6d",
  "name": "Estados Unidos",
  "status": "active",
  "is_default": false,
  "lang_code": "en-US",
  "currency_code": "USD",
  "price_adjust_bp": 500,
  "incoterm": "DDU",
  "country_codes": ["US"],
  "created_at": "2026-08-02T12:00:00Z",
  "updated_at": "2026-09-01T09:30:00Z"
}

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

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.

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

bash

curl "$BASE_URL/api/v1/storefront/market" \
  -H "CF-IPCountry: US"

Resposta

200Mercado ativo e sugestão

json

{
  "market": {
    "id": "0b9f1c2e-6d3a-4f57-8a14-2c7e5b9d1a30",
    "name": "Brasil",
    "lang_code": "pt-BR",
    "currency_code": "BRL"
  },
  "suggested": {
    "id": "7a41e8d2-93bc-4c06-b5f0-1d2e3a4b5c6d",
    "name": "Estados Unidos",
    "lang_code": "en-US",
    "currency_code": "USD",
    "country_code": "US"
  }
}

200Loja sem mercados

json

{ "market": null, "suggested": null }

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

bash

curl -X POST "$BASE_URL/api/v1/storefront/market/select" \
  -H "Content-Type: application/json" \
  -d '{
  "market_id": "7a41e8d2-93bc-4c06-b5f0-1d2e3a4b5c6d"
}'

Resposta

200Mercado gravado no cookie

json

{
  "id": "7a41e8d2-93bc-4c06-b5f0-1d2e3a4b5c6d",
  "name": "Estados Unidos",
  "status": "active",
  "is_default": false,
  "lang_code": "en-US",
  "currency_code": "USD",
  "price_adjust_bp": 500,
  "incoterm": "DDU",
  "country_codes": ["US"],
  "created_at": "2026-08-02T12:00:00Z",
  "updated_at": "2026-09-01T09:30:00Z"
}

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":"..."}`