Estados

Lista, consulta, cria, altera e exclui os estados (UFs) de cada país.

Estado é o segundo nível da hierarquia: pertence a um país e agrupa cidades. O estado é identificado por UUID; a sigla (SP) fica no campo code e é única dentro do país. Exige o privilégio manage_locations.

Listar estados

GET/api/v1/admin/locations/statesAdmin

Lista os estados

Devolve todos os estados (sem paginação), ordenados pelo nome.

Parâmetros de consulta

country_codestring

Somente estados deste país (BR). A comparação é exata e diferencia maiúsculas.

200Estados retornados

json

{
  "states": [
    {
      "id": "bd6860b2-2838-4eb7-ab27-37b0be2412ab",
      "country_code": "BR",
      "code": "AC",
      "name": "Acre",
      "name_pt": "Acre"
    }
  ],
  "total": 27
}

Campos da resposta

states[].iduuid

Identificador do estado.

states[].country_codestring

Código do país dono.

states[].codestring

Sigla do estado (SP), 2 a 3 letras.

states[].namestring

Nome em inglês.

states[].name_ptstring

Nome em português.

totalinteger

Quantidade de estados devolvidos.

Consultar estado

GET/api/v1/admin/locations/states/{id}Admin

Consulta um estado pelo id

Parâmetros de caminho

iduuidobrigatório

Id do estado.

A resposta 200 é um único objeto no formato de states[] acima.

Criar estado

POST/api/v1/admin/locations/statesAdmin

Cadastra um estado

country_code e code são convertidos para maiúsculas. A combinação país + sigla é única.

Corpo da requisição

country_codestringobrigatório

País dono. O código precisa existir.

codestringobrigatório

Sigla de 2 a 3 letras (SP).

namestringobrigatório

Nome em inglês.

name_ptstring

Nome em português.

Exemplo de requisição

bash

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

201Estado criado

json

{
  "id": "0b6f6b5e-3d0c-4f4c-9a5c-7a1d2f6a9c11",
  "country_code": "AR",
  "code": "BA",
  "name": "Buenos Aires",
  "name_pt": "Buenos Aires"
}

Alterar estado

PUT/api/v1/admin/locations/states/{id}Admin

Altera sigla ou nomes de um estado

Alteração parcial. O país do estado não pode ser trocado. Diferente da criação, a sigla enviada aqui não é validada nem convertida para maiúsculas.

Parâmetros de caminho

iduuidobrigatório

Id do estado.

Corpo da requisição

codestring

Nova sigla.

namestring

Novo nome em inglês.

name_ptstring

Novo nome em português.

A resposta 200 é o estado atualizado.

Excluir estado

DELETE/api/v1/admin/locations/states/{id}Admin

Exclui um estado sem cidades

Parâmetros de caminho

iduuidobrigatório

Id do estado.

200Estado excluído

json

{ "message": "state deleted" }

Erros

Status	Quando	Corpo
400	JSON inválido; campo obrigatório ausente; sigla fora do padrão de 2 a 3 letras	`{"error":"state code must be 2-3 letters"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_locations`	`{"error":"insufficient privileges","required":"manage_locations"}`
404	Id inexistente (consultar, alterar)	`{"error":"state not found"}`
409	Sigla já existe no país; excluir estado com cidades	`{"error":"state code already exists","detail":"a state with this code already exists for this country"}` ou `{"error":"state has dependent cities","detail":"delete or reassign cities first"}`
500	Id que não é UUID (consultar, alterar, excluir), ou excluir id que não existe	`{"error":"failed to get state","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Veja também

API atual/Referência completa/Locais

Estados

Lista, consulta, cria, altera e exclui os estados (UFs) de cada país.

Listar estados

GET/api/v1/admin/locations/statesAdmin

Lista os estados

Devolve todos os estados (sem paginação), ordenados pelo nome.

Parâmetros de consulta

country_codestring

Somente estados deste país (BR). A comparação é exata e diferencia maiúsculas.

200Estados retornados

json

{
  "states": [
    {
      "id": "bd6860b2-2838-4eb7-ab27-37b0be2412ab",
      "country_code": "BR",
      "code": "AC",
      "name": "Acre",
      "name_pt": "Acre"
    }
  ],
  "total": 27
}

Campos da resposta

states[].iduuid

Identificador do estado.

states[].country_codestring

Código do país dono.

states[].codestring

Sigla do estado (SP), 2 a 3 letras.

states[].namestring

Nome em inglês.

states[].name_ptstring

Nome em português.

totalinteger

Quantidade de estados devolvidos.

Consultar estado

GET/api/v1/admin/locations/states/{id}Admin

Consulta um estado pelo id

Parâmetros de caminho

iduuidobrigatório

Id do estado.

A resposta 200 é um único objeto no formato de states[] acima.

Criar estado

POST/api/v1/admin/locations/statesAdmin

Cadastra um estado

country_code e code são convertidos para maiúsculas. A combinação país + sigla é única.

Corpo da requisição

country_codestringobrigatório

País dono. O código precisa existir.

codestringobrigatório

Sigla de 2 a 3 letras (SP).

namestringobrigatório

Nome em inglês.

name_ptstring

Nome em português.

Exemplo de requisição

bash

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

201Estado criado

json

{
  "id": "0b6f6b5e-3d0c-4f4c-9a5c-7a1d2f6a9c11",
  "country_code": "AR",
  "code": "BA",
  "name": "Buenos Aires",
  "name_pt": "Buenos Aires"
}

Alterar estado

PUT/api/v1/admin/locations/states/{id}Admin

Altera sigla ou nomes de um estado

Alteração parcial. O país do estado não pode ser trocado. Diferente da criação, a sigla enviada aqui não é validada nem convertida para maiúsculas.

Parâmetros de caminho

iduuidobrigatório

Id do estado.

Corpo da requisição

codestring

Nova sigla.

namestring

Novo nome em inglês.

name_ptstring

Novo nome em português.

A resposta 200 é o estado atualizado.

Excluir estado

DELETE/api/v1/admin/locations/states/{id}Admin

Exclui um estado sem cidades

Parâmetros de caminho

iduuidobrigatório

Id do estado.

200Estado excluído

json

{ "message": "state deleted" }

Erros

Status	Quando	Corpo
400	JSON inválido; campo obrigatório ausente; sigla fora do padrão de 2 a 3 letras	`{"error":"state code must be 2-3 letters"}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_locations`	`{"error":"insufficient privileges","required":"manage_locations"}`
404	Id inexistente (consultar, alterar)	`{"error":"state not found"}`
409	Sigla já existe no país; excluir estado com cidades	`{"error":"state code already exists","detail":"a state with this code already exists for this country"}` ou `{"error":"state has dependent cities","detail":"delete or reassign cities first"}`
500	Id que não é UUID (consultar, alterar, excluir), ou excluir id que não existe	`{"error":"failed to get state","detail":"o valor \"abc\" não é um uuid válido. ..."}`