> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de organizações

> Referência interna para a API de organizações — CRUD, gerenciamento de membros, configurações e metadados do plano.

> **Documentação interna para desenvolvedores.** Esta página abrange endpoints de gerenciamento da organização, operações de associação e gerenciamento de configurações. Não se destina a usuários finais.

***

## Mapa de rotas

| Método   | Ponto final                      | Arquivo manipulador                  | Descrição                                |
| -------- | -------------------------------- | ------------------------------------ | ---------------------------------------- |
| `GET`    | `/api/organizations`             | `organizations/route.ts`             | Listar organizações para o usuário atual |
| `POST`   | `/api/organizations`             | `organizations/route.ts`             | Crie uma nova organização                |
| `GET`    | `/api/organizations/[id]`        | `organizations/[id]/route.ts`        | Obter organização por ID                 |
| `PATCH`  | `/api/organizations/[id]`        | `organizations/[id]/route.ts`        | Atualizar configurações da organização   |
| `DELETE` | `/api/organizations/[id]`        | `organizations/[id]/route.ts`        | Excluir organização                      |
| `GET`    | `/api/organizations/current`     | `organizations/current/route.ts`     | Obtenha a organização ativa atual        |
| `GET`    | `/api/organizations/[id]/invite` | `organizations/[id]/invite/route.ts` | Listar convites pendentes                |
| `POST`   | `/api/organizations/[id]/invite` | `organizations/[id]/invite/route.ts` | Enviar convite                           |

***

## Padrão de autenticação

Os endpoints da organização usam o padrão `withPermissionRoute`. A maioria das operações de gravação no nível da organização exige permissões de nível `org.manage` ou `admin`.

**O isolamento da organização é aplicado no nível da sessão:** `req.session.organization.id` é a organização ativa. O acesso entre organizações é bloqueado pela camada de permissão.

***

## Organização Atual

O endpoint `current` é um auxiliar leve usado pelo frontend para obter a organização ativa sem saber seu ID antecipadamente:

```ts theme={null}
// GET /api/organizations/current
// Returns: current active org based on session
// authMode: 'lightweight' — no extra DB round-trip
```

***

## Fluxo de convite

```ts theme={null}
// POST /api/organizations/[id]/invite
// Body: { email: string, accessGroupId: string, role?: string }
// 1. Creates pending Membership with status='invited'
// 2. Sends invitation email via @zappway/lib/email
// 3. Returns { invitation, membership }
```

Os tokens de convite têm vida curta (72 horas por padrão). Após a expiração, o convidado deve ser convidado novamente.

***

## Configurações da organização (PATCH)

O endpoint `PATCH /api/organizations/[id]` aceita:

| Campo            | Tipo       | Descrição                                        |
| ---------------- | ---------- | ------------------------------------------------ |
| `name`           | `string`   | Nome de exibição                                 |
| `logo`           | `string`   | URL do logotipo                                  |
| `timezone`       | `string`   | Fuso horário padrão                              |
| `locale`         | `string`   | Localidade padrão (`en`, `pt-BR`, `es`)          |
| `allowedDomains` | `string[]` | Restringir inscrições a estes domínios de e-mail |

***

## Problemas conhecidos/pegadinhas

* **A exclusão da organização** é uma operação destrutiva que se espalha para TODOS os recursos da organização (agentes, contatos, conversas, armazenamentos de dados). Protegido por uma etapa de confirmação na IU. O back-end deve verificar se `DELETE` é intencional.
* **`current` endpoint** deve ser invalidado/rebuscado após `update-org` (troca de sessão de autenticação).
* **Usuários de várias organizações** veem várias organizações no seletor de organização. A lista `GET /api/organizations` tem como escopo as associações onde `status='active'`.