States

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	Ação (role)	Sucesso
`POST`	`/api/states`	`create`	`resource:states`	`create`	`201`
`GET`	`/api/states`	`read`	`resource:states`	`read`	`200`
`GET`	`/api/states/:stateCode`	`read`	`resource:states_id`	`read`	`200`
`PUT`	`/api/states/:stateCode`	`update`	`resource:states_id`	`update`	`200`
`DELETE`	`/api/states/:stateCode`	`delete`	`resource:states_id`	`delete`	`204`

Controle de acesso por persona. Personas global e tenant-admin liberam tudo em states. coordinator, technician e viewer têm apenas leitura pela matriz — o catálogo geográfico alimenta os selects de UF/cidade no cadastro de organização e de endereço. Criar, editar e excluir seguem restritos a global/tenant-admin (só via role de exceção states:acao). Token sem role suficiente → 403 NOT_ALLOWED.

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

Erros

Status	`code`	Quando
`409`	`STATE_ALREADY_EXISTS`	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

Erros

Status	`code`	Quando
`404`	`STATE_NOT_FOUND`	Estado não existe

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.

Erros

Status	`code`	Quando
`404`	`STATE_NOT_FOUND`	Estado não existe

Remover estado

DELETE /api/states/:stateCode — retorna 204 No Content.

Erros

Status	`code`	Quando
`404`	`STATE_NOT_FOUND`	Estado não existe

App-to-app (`/service`)

As consultas de estado estão disponíveis para serviços (app-to-app), autenticadas pelo ServiceAuthMiddleware. Mesmos use case e presenter dos endpoints /api.

Método	Rota	Ação (role)	Sucesso	Equivale a
`GET`	`/service/states`	`read`	`200`	`GET /api/states`
`GET`	`/service/states/:stateCode`	`read`	`200`	`GET /api/states/:stateCode`

Estado é dado de referência global (tabela do IBGE): não tem organizationId, então o filtro por organização não se aplica e todo tenant vê a mesma lista. Criar, editar e remover não têm variante /service — a manutenção da tabela é do painel.

Criar estado

Listar estados

Obter estado por código

Editar estado

Remover estado

App-to-app (/service)

On this page

App-to-app (`/service`)