Organizations

CRUD de organizações (cooperativas), a raiz do agregado de endereços e contatos.

Organizações / cooperativas. Raiz do agregado que inclui endereços e contatos. Base path: /api/organizations · autenticação de usuário. Consulta e criação também estão disponíveis app-to-app em /service/organizations — ver App-to-app.

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

Criar organização

POST /api/organizations — transacional: cria a organização, o endereço vigente (obrigatório) e os contatos (opcionais) numa única operação tudo-ou-nada. Não é possível criar uma organização sem endereço.

Corpo

Campo	Tipo	Obrigatório	Regras
`name`	string	sim	mín. 1 caractere
`alias`	string	não	ou `null`
`federalTaxId`	string	sim	11 a 14 caracteres; único (`409`)
`stateTaxId`	string	não	ou `null`
`municipalTaxId`	string	não	ou `null`
`logoPath`	string	não	ou `null`
`active`	boolean	não	padrão `true`
`listed`	boolean	não	padrão `true` (visível publicamente)
`metadata`	object	não	mapa livre; ou `null`
`address`	object	sim	endereço vigente inicial (ver abaixo)
`contacts`	array	não	contatos iniciais (ver abaixo)

address (obrigatório)

Campo	Tipo	Obrigatório	Regras
`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	ou `null`
`district`	string	não	máx. 50; ou `null`
`cityCode`	integer	sim	código IBGE; cidade existente (`400`)
`stateCode`	integer	sim	estado existente (`400`); a cidade deve pertencer a ele (`400`)
`country`	string	não	padrão `Brasil`
`latitude`	number	não	ou `null`
`longitude`	number	não	ou `null`

contacts[] (opcional)

Campo	Tipo	Obrigatório	Regras
`type`	enum	sim	`PHONE` \| `EMAIL` \| `URL`
`value`	string	sim	mín. 1 caractere
`description`	string	não	ou `null`
`isPrimary`	boolean	não	padrão `false`

curl -X POST http://localhost:3000/api/organizations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cooperativa Recicla Já",
    "alias": "Recicla Já",
    "federalTaxId": "12345678000190",
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "cityCode": 3550308,
      "stateCode": 35
    },
    "contacts": [
      { "type": "EMAIL", "value": "contato@reciclaja.org", "isPrimary": true }
    ]
  }'

201 Created — retorna a organização (com organizationAddressId já apontando para o endereço criado). Endereços e contatos são consultados nos seus próprios recursos.

{
  "id": "o1b2c3d4-e5f6-4789-a123-456789abcdef",
  "name": "Cooperativa Recicla Já",
  "alias": "Recicla Já",
  "federalTaxId": "12345678000190",
  "stateTaxId": null,
  "municipalTaxId": null,
  "logoPath": null,
  "active": true,
  "listed": true,
  "metadata": null,
  "organizationAddressId": "a1b2c3d4-e5f6-4789-a123-456789abcdef",
  "createdAt": "2026-07-13T12:00:00.000Z",
  "updatedAt": "2026-07-13T12:00:00.000Z"
}

409 Conflict — já existe uma organização com esse federalTaxId.

400 Bad Request — endereço inválido: stateCode ou cityCode inexistente, ou a cidade não pertence ao estado informado. Como é transacional, nada é criado nesses casos.

Depois de criada, endereços (com histórico de vigência) e contatos são gerenciados pelos recursos organization-addresses e organization-contacts.

Listar organizações

GET /api/organizations — lista paginada (page, limit).

Filtros opcionais: name (contém), active (true | false), listed (true | false).

Obter organização por id

GET /api/organizations/:id — 404 se não existir.

Editar organização

PUT /api/organizations/:id — atualização parcial. O federalTaxId não é editável.

Campo	Tipo	Regras
`name`	string	mín. 1 caractere
`alias`	string	ou `null`
`stateTaxId`	string	ou `null`
`municipalTaxId`	string	ou `null`
`logoPath`	string	ou `null`
`active`	boolean
`listed`	boolean
`metadata`	object	ou `null`

Retorna 200; 404 se não existir.

Remover organização

DELETE /api/organizations/:id — soft delete (deletedAt). Retorna 204 No Content. Organizações removidas deixam de aparecer nas listagens e buscas.

App-to-app (`/service`)

Além do prefixo /api (usuário final), a consulta e a criação de organizações também estão disponíveis para serviços (app-to-app), autenticados pelo ServiceAuthMiddleware (client credentials do Keycloak). São os mesmos use case, validações e formato dos endpoints /api — muda só o prefixo e o mecanismo de autenticação; aqui não há o PermissionGuard por escopo de usuário.

Método	Rota	Sucesso	Equivale a
`GET`	`/service/organizations`	`200`	`GET /api/organizations`
`POST`	`/service/organizations`	`201`	`POST /api/organizations`

GET /service/organizations — mesma paginação e filtros (page, limit, name, active, listed) e o mesmo envelope de resposta.
POST /service/organizations — mesmo corpo transacional (organização + address obrigatório + contacts opcionais) e os mesmos erros (409 para federalTaxId duplicado, 400 para endereço inválido).

Obter por id, editar e remover não têm variante /service — apenas consulta e criação.