Cities
CRUD de cidades (municípios) — dados geográficos de referência.
Municípios (dados de referência), vinculados a um estado. Identificados pelo código IBGE
(ibgeCode). Base path: /api/cities · autenticação de usuário.
| Método | Rota | Scope | Resource | Sucesso |
|---|---|---|---|---|
POST | /api/cities | create | resource:cities | 201 |
GET | /api/cities | read | resource:cities | 200 |
GET | /api/cities/:ibgeCode | read | resource:cities_id | 200 |
PUT | /api/cities/:ibgeCode | update | resource:cities_id | 200 |
DELETE | /api/cities/:ibgeCode | delete | resource:cities_id | 204 |
Criar cidade
POST /api/cities — a chave primária (ibgeCode) é informada no corpo, não gerada.
Corpo
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
ibgeCode | integer | sim | código IBGE do município; único (409) |
name | string | sim | mín. 1 caractere |
latitude | number | sim | |
longitude | number | sim | |
capital | boolean | sim | se é capital do estado |
stateCode | integer | sim | estado existente (400 se não existir) |
siafiId | string | sim | 1 a 4 caracteres; único (409) |
ddd | integer | sim | código de DDD |
timeZone | string | sim | ex.: America/Sao_Paulo |
curl -X POST http://localhost:3000/api/cities \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ibgeCode": 3550308,
"name": "São Paulo",
"latitude": -23.5505,
"longitude": -46.6333,
"capital": true,
"stateCode": 35,
"siafiId": "7107",
"ddd": 11,
"timeZone": "America/Sao_Paulo"
}'201 Created
{
"ibgeCode": 3550308,
"name": "São Paulo",
"latitude": -23.5505,
"longitude": -46.6333,
"capital": true,
"stateCode": 35,
"siafiId": "7107",
"ddd": 11,
"timeZone": "America/Sao_Paulo"
}409 Conflict — já existe uma cidade com esse ibgeCode ou siafiId.
400 Bad Request — o stateCode informado não existe (StateNotFoundError).
Listar cidades
GET /api/cities — lista paginada (page, limit), ordenada por nome.
Filtros opcionais: name (contém), stateCode, capital (true | false).
curl "http://localhost:3000/api/cities?stateCode=35&capital=true" \
-H "Authorization: Bearer $ACCESS_TOKEN"Obter cidade por código
GET /api/cities/:ibgeCode — 404 se não existir.
Editar cidade
PUT /api/cities/:ibgeCode — atualização parcial (o ibgeCode não muda).
| Campo | Tipo | Regras |
|---|---|---|
name | string | mín. 1 caractere |
latitude | number | |
longitude | number | |
capital | boolean | |
stateCode | integer | estado existente (400 se não existir) |
siafiId | string | 1 a 4 caracteres |
ddd | integer | |
timeZone | string | mín. 1 caractere |
Retorna 200; 404 se a cidade não existir; 400 se o stateCode informado não existir.
Remover cidade
DELETE /api/cities/:ibgeCode — retorna 204 No Content.