API de organizações

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:

// GET /api/organizations/current
// Returns: current active org based on session
// authMode: 'lightweight' — no extra DB round-trip

Fluxo de convite

// 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'.

API Internals

Infrastructure

Mapa de rotas

Padrão de autenticação

Organização Atual

Fluxo de convite

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

Problemas conhecidos/pegadinhas

​Mapa de rotas

​Padrão de autenticação

​Organização Atual

​Fluxo de convite

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

​Problemas conhecidos/pegadinhas

Mapa de rotas

Padrão de autenticação

Organização Atual

Fluxo de convite

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

Problemas conhecidos/pegadinhas