Cidades

Lista paginada, consulta, criação, alteração e exclusão de cidades (municípios) de um estado.

Cidade é o terceiro nível: pertence a um estado e agrupa bairros. Ela guarda o código IBGE de 7 dígitos, usado no cálculo de ISS e em integrações fiscais. O id é um UUID. Exige o privilégio manage_locations.

Listar cidades

GET/api/v1/admin/locations/citiesAdmin

Lista cidades com paginação

Ordenadas pelo nome. Para montar um seletor de cidades de um estado inteiro, filtre por state_id e use per_page=1000.

Parâmetros de consulta

state_iduuid

Somente cidades deste estado.

searchstring

Texto contido no nome da cidade, sem diferenciar maiúsculas (campinas).

sort_dirstringpadrão: asc

ascdesc

Direção da ordenação por nome.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página. O máximo é 1000: valores maiores são reduzidos a 1000, valores menores que 1 voltam a 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/locations/cities?search=campinas&per_page=2" \
  -H "Authorization: Bearer $TOKEN"

200Cidades retornadas

json

{
  "cities": [
    {
      "id": "6b4323c6-b531-4042-a72c-5afa1d9e0afd",
      "state_id": "55766ae5-4725-4971-b1bb-29686b7cc492",
      "state_name": "São Paulo",
      "state_code": "SP",
      "name": "Campinas",
      "ibge_code": "3509502"
    }
  ],
  "total": 3,
  "page": 1,
  "per_page": 2,
  "total_pages": 2
}

Campos da resposta

cities[].iduuid

Identificador da cidade.

cities[].state_iduuid

Estado dono.

cities[].state_namestring

Nome do estado. Só aparece nas listagens e na consulta.

cities[].state_codestring

Sigla do estado (SP).

cities[].namestring

Nome da cidade.

cities[].ibge_codestring

Código IBGE de 7 dígitos. Pode ser vazio.

totalinteger

Total de cidades que atendem ao filtro, em todas as páginas.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Consultar cidade

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

Consulta uma cidade pelo id

Parâmetros de caminho

iduuidobrigatório

Id da cidade.

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

Criar cidade

POST/api/v1/admin/locations/citiesAdmin

Cadastra uma cidade

Corpo da requisição

state_iduuidobrigatório

Estado dono.

namestringobrigatório

Nome da cidade.

ibge_codestring

Código IBGE, exatamente 7 dígitos. Opcional, mas único na loja quando informado.

201Cidade criada

json

{
  "id": "2d1f5d0e-7c0b-4a46-bb0d-0d9d6c9e1a42",
  "state_id": "55766ae5-4725-4971-b1bb-29686b7cc492",
  "state_name": "São Paulo",
  "state_code": "SP",
  "name": "Vila Nova Exemplo",
  "ibge_code": "3599999"
}

Alterar cidade

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

Altera nome ou código IBGE de uma cidade

Alteração parcial. O estado da cidade não pode ser trocado. Enviar ibge_code vazio ("") apaga o código.

Parâmetros de caminho

iduuidobrigatório

Id da cidade.

Corpo da requisição

namestring

Novo nome.

ibge_codestring

Novo código IBGE (7 dígitos, único) ou vazio para limpar.

A resposta 200 é a cidade atualizada.

Excluir cidade

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

Exclui uma cidade sem bairros

Parâmetros de caminho

iduuidobrigatório

Id da cidade.

200Cidade excluída

json

{ "message": "city deleted" }

Erros

Status	Quando	Corpo
400	JSON inválido; `state_id` ou `name` ausente; `ibge_code` fora do padrão	`{"error":"ibge_code must be a 7-digit number"}`
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":"city not found"}`
409	Criar com código IBGE já usado; excluir cidade com bairros	`{"error":"ibge code already exists","detail":"a city with this ibge_code already exists"}` ou `{"error":"city has dependent records","detail":"delete or reassign districts first"}`
500	Id que não é UUID, `state_id` inexistente na criação, excluir id que não existe, ou atualização com `ibge_code` fora do formato de 7 dígitos ou já em uso (a atualização não devolve 400 nem 409)	`{"error":"failed to get city","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Veja também

API atual/Referência completa/Locais

Cidades

Lista paginada, consulta, criação, alteração e exclusão de cidades (municípios) de um estado.

Listar cidades

GET/api/v1/admin/locations/citiesAdmin

Lista cidades com paginação

Ordenadas pelo nome. Para montar um seletor de cidades de um estado inteiro, filtre por state_id e use per_page=1000.

Parâmetros de consulta

state_iduuid

Somente cidades deste estado.

searchstring

Texto contido no nome da cidade, sem diferenciar maiúsculas (campinas).

sort_dirstringpadrão: asc

ascdesc

Direção da ordenação por nome.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página. O máximo é 1000: valores maiores são reduzidos a 1000, valores menores que 1 voltam a 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/locations/cities?search=campinas&per_page=2" \
  -H "Authorization: Bearer $TOKEN"

200Cidades retornadas

json

{
  "cities": [
    {
      "id": "6b4323c6-b531-4042-a72c-5afa1d9e0afd",
      "state_id": "55766ae5-4725-4971-b1bb-29686b7cc492",
      "state_name": "São Paulo",
      "state_code": "SP",
      "name": "Campinas",
      "ibge_code": "3509502"
    }
  ],
  "total": 3,
  "page": 1,
  "per_page": 2,
  "total_pages": 2
}

Campos da resposta

cities[].iduuid

Identificador da cidade.

cities[].state_iduuid

Estado dono.

cities[].state_namestring

Nome do estado. Só aparece nas listagens e na consulta.

cities[].state_codestring

Sigla do estado (SP).

cities[].namestring

Nome da cidade.

cities[].ibge_codestring

Código IBGE de 7 dígitos. Pode ser vazio.

totalinteger

Total de cidades que atendem ao filtro, em todas as páginas.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Consultar cidade

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

Consulta uma cidade pelo id

Parâmetros de caminho

iduuidobrigatório

Id da cidade.

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

Criar cidade

POST/api/v1/admin/locations/citiesAdmin

Cadastra uma cidade

Corpo da requisição

state_iduuidobrigatório

Estado dono.

namestringobrigatório

Nome da cidade.

ibge_codestring

Código IBGE, exatamente 7 dígitos. Opcional, mas único na loja quando informado.

201Cidade criada

json

{
  "id": "2d1f5d0e-7c0b-4a46-bb0d-0d9d6c9e1a42",
  "state_id": "55766ae5-4725-4971-b1bb-29686b7cc492",
  "state_name": "São Paulo",
  "state_code": "SP",
  "name": "Vila Nova Exemplo",
  "ibge_code": "3599999"
}

Alterar cidade

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

Altera nome ou código IBGE de uma cidade

Alteração parcial. O estado da cidade não pode ser trocado. Enviar ibge_code vazio ("") apaga o código.

Parâmetros de caminho

iduuidobrigatório

Id da cidade.

Corpo da requisição

namestring

Novo nome.

ibge_codestring

Novo código IBGE (7 dígitos, único) ou vazio para limpar.

A resposta 200 é a cidade atualizada.

Excluir cidade

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

Exclui uma cidade sem bairros

Parâmetros de caminho

iduuidobrigatório

Id da cidade.

200Cidade excluída

json

{ "message": "city deleted" }

Erros

Status	Quando	Corpo
400	JSON inválido; `state_id` ou `name` ausente; `ibge_code` fora do padrão	`{"error":"ibge_code must be a 7-digit number"}`
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":"city not found"}`
409	Criar com código IBGE já usado; excluir cidade com bairros	`{"error":"ibge code already exists","detail":"a city with this ibge_code already exists"}` ou `{"error":"city has dependent records","detail":"delete or reassign districts first"}`
500	Id que não é UUID, `state_id` inexistente na criação, excluir id que não existe, ou atualização com `ibge_code` fora do formato de 7 dígitos ou já em uso (a atualização não devolve 400 nem 409)	`{"error":"failed to get city","detail":"o valor \"abc\" não é um uuid válido. ..."}`