> ## 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 organizaciones

> Referencia interna para la API de Organizaciones: CRUD, administración de miembros, configuración y metadatos del plan.

> **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:

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

***

## Flujo de invitación

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

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