API atual/Referência completa/Mercados internacionais

Cadastro de mercados

Lista, cria, consulta, atualiza e exclui mercados, com as regras de país único e a armadilha do PATCH que substitui tudo.

Estas cinco operações mantêm o cadastro de mercados. Todas exigem o privilégio manage_settings.

Listar mercados

Devolve todos os mercados não excluídos, o padrão primeiro e depois por nome. Não há paginação nem filtro.

GET/api/v1/admin/marketsAdmin

Lista os mercados da loja

200Mercados

json

{
  "items": [
    {
      "id": "cec34bae-b229-4f42-b7a6-b93d4ef2c765",
      "name": "Portugal",
      "status": "active",
      "is_default": false,
      "lang_code": "pt-PT",
      "currency_code": "EUR",
      "price_adjust_bp": 1200,
      "incoterm": "DDP",
      "country_codes": ["PT"],
      "created_at": "2026-10-11T21:26:22Z",
      "updated_at": "2026-10-11T21:26:22Z"
    }
  ]
}

Campos da resposta

itemsarray

Mercados. Lista vazia se não houver nenhum.

items[].iduuid

Id do mercado.

items[].namestring

Nome para exibição.

items[].statusstring

activeinactive

active ou inactive. Só mercados ativos participam da regra de país único e da resolução por país.

items[].is_defaultboolean

true no mercado padrão da loja.

items[].lang_codestring

Idioma (por exemplo pt-BR, en).

items[].currency_codestring

Moeda ISO 4217 (BRL, EUR, USD).

items[].price_adjust_bpinteger

Ajuste do preço em pontos-base, com sinal. 1200 = +12%.

items[].incotermstring

DDUDDP

Quem paga os impostos de importação.

items[].country_codesarray

Países do mercado, ISO de 2 letras maiúsculas. Pode vir null em mercado sem países.

items[].created_atstring

Criação (RFC 3339, UTC).

items[].updated_atstring

Última alteração.

Criar um mercado

POST/api/v1/admin/marketsAdmin

Cria um mercado

Corpo da requisição

namestringobrigatório

Nome do mercado. A API não valida: vazio é aceito, mas inútil.

lang_codestringobrigatório

Idioma do mercado.

currency_codestringobrigatório

Moeda do mercado (ISO 4217).

price_adjust_bpintegerpadrão: 0

Ajuste do preço em pontos-base (inteiro, pode ser negativo).

incotermstringpadrão: DDU

DDUDDP

DDP inclui impostos de importação no total. Qualquer outro valor vira DDU.

country_codesarray

Países (ISO de 2 letras, sem diferenciar maiúsculas). Duplicatas são removidas.

statusstringpadrão: active

activeinactive

Status inicial.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/markets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Portugal","lang_code":"pt-PT","currency_code":"EUR","price_adjust_bp":1200,"incoterm":"DDP","country_codes":["PT"]}'

201Mercado criado

json

{
  "id": "cec34bae-b229-4f42-b7a6-b93d4ef2c765",
  "name": "Portugal",
  "status": "active",
  "is_default": false,
  "lang_code": "pt-PT",
  "currency_code": "EUR",
  "price_adjust_bp": 1200,
  "incoterm": "DDP",
  "country_codes": ["PT"],
  "created_at": "2026-10-11T21:26:22Z",
  "updated_at": "2026-10-11T21:26:22Z"
}

Consultar um mercado

GET/api/v1/admin/markets/{id}Admin

Consulta um mercado

Parâmetros de caminho

iduuidobrigatório

Id do mercado.

Devolve o mesmo objeto da criação.

Atualizar um mercado

PATCH/api/v1/admin/markets/{id}Admin

Substitui os dados de um mercado

Parâmetros de caminho

iduuidobrigatório

Id do mercado.

Corpo da requisição

namestringobrigatório

Nome.

lang_codestringobrigatório

Idioma.

currency_codestringobrigatório

Moeda.

price_adjust_bpintegerpadrão: 0

Ajuste em pontos-base.

incotermstringpadrão: DDU

DDUDDP

Incoterm.

country_codesarray

Lista completa de países. Substitui a anterior.

statusstringpadrão: active

activeinactive

Status. Se omitido, volta a active.

Excluir um mercado

Remove o mercado das listas (exclusão lógica). Responde 204 sem corpo. O mercado padrão não pode ser excluído.

DELETE/api/v1/admin/markets/{id}Admin

Exclui um mercado

Parâmetros de caminho

iduuidobrigatório

Id do mercado.

Erros

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid request body","detail":"..."}`
404	Mercado não existe, foi excluído, ou é o padrão (no `DELETE`).	`{"error":"market not found","detail":"market not found"}`
409	Um dos países já pertence a outro mercado ativo (na criação e na atualização).	`{"error":"country already assigned to an active market","detail":"country already assigned to an active market"}`
500	`id` não é UUID.	`{"error":"market operation failed","detail":"o valor \"abc\" não é um uuid válido. ..."}`
401 / 403	Sem token ou sem `manage_settings`.	`{"error":"missing authorization header"}`

O detail do erro 500 de UUID inválido sai em português, como o servidor devolve.

Veja também

API atual/Referência completa/Mercados internacionais

Cadastro de mercados

Lista, cria, consulta, atualiza e exclui mercados, com as regras de país único e a armadilha do PATCH que substitui tudo.

Estas cinco operações mantêm o cadastro de mercados. Todas exigem o privilégio manage_settings.

Listar mercados

Devolve todos os mercados não excluídos, o padrão primeiro e depois por nome. Não há paginação nem filtro.

GET/api/v1/admin/marketsAdmin

Lista os mercados da loja

200Mercados

json

{
  "items": [
    {
      "id": "cec34bae-b229-4f42-b7a6-b93d4ef2c765",
      "name": "Portugal",
      "status": "active",
      "is_default": false,
      "lang_code": "pt-PT",
      "currency_code": "EUR",
      "price_adjust_bp": 1200,
      "incoterm": "DDP",
      "country_codes": ["PT"],
      "created_at": "2026-10-11T21:26:22Z",
      "updated_at": "2026-10-11T21:26:22Z"
    }
  ]
}

Campos da resposta

itemsarray

Mercados. Lista vazia se não houver nenhum.

items[].iduuid

Id do mercado.

items[].namestring

Nome para exibição.

items[].statusstring

activeinactive

active ou inactive. Só mercados ativos participam da regra de país único e da resolução por país.

items[].is_defaultboolean

true no mercado padrão da loja.

items[].lang_codestring

Idioma (por exemplo pt-BR, en).

items[].currency_codestring

Moeda ISO 4217 (BRL, EUR, USD).

items[].price_adjust_bpinteger

Ajuste do preço em pontos-base, com sinal. 1200 = +12%.

items[].incotermstring

DDUDDP

Quem paga os impostos de importação.

items[].country_codesarray

Países do mercado, ISO de 2 letras maiúsculas. Pode vir null em mercado sem países.

items[].created_atstring

Criação (RFC 3339, UTC).

items[].updated_atstring

Última alteração.

Criar um mercado

POST/api/v1/admin/marketsAdmin

Cria um mercado

Corpo da requisição

namestringobrigatório

Nome do mercado. A API não valida: vazio é aceito, mas inútil.

lang_codestringobrigatório

Idioma do mercado.

currency_codestringobrigatório

Moeda do mercado (ISO 4217).

price_adjust_bpintegerpadrão: 0

Ajuste do preço em pontos-base (inteiro, pode ser negativo).

incotermstringpadrão: DDU

DDUDDP

DDP inclui impostos de importação no total. Qualquer outro valor vira DDU.

country_codesarray

Países (ISO de 2 letras, sem diferenciar maiúsculas). Duplicatas são removidas.

statusstringpadrão: active

activeinactive

Status inicial.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/markets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Portugal","lang_code":"pt-PT","currency_code":"EUR","price_adjust_bp":1200,"incoterm":"DDP","country_codes":["PT"]}'

201Mercado criado

json

{
  "id": "cec34bae-b229-4f42-b7a6-b93d4ef2c765",
  "name": "Portugal",
  "status": "active",
  "is_default": false,
  "lang_code": "pt-PT",
  "currency_code": "EUR",
  "price_adjust_bp": 1200,
  "incoterm": "DDP",
  "country_codes": ["PT"],
  "created_at": "2026-10-11T21:26:22Z",
  "updated_at": "2026-10-11T21:26:22Z"
}

Consultar um mercado

GET/api/v1/admin/markets/{id}Admin

Consulta um mercado

Parâmetros de caminho

iduuidobrigatório

Id do mercado.

Devolve o mesmo objeto da criação.

Atualizar um mercado

PATCH/api/v1/admin/markets/{id}Admin

Substitui os dados de um mercado

Parâmetros de caminho

iduuidobrigatório

Id do mercado.

Corpo da requisição

namestringobrigatório

Nome.

lang_codestringobrigatório

Idioma.

currency_codestringobrigatório

Moeda.

price_adjust_bpintegerpadrão: 0

Ajuste em pontos-base.

incotermstringpadrão: DDU

DDUDDP

Incoterm.

country_codesarray

Lista completa de países. Substitui a anterior.

statusstringpadrão: active

activeinactive

Status. Se omitido, volta a active.

Excluir um mercado

Remove o mercado das listas (exclusão lógica). Responde 204 sem corpo. O mercado padrão não pode ser excluído.

DELETE/api/v1/admin/markets/{id}Admin

Exclui um mercado

Parâmetros de caminho

iduuidobrigatório

Id do mercado.

Erros

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid request body","detail":"..."}`
404	Mercado não existe, foi excluído, ou é o padrão (no `DELETE`).	`{"error":"market not found","detail":"market not found"}`
409	Um dos países já pertence a outro mercado ativo (na criação e na atualização).	`{"error":"country already assigned to an active market","detail":"country already assigned to an active market"}`
500	`id` não é UUID.	`{"error":"market operation failed","detail":"o valor \"abc\" não é um uuid válido. ..."}`
401 / 403	Sem token ou sem `manage_settings`.	`{"error":"missing authorization header"}`

O detail do erro 500 de UUID inválido sai em português, como o servidor devolve.