Endpoints
States
CRUD de estados (UFs) — dados geográficos de referência.
Unidades federativas (dados de referência). Identificadas pelo código IBGE do estado
(stateCode). Base path: /api/states · autenticação de usuário.
| Método | Rota | Scope | Resource | Sucesso |
|---|---|---|---|---|
POST | /api/states | create | resource:states | 201 |
GET | /api/states | read | resource:states | 200 |
GET | /api/states/:stateCode | read | resource:states_id | 200 |
PUT | /api/states/:stateCode | update | resource:states_id | 200 |
DELETE | /api/states/:stateCode | delete | resource:states_id | 204 |
Criar estado
POST /api/states — a chave primária (stateCode) é informada no corpo, não gerada.
Corpo
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
stateCode | integer | sim | código IBGE do estado; único (409) |
uf | string | sim | exatamente 2 caracteres; único (409) |
name | string | sim | mín. 1 caractere |
latitude | number | sim | |
longitude | number | sim | |
region | string | sim | mín. 1 caractere (ex.: Sudeste) |
curl -X POST http://localhost:3000/api/states \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"stateCode": 35,
"uf": "SP",
"name": "São Paulo",
"latitude": -23.5505,
"longitude": -46.6333,
"region": "Sudeste"
}'201 Created
{
"stateCode": 35,
"uf": "SP",
"name": "São Paulo",
"latitude": -23.5505,
"longitude": -46.6333,
"region": "Sudeste"
}409 Conflict — já existe um estado com esse stateCode ou uf.
Listar estados
GET /api/states — lista paginada (page, limit), ordenada por nome.
Filtros opcionais: name (contém), uf, region.
curl "http://localhost:3000/api/states?region=Sudeste" \
-H "Authorization: Bearer $ACCESS_TOKEN"Obter estado por código
GET /api/states/:stateCode — 404 se não existir.
Editar estado
PUT /api/states/:stateCode — atualização parcial (o stateCode não muda).
| Campo | Tipo | Regras |
|---|---|---|
uf | string | exatamente 2 caracteres |
name | string | mín. 1 caractere |
latitude | number | |
longitude | number | |
region | string | mín. 1 caractere |
Retorna 200; 404 se não existir.
Remover estado
DELETE /api/states/:stateCode — retorna 204 No Content.