Países

Lista, consulta, cria, altera e exclui os países cadastrados na loja.

Os países são o primeiro nível da hierarquia geográfica. Uma loja brasileira normalmente tem só o BR; cadastre outros se a loja entrega ou cadastra clientes fora do Brasil. O país é identificado pelo código ISO em maiúsculas, não por UUID. Todas as rotas desta página exigem o privilégio manage_locations.

Listar países

GET/api/v1/admin/locations/countriesAdmin

Lista os países da loja

Devolve todos os países, ordenados pelo nome em inglês (name). Não há paginação.

Parâmetros de consulta

statusstring

ADactivedisabled

Filtra pelo status. A API aceita a letra ou a palavra longa e normaliza para a letra. Sem o parâmetro, devolve todos.

200Países retornados

json

{
  "countries": [
    { "code": "BR", "name": "Brazil", "name_pt": "Brasil", "status": "A" }
  ],
  "total": 1
}

Campos da resposta

countriesarray

Lista de países.

countries[].codestring

Código ISO de 2 a 3 letras, em maiúsculas. É a chave do país.

countries[].namestring

Nome em inglês.

countries[].name_ptstring

Nome em português.

countries[].statusstring

AD

A ativo, D desativado.

totalinteger

Quantidade de países devolvidos.

Consultar país

GET/api/v1/admin/locations/countries/{code}Admin

Consulta um país pelo código

Parâmetros de caminho

codestringobrigatório

Código do país (BR).

200País encontrado

json

{ "code": "BR", "name": "Brazil", "name_pt": "Brasil", "status": "A" }

Criar país

POST/api/v1/admin/locations/countriesAdmin

Cadastra um novo país

O código é convertido para maiúsculas e precisa ter 2 ou 3 letras. Se status não for enviado, o país nasce ativo (A).

Corpo da requisição

codestringobrigatório

Código ISO, 2 a 3 letras (AR, ARG). Único na loja.

namestringobrigatório

Nome em inglês.

name_ptstring

Nome em português.

statusstringpadrão: A

ADactivedisabled

Status inicial.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/locations/countries" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"AR","name":"Argentina","name_pt":"Argentina"}'

201País criado

json

{ "code": "AR", "name": "Argentina", "name_pt": "Argentina", "status": "A" }

Alterar país

PUT/api/v1/admin/locations/countries/{code}Admin

Altera nome ou status de um país

Alteração parcial: só os campos enviados mudam. O código não pode ser alterado. Um corpo vazio ({}) não muda nada e devolve o país atual.

Parâmetros de caminho

codestringobrigatório

Código do país.

Corpo da requisição

namestring

Novo nome em inglês.

name_ptstring

Novo nome em português.

statusstring

ADactivedisabled

Novo status.

A resposta 200 é o país já atualizado, no mesmo formato de "Consultar país".

Excluir país

DELETE/api/v1/admin/locations/countries/{code}Admin

Exclui um país sem estados

Parâmetros de caminho

codestringobrigatório

Código do país.

200País excluído

json

{ "message": "country deleted" }

Erros

Status	Quando	Corpo
400	Corpo JSON inválido; `code` ou `name` ausente; código fora do padrão de 2 a 3 letras	`{"error":"country code must be 2-3 letters (ISO format)"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Usuário sem o privilégio `manage_locations`	`{"error":"insufficient privileges","required":"manage_locations"}`
404	Código inexistente (consultar, alterar)	`{"error":"country not found"}`
409	Criar com código já existente; excluir país que ainda tem estados	`{"error":"country code already exists"}` ou `{"error":"country has dependent states","detail":"delete or reassign states first"}`
500	Falha interna; também ao excluir um código que não existe	`{"error":"failed to delete country","detail":"country XX not found"}`

Veja também

Países

Lista, consulta, cria, altera e exclui os países cadastrados na loja.

Listar países

GET/api/v1/admin/locations/countriesAdmin

Lista os países da loja

Devolve todos os países, ordenados pelo nome em inglês (name). Não há paginação.

Parâmetros de consulta

statusstring

ADactivedisabled

Filtra pelo status. A API aceita a letra ou a palavra longa e normaliza para a letra. Sem o parâmetro, devolve todos.

200Países retornados

json

{
  "countries": [
    { "code": "BR", "name": "Brazil", "name_pt": "Brasil", "status": "A" }
  ],
  "total": 1
}

Campos da resposta

countriesarray

Lista de países.

countries[].codestring

Código ISO de 2 a 3 letras, em maiúsculas. É a chave do país.

countries[].namestring

Nome em inglês.

countries[].name_ptstring

Nome em português.

countries[].statusstring

AD

A ativo, D desativado.

totalinteger

Quantidade de países devolvidos.

Consultar país

GET/api/v1/admin/locations/countries/{code}Admin

Consulta um país pelo código

Parâmetros de caminho

codestringobrigatório

Código do país (BR).

200País encontrado

json

{ "code": "BR", "name": "Brazil", "name_pt": "Brasil", "status": "A" }

Criar país

POST/api/v1/admin/locations/countriesAdmin

Cadastra um novo país

O código é convertido para maiúsculas e precisa ter 2 ou 3 letras. Se status não for enviado, o país nasce ativo (A).

Corpo da requisição

codestringobrigatório

Código ISO, 2 a 3 letras (AR, ARG). Único na loja.

namestringobrigatório

Nome em inglês.

name_ptstring

Nome em português.

statusstringpadrão: A

ADactivedisabled

Status inicial.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/locations/countries" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"AR","name":"Argentina","name_pt":"Argentina"}'

201País criado

json

{ "code": "AR", "name": "Argentina", "name_pt": "Argentina", "status": "A" }

Alterar país

PUT/api/v1/admin/locations/countries/{code}Admin

Altera nome ou status de um país

Alteração parcial: só os campos enviados mudam. O código não pode ser alterado. Um corpo vazio ({}) não muda nada e devolve o país atual.

Parâmetros de caminho

codestringobrigatório

Código do país.

Corpo da requisição

namestring

Novo nome em inglês.

name_ptstring

Novo nome em português.

statusstring

ADactivedisabled

Novo status.

A resposta 200 é o país já atualizado, no mesmo formato de "Consultar país".

Excluir país

DELETE/api/v1/admin/locations/countries/{code}Admin

Exclui um país sem estados

Parâmetros de caminho

codestringobrigatório

Código do país.

200País excluído

json

{ "message": "country deleted" }

Erros

Status	Quando	Corpo
400	Corpo JSON inválido; `code` ou `name` ausente; código fora do padrão de 2 a 3 letras	`{"error":"country code must be 2-3 letters (ISO format)"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Usuário sem o privilégio `manage_locations`	`{"error":"insufficient privileges","required":"manage_locations"}`
404	Código inexistente (consultar, alterar)	`{"error":"country not found"}`
409	Criar com código já existente; excluir país que ainda tem estados	`{"error":"country code already exists"}` ou `{"error":"country has dependent states","detail":"delete or reassign states first"}`
500	Falha interna; também ao excluir um código que não existe	`{"error":"failed to delete country","detail":"country XX not found"}`