API de organizaciones

Documentación interna para desarrolladores. Esta página cubre los puntos finales de administración de la organización, las operaciones de membresía y la administración de configuraciones. No está destinado a usuarios finales.

Mapa de ruta

Método	Punto final	Archivo de controlador	Descripción
`GET`	`/api/organizations`	`organizations/route.ts`	Listar organizaciones para el usuario actual
`POST`	`/api/organizations`	`organizations/route.ts`	Crear una nueva organización
`GET`	`/api/organizations/[id]`	`organizations/[id]/route.ts`	Obtener organización por ID
`PATCH`	`/api/organizations/[id]`	`organizations/[id]/route.ts`	Actualizar la configuración de la organización
`DELETE`	`/api/organizations/[id]`	`organizations/[id]/route.ts`	Eliminar organización
`GET`	`/api/organizations/current`	`organizations/current/route.ts`	Obtener organización activa actual
`GET`	`/api/organizations/[id]/invite`	`organizations/[id]/invite/route.ts`	Lista de invitaciones pendientes
`POST`	`/api/organizations/[id]/invite`	`organizations/[id]/invite/route.ts`	Enviar invitación

Patrón de autenticación

Los puntos finales de la organización utilizan el estándar withPermissionRoute. La mayoría de las operaciones de escritura a nivel de organización requieren permisos de nivel org.manage o admin. El aislamiento de la organización se aplica a nivel de sesión: req.session.organization.id es la organización activa. El acceso entre organizaciones está bloqueado por la capa de permiso.

Organización actual

El punto final current es un asistente liviano utilizado por el frontend para obtener la organización activa sin conocer su ID por adelantado:

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

Flujo de invitación

// 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 }

Los tokens de invitación son de corta duración (72 horas de forma predeterminada). Una vez vencido, se debe volver a invitar al invitado.

Configuración de la organización (PARCHE)

El punto final PATCH /api/organizations/[id] acepta:

Campo	Tipo	Descripción
`name`	`string`	Nombre para mostrar
`logo`	`string`	URL del logotipo
`timezone`	`string`	Zona horaria predeterminada
`locale`	`string`	Configuración regional predeterminada (`en`, `pt-BR`, `es`)
`allowedDomains`	`string[]`	Restringir registros a estos dominios de correo electrónico

Problemas conocidos / Problemas

Eliminación de la organización es una operación destructiva que se aplica en cascada a TODOS los recursos de la organización (agentes, contactos, conversaciones, almacenes de datos). Protegido por un paso de confirmación en la interfaz de usuario. El backend debe verificar que DELETE sea intencional.
current el punto final debe invalidarse o recuperarse después de update-org (cambio de sesión de autenticación).
Los usuarios de varias organizaciones ven varias organizaciones en el selector de organizaciones. La lista GET /api/organizations tiene como alcance las membresías donde status='active'.

API Internals

Infrastructure

Mapa de ruta

Patrón de autenticación

Organización actual

Flujo de invitación

Configuración de la organización (PARCHE)

Problemas conocidos / Problemas

​Mapa de ruta

​Patrón de autenticación

​Organización actual

​Flujo de invitación

​Configuración de la organización (PARCHE)

​Problemas conocidos / Problemas

Mapa de ruta

Patrón de autenticación

Organización actual

Flujo de invitación

Configuración de la organización (PARCHE)

Problemas conocidos / Problemas