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

200Cidades retornadas

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

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

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

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

200Cidades retornadas

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

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

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