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

Controle de acesso por persona. Personas global e tenant-admin liberam tudo em organization-addresses. coordinator e technician podem ler, criar e editar — mesmo escopo que já têm em organizations, já que o endereço é sub-recurso da organização; viewer só lê. delete fica fora do padrão para as três, só via role de exceção organization-addresses:delete. Token sem role suficiente → 403 NOT_ALLOWED.

Para coordinator e technician a listagem é filtrada automaticamente pelas organizations alcançadas pelos tenants do usuário.

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
}

Erros

Status	`code`	Quando
`404`	`ORGANIZATION_NOT_FOUND` · `STATE_NOT_FOUND` · `CITY_NOT_FOUND`	`organizationId`, `stateCode` ou `cityCode` inexistentes
`403`	`NOT_ALLOWED_ORGANIZATION`	`organizationId` fora do escopo de cooperativas do usuário (`IUser.allowedOrganizationIds`)
`400`	`CITY_STATE_MISMATCH`	A cidade informada não pertence ao estado

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

Erros

Status	`code`	Quando
`404`	`ORGANIZATION_ADDRESS_NOT_FOUND`	Endereço não existe

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.

Erros

Status	`code`	Quando
`404`	`ORGANIZATION_ADDRESS_NOT_FOUND` · `STATE_NOT_FOUND` · `CITY_NOT_FOUND`	Endereço, estado ou cidade inexistentes
`400`	`ORGANIZATION_ADDRESS_NOT_CURRENT`	O endereço não é o vigente da organização
`400`	`CITY_STATE_MISMATCH`	A cidade informada não pertence ao estado

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).

Erros

Status	`code`	Quando
`404`	`ORGANIZATION_ADDRESS_NOT_FOUND`	Endereço não existe

Criar endereço

Listar endereços

Obter endereço por id

Editar endereço

Remover endereço

On this page