Organization Addresses

Endereços de uma organização com controle temporal (validFrom / validTo). Base path: /api/organization-addresses · autenticação de usuário.

Método	Rota	Scope	Resource	Sucesso
`POST`	`/api/organization-addresses`	`create`	`resource:organization-addresses`	`201`
`GET`	`/api/organization-addresses`	`read`	`resource:organization-addresses`	`200`
`GET`	`/api/organization-addresses/:id`	`read`	`resource:organization-addresses_id`	`200`
`PUT`	`/api/organization-addresses/:id`	`update`	`resource:organization-addresses_id`	`200`
`DELETE`	`/api/organization-addresses/:id`	`delete`	`resource:organization-addresses_id`	`204`

Criar endereço

POST /api/organization-addresses — define um novo endereço vigente para a organização.

Ao criar, o endereço atual (com validTo = null) é encerrado: seu validTo passa a ser o validFrom do novo endereço. A organização tem organizationAddressId atualizado para o novo registro.

Corpo

Campo	Tipo	Obrigatório	Regras
`organizationId`	uuid	sim	Organização existente (`404` se não existir)
`zipCode`	string	sim	exatamente 8 caracteres (CEP)
`street`	string	sim	mín. 1 caractere
`number`	string	sim	mín. 1 caractere
`complement`	string	não	pode ser `null`
`district`	string	não	máx. 50 caracteres; pode ser `null`
`cityCode`	integer	sim	Código IBGE; cidade existente (`404` se não existir)
`stateCode`	integer	sim	Código do estado; estado existente (`404` se não existir)
`country`	string	não	padrão `Brasil`; máx. 50 caracteres
`latitude`	number	não	pode ser `null`
`longitude`	number	não	pode ser `null`

curl -X POST http://localhost:3000/api/organization-addresses \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "o1b2c3d4-e5f6-4789-a123-456789abcdef",
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "district": "Bela Vista",
    "cityCode": 3550308,
    "stateCode": 35,
    "latitude": -23.561414,
    "longitude": -46.655881
  }'

201 Created

{
  "id": "a1b2c3d4-e5f6-4789-a123-456789abcdef",
  "organizationId": "o1b2c3d4-e5f6-4789-a123-456789abcdef",
  "zipCode": "01310100",
  "street": "Avenida Paulista",
  "number": "1000",
  "complement": null,
  "district": "Bela Vista",
  "cityCode": 3550308,
  "stateCode": 35,
  "country": "Brasil",
  "latitude": -23.561414,
  "longitude": -46.655881,
  "validFrom": "2026-07-13T12:00:00.000Z",
  "validTo": null
}

404 Not Found — organizationId, stateCode ou cityCode inexistentes.

400 Bad Request — a cidade informada não pertence ao estado (CityStateMismatchError).

Listar endereços

GET /api/organization-addresses — lista paginada (page, limit).

Filtros opcionais: organizationId (uuid), cityCode, stateCode, currentOnly (true | false — apenas endereços vigentes com validTo = null).

Obter endereço por id

GET /api/organization-addresses/:id — 404 se não existir.

Editar endereço

PUT /api/organization-addresses/:id — atualização parcial apenas do endereço vigente (validTo = null). Para trocar de endereço mantendo histórico, crie um novo via POST.

Campo	Tipo	Regras
`zipCode`	string	exatamente 8 caracteres
`street`	string	mín. 1 caractere
`number`	string	mín. 1 caractere
`complement`	string	ou `null`
`district`	string	máx. 50 caracteres; ou `null`
`cityCode`	integer	cidade existente; deve pertencer ao `stateCode` informado
`stateCode`	integer	estado existente
`country`	string	máx. 50 caracteres; ou `null`
`latitude`	number	ou `null`
`longitude`	number	ou `null`

Retorna 200; 404 se não existir; 400 se o endereço não for o vigente ou se cidade/estado forem incompatíveis.

Remover endereço

DELETE /api/organization-addresses/:id — retorna 204 No Content. Se o endereço removido for o vigente, organizationAddressId da organização é limpo (null).

Criar endereço

Listar endereços

Obter endereço por id

Editar endereço

Remover endereço

On this page