# Mosend WB API — referencia completa para LLMs

Base URL: https://api.mosend.dev
Auth: header `X-Api-Key: mk_live_<prefix>.<secret>` o `Authorization: Bearer <jwt>`.
Toda respuesta viene como { "data": ... }. Rutas multi-tenant: /organizations/{orgId}/...

## Guía: Introducción
Qué es la API de Mosend y cómo empezar. — https://developer.mosend.dev/

## Guía: Autenticación
Bearer JWT y API Keys (con scopes y restricción por número). — https://developer.mosend.dev/auth

## Guía: URL base
Host, versionado y formato de respuestas { data }. — https://developer.mosend.dev/url-base

## Guía: Enviar una plantilla
Quickstart: enviar una plantilla aprobada a un número. — https://developer.mosend.dev/enviar-plantilla

## Guía: Enviar un broadcast
Envío masivo a listas/contactos, conteos y filtros de destinatarios. — https://developer.mosend.dev/enviar-broadcast

## Guía: Plantillas OTP
Plantillas de autenticación con botón COPY_CODE. — https://developer.mosend.dev/templates/otp

## Guía: Handoff a humano
Derivar una conversación de un bot externo a un asesor. — https://developer.mosend.dev/handoff

## Guía: Webhooks salientes
Eventos firmados con HMAC, scope por número, conversation.unanswered. — https://developer.mosend.dev/webhooks-out

## Guía: Identidad del widget
Identificar visitantes del web-chat con hash HMAC. — https://developer.mosend.dev/widget/identity

## Guía: Knowledge base (RAG)
Subir documentos para el agente IA. — https://developer.mosend.dev/bot/knowledge

## Guía: Construir con agentes de IA
Instrucciones canónicas para que un LLM construya contra la API. — https://developer.mosend.dev/agents

## Guía: Errores
Códigos de error y cómo resolverlos. — https://developer.mosend.dev/errors

## Guía: Cambios recientes
Novedades de la API por fecha. — https://developer.mosend.dev/changelog

## Add-ons (/organizations/:orgId/billing/addons)
### GET /organizations/:orgId/billing/addons
Catálogo de add-ons del plan + cantidades contratadas.

### POST /organizations/:orgId/billing/addons/preview
Previsualiza el prorrateo y el impacto en el wallet.

### PATCH /organizations/:orgId/billing/addons
Contrata o reduce un add-on. Los aumentos exigen saldo suficiente en el wallet.

## API Keys (/organizations/:orgId/api-keys)
### GET /organizations/:orgId/api-keys
Lista las API keys de la organización (sin el secret).

### POST /organizations/:orgId/api-keys
Crear API key. Devuelve `secret` UNA sola vez.
Body:
- name (requerido): string
- scopes: string[]
- phoneNumberIds: string[] — Restricción opcional a un subconjunto de phone-numbers de la org. Vacío
o ausente = la key opera sobre TODOS los phone-numbers (default). Si
trae UUIDs, la key SOLO puede enviar/leer de esos números.

### PATCH /organizations/:orgId/api-keys/:id
Editar API key: scopes y/o nombre. El secret NO se puede tocar — para rotar, revocar y crear otra.
Body:
- name: string
- scopes: string[]
- phoneNumberIds: string[]

### DELETE /organizations/:orgId/api-keys/:id
Revoca una API key de forma permanente.

## Audit (/)
### GET /organizations/:orgId/audit
Cliente final: lista de logs de SU organización con filtros.
Query params:
- action: string
- resource: string
- actorUserId: string
- dateFrom: string
- dateTo: string
- cursor: string
- limit: string

### GET /organizations/:orgId/audit/export
Exporta el audit log en CSV (requiere audit_advanced).
Query params:
- action: string
- resource: string
- actorUserId: string
- dateFrom: string
- dateTo: string

### GET /admin/audit
Admin staff: cross-org audit con todos los filtros.
Query params:
- orgId: string
- action: string
- resource: string
- actorUserId: string
- dateFrom: string
- dateTo: string
- cursor: string
- limit: string

### GET /admin/audit/export
Admin staff: export CSV cross-org (sin feature gate, siempre permitido).
Query params:
- orgId: string
- action: string
- resource: string
- dateFrom: string
- dateTo: string

## Auth (/auth)
### POST /auth/signup
Crear cuenta de usuario
Auth: pública (sin token).
Body:
- email (requerido): string
- password (requerido): string
- name (requerido): string

### POST /auth/login
Iniciar sesión
Auth: pública (sin token).
Body:
- email (requerido): string
- password (requerido): string
- twoFactorCode: string

### POST /auth/refresh
Renovar tokens (rotación)
Auth: pública (sin token).
Body:
- refreshToken (requerido): string

### POST /auth/logout
Cerrar sesión (revoca el refresh token)
Auth: pública (sin token).
Body:
- refreshToken (requerido): string

### POST /auth/forgot-password
Solicita un email de recuperación de contraseña. Por seguridad SIEMPRE responde 200 — no revela si el email existe o no en el sistema.
Auth: pública (sin token).
Body:
- email (requerido): string

### POST /auth/reset-password
Canjea el token recibido por email + nueva contraseña. Si el token es inválido/expirado lanza 401. Tras éxito se revocan todas las sesiones activas del usuario (logout en todos los dispositivos).
Auth: pública (sin token).
Body:
- token (requerido): string
- password (requerido): string

### POST /auth/impersonate-redeem
Canjea un ImpersonationToken (creado por staff via /admin/impersonate) por una sesión válida del target user. El JWT resultante lleva el flag `impersonatedBy` para que el frontend muestre banner persistente.
Auth: pública (sin token).
Body:
- token (requerido): string

## Billing (/organizations/:orgId/billing)
### GET /organizations/:orgId/billing/periods
Lista los periodos de facturación de la organización.

### GET /organizations/:orgId/billing/usage
Devuelve el consumo del periodo de facturación en curso.

### GET /organizations/:orgId/billing/estimated-next-charge
Estima cuánto pagaría la organización si se cerrara hoy el periodo abierto. NO persiste.

### POST /organizations/:orgId/billing/coupons/validate
Valida un cupón sin consumirlo (previsualización del descuento).

### POST /organizations/:orgId/billing/coupons/redeem
Valida y redime un cupón a nombre de la organización.

## Billing (Alertas de saldo) (/organizations/:orgId/billing/alert-settings)
### GET /organizations/:orgId/billing/alert-settings
Devuelve configuración actual de alertas de saldo bajo y auto-recarga.

### PATCH /organizations/:orgId/billing/alert-settings
Actualiza configuración de alertas de saldo bajo y auto-recarga.
Body:
- lowBalanceThreshold: number — Umbral de saldo bajo en la moneda del wallet. Si está set y el saldo
cae al o por debajo, el cron envía una alerta. `null` desactiva la alerta.
- autoRechargeEnabled: boolean — Activa/desactiva auto-recarga. Para activar, requiere `autoRechargeAmount`
> 0, `autoRechargeCurrency` (3 chars), y que la org tenga
`autoPayMethodId` (tarjeta default registrada).
- autoRechargeAmount: number — Monto a cobrar a la tarjeta default cada vez que se dispara la auto-recarga.
- autoRechargeCurrency: string — Moneda ISO-4217 de 3 chars (USD, COP, MXN, ...).

## Bot · AI providers (BYOK) (/organizations/:orgId/bot/ai-providers)
### GET /organizations/:orgId/bot/ai-providers
Lista los 4 proveedores soportados (Anthropic, OpenAI, OpenRouter, Groq) con su estado para esta org. La API key nunca se devuelve.

### PUT /organizations/:orgId/bot/ai-providers/:provider
Crea o actualiza la config del proveedor para esta org. Recibe apiKey en plaintext, se persiste cifrada con AES-GCM.
Body:
- apiKey: string — Key en plaintext. Opcional al actualizar (mantiene la actual si no se pasa).
- enabled: boolean
- defaultModel: string — Override del modelo default. Null o '' para borrar el override.

### DELETE /organizations/:orgId/bot/ai-providers/:provider
Elimina la config del proveedor. La org vuelve a usar fallback (si existe) o queda sin key.

### POST /organizations/:orgId/bot/ai-providers/:provider/test
Verifica que la API key funciona haciendo un ping mínimo al proveedor. Persiste el resultado en lastTestedAt/lastTestError.

## Bot · Knowledge (/organizations/:orgId/bot/knowledge)
### GET /organizations/:orgId/bot/knowledge
Lista los documentos del knowledge base del bot.

### GET /organizations/:orgId/bot/knowledge/:id
Obtiene el detalle de un documento del knowledge base.

### POST /organizations/:orgId/bot/knowledge
Sube un documento. Multipart: file + opcional title, tags (coma).

### PATCH /organizations/:orgId/bot/knowledge/:id/title
Renombra un documento del knowledge base.

### PATCH /organizations/:orgId/bot/knowledge/:id/tags
Re-etiqueta un documento (afecta qué bots lo usan).

### POST /organizations/:orgId/bot/knowledge/:id/reprocess
Re-extrae texto + regenera embeddings.

### DELETE /organizations/:orgId/bot/knowledge/:id
Elimina un documento del knowledge base (chunks y objeto S3).

## Bot auto-replies (/organizations/:orgId/bot/auto-replies)
### GET /organizations/:orgId/bot/auto-replies
Lista las respuestas automáticas del bot (filtrable por número).
Query params:
- phoneNumberId: string

### POST /organizations/:orgId/bot/auto-replies
Crea una respuesta automática del bot.

### PATCH /organizations/:orgId/bot/auto-replies/:id
Actualiza una respuesta automática del bot.

### DELETE /organizations/:orgId/bot/auto-replies/:id
Elimina una respuesta automática del bot.

## Bot config (/organizations/:orgId/bot/config)
### GET /organizations/:orgId/bot/config
Lista la configuración del bot por número activo de la org.

### GET /organizations/:orgId/bot/config/:phoneId
Obtiene la configuración del bot de un número.

### PUT /organizations/:orgId/bot/config/:phoneId
Crea o actualiza la configuración del bot de un número.

### PATCH /organizations/:orgId/bot/config/:phoneId/toggle
Activa o desactiva el bot de un número (crea config con defaults si no existe).

## Bot events (/organizations/:orgId/bot/events)
### GET /organizations/:orgId/bot/events
Lista los eventos recientes del bot (filtrable por número y límite).
Query params:
- phoneNumberId: string
- limit: string

## Bot flows (/organizations/:orgId/bot/flows)
### GET /organizations/:orgId/bot/flows
Lista los flujos del bot de la org (filtrable por número).
Query params:
- phoneNumberId: string

### GET /organizations/:orgId/bot/flows/:id
Obtiene el detalle de un flujo del bot.

### POST /organizations/:orgId/bot/flows
Crea un flujo del bot.

### PATCH /organizations/:orgId/bot/flows/:id
Actualiza un flujo del bot (config y/o su JSON).

### POST /organizations/:orgId/bot/flows/:id/publish
Publica el flujo para que quede activo.

### POST /organizations/:orgId/bot/flows/:id/unpublish
Despublica el flujo (lo desactiva).

### POST /organizations/:orgId/bot/flows/:id/duplicate
Duplica un flujo existente.

### DELETE /organizations/:orgId/bot/flows/:id
Elimina un flujo del bot.

### POST /organizations/:orgId/bot/flows/:id/test-run
Ejecuta el flujo en sandbox y devuelve el trace de pasos.

## Broadcasts (/organizations/:orgId/broadcasts)
### GET /organizations/:orgId/broadcasts
Lista las difusiones (broadcasts) de la organización.

### GET /organizations/:orgId/broadcasts/:id
Detalle de una difusión, incluyendo conteos agregados (counts: total/sent/delivered/read/failed/replied).

### GET /organizations/:orgId/broadcasts/:id/recipients
Destinatarios de la difusión, filtrables por estado (para el detalle).
Query params:
- filter: string
- cursor: string
- limit: string

### POST /organizations/:orgId/broadcasts
Crea una difusión (DRAFT, o SCHEDULED si pasás scheduledAt). No envía nada todavía.

### POST /organizations/:orgId/broadcasts/:id/send
Dispara el envío: resuelve audiencia (dedup + opt-outs), valida cuota y manda. Bloquea hasta terminar.

### POST /organizations/:orgId/broadcasts/:id/cancel
Cancela una difusión DRAFT/SCHEDULED. Lo ya enviado no se desmanda.

## Business Profiles (/organizations/:orgId/phone-numbers/:phoneId/profile)
### GET /organizations/:orgId/phone-numbers/:phoneId/profile
Obtiene el perfil de negocio del número.

### PUT /organizations/:orgId/phone-numbers/:phoneId/profile
Crea o actualiza el perfil de negocio del número.

### POST /organizations/:orgId/phone-numbers/:phoneId/profile/picture
Sube una foto de perfil (JPG/PNG, máx. 5 MB) y la aplica al número en Meta.

## Contact lists (/organizations/:orgId/contact-lists)
### GET /organizations/:orgId/contact-lists
Lista las listas de contactos de la organización.

### GET /organizations/:orgId/contact-lists/:id
Obtiene el detalle de una lista de contactos por su id.

### POST /organizations/:orgId/contact-lists
Crea una nueva lista de contactos.

### PATCH /organizations/:orgId/contact-lists/:id
Actualiza nombre, descripción o color de una lista de contactos.

### DELETE /organizations/:orgId/contact-lists/:id
Archiva una lista de contactos.

### GET /organizations/:orgId/contact-lists/:id/members
Lista los contactos miembros de una lista.

### POST /organizations/:orgId/contact-lists/:id/members
Agrega contactos a una lista por sus ids.

### DELETE /organizations/:orgId/contact-lists/:id/members/:contactId
Quita un contacto de una lista.

### POST /organizations/:orgId/contact-lists/:id/add-by-tag
Agrega a la lista todos los contactos que tengan alguna de las etiquetas indicadas.

## Contacts (/organizations/:orgId/contacts)
### GET /organizations/:orgId/contacts
Lista y filtra contactos (búsqueda, canal, etiqueta, opt-in, país, actividad). Paginado.
Query params:
- q: string
- channel: string
- identifiedOnly: string
- tagId: string
- optInStatus: string
- country: string
- language: string
- createdSince: string
- hasConversations: string
- lastActivityDaysGt: string
- page: string
- pageSize: string

### POST /organizations/:orgId/contacts
Crea o actualiza un contacto (upsert por waId).
Body:
- waId (requerido): string
- name: string
- language: string
- attributes: object

### POST /organizations/:orgId/contacts/bulk-tag
Agrega o quita una etiqueta a varios contactos de una vez.

### POST /organizations/:orgId/contacts/bulk-delete
Elimina varios contactos de una vez.

### POST /organizations/:orgId/contacts/bulk-opt-in-status
Cambia el estado de opt-in (UNKNOWN/OPTED_IN/OPTED_OUT) de varios contactos.

### POST /organizations/:orgId/contacts/import
Importa contactos desde un archivo CSV (multipart/form-data, campo file).
Query params:
- defaultCountry: string
- defaultOptIn: string

### GET /organizations/:orgId/contacts/:id
Detalle de un contacto por id.

### PATCH /organizations/:orgId/contacts/:id
Actualiza campos de un contacto (nombre, atributos, idioma, etc.).
Body:
- name: string
- language: string
- attributes: object
- optInStatus: object

### DELETE /organizations/:orgId/contacts/:id
Elimina un contacto por id.

## Conversations (/organizations/:orgId/conversations)
### GET /organizations/:orgId/conversations
Lista conversaciones del inbox con filtros por estado, número, asignado, etiqueta y no leídas.
Query params:
- status: string
- phoneNumberId: string
- assigneeUserId: string
- tagId: string
- unreadOnly: string
- handoffPending: string

### GET /organizations/:orgId/conversations/messaging-settings
Obtiene los ajustes de mensajería de la org (read receipts, indicador de escritura).

### PATCH /organizations/:orgId/conversations/messaging-settings
Actualiza los ajustes de mensajería de la org (read receipts, indicador de escritura).

### GET /organizations/:orgId/conversations/unread-counts
Devuelve los conteos de no leídas por estado para los badges del inbox.
Query params:
- phoneNumberId: string

### GET /organizations/:orgId/conversations/search
Busca dentro del contenido de los mensajes de la org con filtros por fecha, dirección y adjunto.
Query params:
- q: string
- from: string
- to: string
- direction: string
- hasAttachment: string
- sentByMe: string

### GET /organizations/:orgId/conversations/workload
Lista métricas de carga y performance reciente por agente (requiere reports:read).

### GET /organizations/:orgId/conversations/workload/settings
Obtiene la configuración del panel de workload (thresholds de SLA y staleness).

### PATCH /organizations/:orgId/conversations/workload/settings
Actualiza parcialmente la configuración del panel de workload (thresholds).

### GET /organizations/:orgId/conversations/workload/agent/:userId
Detalle de workload de un agente: agregados y tenencias de los últimos N días.
Query params:
- days: string

### GET /organizations/:orgId/conversations/activity-trends
Serie temporal de conversaciones entrantes y cerradas por día (?days=N).
Query params:
- days: string

### GET /organizations/:orgId/conversations/activity-heatmap
Heatmap día-de-semana × hora de actividad (?metric=volume|late|avgResponse).
Query params:
- days: string
- metric: string

### GET /organizations/:orgId/conversations/:id
Obtiene el detalle de una conversación por su id.

### GET /organizations/:orgId/conversations/:id/messages
Lista los mensajes de una conversación con paginación por cursor.
Query params:
- limit: string
- before: string

### PATCH /organizations/:orgId/conversations/:id/status
Cambia el estado de la conversación (open/closed/snoozed); al cerrar acepta category y resolución.

### POST /organizations/:orgId/conversations/:id/request-handoff
Solicita handoff a un asesor humano: marca pendiente, calla la automatización y notifica.

### PATCH /organizations/:orgId/conversations/:id/categorize
Asigna o corrige category y resolución de la conversación sin cambiar su estado.

### POST /organizations/:orgId/conversations/:id/read
Marca la conversación como leída.

### POST /organizations/:orgId/conversations/:id/unread
Marca la conversación como no leída.

### POST /organizations/:orgId/conversations/:id/typing
Envía el indicador de "escribiendo" al contacto de la conversación.

### PATCH /organizations/:orgId/conversations/:id/assign
Asigna la conversación a un usuario o la libera (userId null).

### POST /organizations/:orgId/conversations/:id/claim
El usuario actual toma posesión de la conversación (autoasignación).

### POST /organizations/:orgId/conversations/bulk-assign
Reasigna en lote varias conversaciones a un usuario o las libera.

### PATCH /organizations/:orgId/conversations/:id/snooze
Pospone la conversación hasta una fecha, o cancela el snooze (until null).

### PATCH /organizations/:orgId/conversations/:id/pin
Fija o desfija la conversación en el inbox.

### POST /organizations/:orgId/conversations/:id/tags
Agrega una etiqueta a la conversación.

### DELETE /organizations/:orgId/conversations/:id/tags/:tagId
Quita una etiqueta de la conversación.

## Integrations (/organizations/:orgId/integrations)
### GET /organizations/:orgId/integrations
Vista resumida: API keys + webhooks outbound configurados

### GET /organizations/:orgId/integrations/catalog
Catálogo de integraciones disponibles + flag de instalación per-org. Frontend lo usa para renderizar la lista en Settings → Integraciones.

### GET /organizations/:orgId/integrations/catalog/:integrationId
Detalle de una instalación específica (sin config descifrada).

### POST /organizations/:orgId/integrations/install
Instala una integración del catálogo en la organización.
Body:
- slug (requerido): string
- config: object

### PATCH /organizations/:orgId/integrations/catalog/:integrationId
Actualiza config o toggle enabled de una instalación.
Body:
- config: object
- enabled: boolean

### DELETE /organizations/:orgId/integrations/catalog/:integrationId
Desinstala la integración (borra fila + config cifrada).

## Invitations (/)
### GET /organizations/:orgId/invitations
Lista las invitaciones de la organización.

### POST /organizations/:orgId/invitations
Crear invitación. Devuelve `token` UNA sola vez (enviar por email).
Body:
- email (requerido): string
- roleId (requerido): string

### DELETE /organizations/:orgId/invitations/:id
Cancela una invitación pendiente. Falla si ya fue aceptada.

### POST /organizations/:orgId/invitations/:id/resend
Reenvía una invitación: rota el token, refresca la expiración y vuelve a mandar el email. Falla si ya fue aceptada.

### POST /invitations/accept
Aceptar invitación con el token recibido
Body:
- token (requerido): string

## Invoices (/organizations/:orgId/invoices)
### GET /organizations/:orgId/invoices
Lista las facturas de la organización.

### GET /organizations/:orgId/invoices/:id
Obtiene el detalle de una factura por su ID.

### GET /organizations/:orgId/invoices/:id/pdf
Genera (si falta) el PDF de la factura y devuelve URL de descarga firmada.

## Leads (/public/leads)
### POST /public/leads
Sink público para el formulario de contacto de la landing.
Auth: pública (sin token).

## Media (/organizations/:orgId/media)
### GET /organizations/:orgId/media/:id
Obtiene los metadatos de un archivo de medios por su ID.

### GET /organizations/:orgId/media/:id/url
Devuelve una URL firmada de descarga del archivo de medios.

## Memberships (/organizations/:orgId/memberships)
### GET /organizations/:orgId/memberships
Lista los miembros de la organización con su rol y alcance.

### GET /organizations/:orgId/memberships/me
Devuelve la membresía del usuario actual en la organización.

### PATCH /organizations/:orgId/memberships/:id
Cambia el rol asignado a un miembro.

### PUT /organizations/:orgId/memberships/:id/waba-scope
Define a qué WABAs tiene acceso un miembro.

### DELETE /organizations/:orgId/memberships/:id
Elimina a un miembro de la organización.

## Messages (/organizations/:orgId/messages)
### POST /organizations/:orgId/messages
Envía un mensaje de WhatsApp (texto, media o plantilla) a un contacto.
Body:
- type: string [text|image|video|audio|document] — Tipo de mensaje. Si no se especifica, default 'text'.
- body: string — Texto del mensaje (requerido si type='text'; opcional como caption en otros).
- mediaAssetId: string — Id del MediaAsset previamente subido vía /web-chat/media. Requerido cuando type != 'text'.
- replyToMessageId: string — UUID del Message al que el agente responde (cita visible en widget).

### PATCH /organizations/:orgId/messages/:messageId/edit
Edita el texto de un mensaje ya enviado.

### DELETE /organizations/:orgId/messages/:messageId
Elimina un mensaje (lo oculta del inbox como tombstone).

### POST /organizations/:orgId/messages/:messageId/restore
Revierte el tombstone de un mensaje y lo vuelve a mostrar en el inbox.

### POST /organizations/:orgId/messages/upload
Sube un archivo a Meta como media adjunto y devuelve el mediaId para usar al enviar.
Query params:
- phoneNumberId (requerido): string

### GET /organizations/:orgId/messages/:messageId/media
Descarga y proxyea el media de un mensaje (sirve desde caché S3 o desde Meta).

## Notas crédito (admin) (/admin/credit-notes)
### POST /admin/credit-notes
Emite una nota crédito a favor de una organización. Solo se debería emitir cuando hubo un error nuestro.

### GET /admin/credit-notes
Lista notas crédito (filtro opcional por organización).
Query params:
- orgId: string
- limit: string

### GET /admin/credit-notes/:id
Detalle de una nota crédito.

### POST /admin/credit-notes/:id/void
Anula una nota crédito (revierte el crédito al wallet si fue aplicada).

### GET /admin/credit-notes/:id/pdf
Genera (si falta) el PDF de la nota crédito y devuelve URL firmada para descarga.

### POST /admin/credit-notes/:id/regenerate-pdf
Regenera el PDF de una nota crédito (tras tweaks de layout).

## Notifications (/notifications)
### GET /notifications
Lista las notificaciones del usuario autenticado.

### PATCH /notifications/:id/read
Marca una notificación como leída.

## Opt-ins (/organizations/:orgId/contacts/:contactId/opt-ins)
### GET /organizations/:orgId/contacts/:contactId/opt-ins
Lista el historial de opt-ins/opt-outs de un contacto.

### POST /organizations/:orgId/contacts/:contactId/opt-ins
Registra un opt-in o opt-out de un contacto.

## Organizations (/organizations)
### GET /organizations
Listar organizaciones del usuario actual

### POST /organizations
Crear organización (queda como owner)
Body:
- name (requerido): string
- slug (requerido): string
- billingEmail (requerido): string
- country: string
- currency: string
- timezone: string

### GET /organizations/slug-suggest
Sugiere un slug disponible para un nombre dado
Query params:
- name (requerido): string

### GET /organizations/slug-available
Verifica si un slug está disponible
Query params:
- slug (requerido): string

### GET /organizations/:id
Obtener organización por id

### PATCH /organizations/:id
Actualizar organización (requiere organizations:write)
Body:
- name: string
- billingEmail: string
- country: string
- currency: string
- timezone: string
- businessHoursSchedule: object

## Pagos (Mercado Pago) (/)
### POST /organizations/:orgId/wallet/recharge
Crea preference de recarga de saldo. Devuelve URL de checkout.

### POST /webhooks/mercado-pago
Webhook IPN de Mercado Pago. Valida firma y procesa pagos.
Auth: pública (sin token).
Query params:
- id: string
- type: string

### POST /organizations/:orgId/billing/invoices/:invoiceId/pay
Crea preference MP para pagar una factura. Devuelve URL de checkout.

## Pagos (Tarjetas guardadas) (/organizations/:orgId/billing)
### GET /organizations/:orgId/billing/payment-methods
Lista las tarjetas guardadas de la organización (sin exponer tokens MP).

### POST /organizations/:orgId/billing/payment-methods
Guarda una tarjeta nueva tokenizando el `token` que viene del frontend.
Body:
- token (requerido): string
- email (requerido): string
- firstName: string
- lastName: string

### DELETE /organizations/:orgId/billing/payment-methods/:id
Borra una tarjeta de MP y de la BD.

### POST /organizations/:orgId/billing/payment-methods/:id/default
Marca una tarjeta como default; las otras quedan en isDefault=false.

### GET /organizations/:orgId/billing/preferences
Estado actual de cobro automático (autoPayEnabled + autoPayMethodId).

### PATCH /organizations/:orgId/billing/auto-pay
Activa o desactiva el cobro automático mensual.
Body:
- enabled (requerido): boolean
- methodId: string

## Passkeys (/)
### POST /passkeys/registration/options
Genera las opciones WebAuthn para registrar una nueva passkey.

### POST /passkeys/registration/verify
Verifica y guarda la passkey recién registrada.

### GET /passkeys
Lista las passkeys registradas del usuario.

### PATCH /passkeys/:id
Renombra una passkey del usuario.

### DELETE /passkeys/:id
Elimina una passkey del usuario.

### POST /auth/passkey/login/options
Genera las opciones WebAuthn para iniciar sesión con passkey.
Auth: pública (sin token).

### POST /auth/passkey/login/verify
Verifica la passkey y emite los tokens de sesión.
Auth: pública (sin token).

## Permissions (/permissions)
### GET /permissions
Lista el catálogo de permisos disponibles en el sistema.

## Phone Numbers (/organizations/:orgId/phone-numbers)
### POST /organizations/:orgId/phone-numbers
Agrega un nuevo número de teléfono a la WABA via Meta Cloud API.

### GET /organizations/:orgId/phone-numbers
Lista los números de teléfono de la organización.
Query params:
- wabaId: string
- includeArchived: string

### GET /organizations/:orgId/phone-numbers/:id
Obtiene el detalle de un número de teléfono.

### DELETE /organizations/:orgId/phone-numbers/:id
Archiva (soft-delete) el número.

### POST /organizations/:orgId/phone-numbers/sync
Sincroniza con Meta: archiva números que ya no existen ahí y restaura los que volvieron.

### POST /organizations/:orgId/phone-numbers/:id/restore
Restaura un número archivado.

### DELETE /organizations/:orgId/phone-numbers/:id/purge
HARD delete del número. Bloquea si hay cargos pendientes.

## Plan & límites (/organizations/:orgId/plan-limits)
### GET /organizations/:orgId/plan-limits
Plan actual + uso vs cuotas. Frontend lo usa para barras de progreso.

## Plans (/plans)
### GET /plans
Lista pública de planes activos con sus precios.
Auth: pública (sin token).

### GET /plans/:slug
Detalle público de un plan por su slug.
Auth: pública (sin token).

### GET /plans/quote/:slug
Precio final con cupón aplicado (informativo, no cobra).
Query params:
- currency: string
- interval: string
- coupon: string

### POST /plans/organizations/:orgId/preview-change
Previsualiza el efecto de un cambio de plan: prorrateo + cupón + saldo final.

### POST /plans/organizations/:orgId/cancel-subscription
Cancela la suscripción de pago. Baja el plan a free, mantiene los datos. No emite reembolsos por servicios ya prestados.

### PATCH /plans/organizations/:orgId/plan
Cambia el plan de una organización (self-service: upgrade/downgrade).

## Pricing (/pricing)
### GET /pricing
Lista las tarifas de mensajería vigentes.

## Push Notifications (/push)
### GET /push/config
VAPID public key y disponibilidad del servicio.

### POST /push/subscribe
Guarda la suscripción Push del browser del usuario.

### DELETE /push/subscribe
Elimina una suscripción Push (logout en device, toggle off).

### GET /push/subscriptions
Lista los devices del usuario con push habilitado.

### POST /push/test
Envía una notificación de prueba al usuario actual.

## Quick replies (/organizations/:orgId/quick-replies)
### GET /organizations/:orgId/quick-replies
Lista las respuestas rápidas de la organización.

### POST /organizations/:orgId/quick-replies
Crea una respuesta rápida (atajo, título y cuerpo).

### PATCH /organizations/:orgId/quick-replies/:id
Actualiza una respuesta rápida.

### DELETE /organizations/:orgId/quick-replies/:id
Archiva una respuesta rápida.

### POST /organizations/:orgId/quick-replies/:id/use
Incrementa el contador de uso de una respuesta rápida.

## Reactions (/organizations/:orgId/messages/:messageId/reactions)
### PUT /organizations/:orgId/messages/:messageId/reactions
Añade o reemplaza la reacción del agente en un mensaje. WhatsApp Cloud API solo
permite una reacción por usuario por mensaje, así que sustituye la previa si
existe (semántica de upsert).
Body:
- emoji (requerido): string — Emoji unicode para reaccionar al mensaje. Si está vacío se interpreta como remover la reacción.

### DELETE /organizations/:orgId/messages/:messageId/reactions
Remueve la reacción del agente actual del mensaje.

## Reports (/organizations/:orgId/reports)
### GET /organizations/:orgId/reports/summary
Resumen general del dashboard de la organización.

### GET /organizations/:orgId/reports/messaging
Métricas de mensajería agregadas desde una fecha.
Query params:
- since: string

### GET /organizations/:orgId/reports/billing
Resumen de facturación y consumo de la organización.

### GET /organizations/:orgId/reports/customers
Lista contactos con métricas agregadas de conversaciones (paginado).
Query params:
- since: string
- until: string
- category: string
- resolutionOutcome: string
- q: string
- limit: string
- cursor: string

### GET /organizations/:orgId/reports/customers/:contactId
Detalle de un contacto con métricas históricas y timeline.

## Roles (/organizations/:orgId/roles)
### GET /organizations/:orgId/roles
Lista los roles de la organización.

### POST /organizations/:orgId/roles
Crea un rol personalizado en la organización.

### PATCH /organizations/:orgId/roles/:id
Actualiza el nombre o los datos de un rol.

### PUT /organizations/:orgId/roles/:id/permissions
Reemplaza el conjunto de permisos de un rol.

### DELETE /organizations/:orgId/roles/:id
Elimina un rol de la organización.

## Stickers (/organizations/:orgId/stickers)
### GET /organizations/:orgId/stickers
Lista la librería de stickers de la org.

### POST /organizations/:orgId/stickers/upload
Sube un sticker propio (cualquier imagen → webp 512×512).

### POST /organizations/:orgId/stickers/from-message/:messageId
"Roba" un sticker entrante de un mensaje del cliente a la librería.

### POST /organizations/:orgId/stickers/:id/send
Envía un sticker de la librería a una conversación.

### DELETE /organizations/:orgId/stickers/:id
Borra un sticker de la librería.

## Tags (/organizations/:orgId/tags)
### GET /organizations/:orgId/tags
Lista las etiquetas de la organización.

### POST /organizations/:orgId/tags
Crea una etiqueta (nombre y color opcional).

### DELETE /organizations/:orgId/tags/:id
Elimina una etiqueta.

## Templates (/organizations/:orgId/templates)
### GET /organizations/:orgId/templates
Lista las plantillas de la organización, opcionalmente filtradas por WABA.
Query params:
- wabaId: string

### GET /organizations/:orgId/templates/:id
Obtiene el detalle de una plantilla por su id.

### POST /organizations/:orgId/templates
Crea una plantilla y la envía a Meta para aprobación.
Body:
- wabaId (requerido): string
- name (requerido): string
- language (requerido): string
- category (requerido): string [MARKETING|UTILITY|AUTHENTICATION]
- components (requerido): TemplateComponentDto[]

### PATCH /organizations/:orgId/templates/:id
Edita una plantilla en Meta. Solo se permiten APPROVED o REJECTED, y solo los `components`.
Meta solo permite editar plantillas aprobadas o rechazadas; name/language/category no son editables. Cuotas de Meta: 1 edición/24h, máximo 10/mes por plantilla.
Body:
- components (requerido): TemplateComponentDto[]

### DELETE /organizations/:orgId/templates/:id
Borra una plantilla — primero en Meta y luego en la BD local.

### POST /organizations/:orgId/templates/sync
Sincroniza plantillas desde Meta para todos los WABA de la organización

### POST /organizations/:orgId/templates/upload-header-media
Sube imagen/video/PDF para usar como Header de plantilla. Devuelve header_handle.

## Two-Factor (/two-factor)
### POST /two-factor/enroll
Inicia el alta de 2FA y devuelve el secreto/QR TOTP.

### POST /two-factor/verify
Verifica el código TOTP y activa el 2FA.

### POST /two-factor/disable
Desactiva el 2FA del usuario.

## Usage (/organizations/:orgId/usage)
### GET /organizations/:orgId/usage/daily
Devuelve el consumo diario por métrica desde una fecha.
Query params:
- metric: string
- since: string

## Users (/users)
### GET /users/me
Obtener mi perfil

### PATCH /users/me
Actualizar mi perfil
Body:
- name: string
- locale: string

### POST /users/me/change-password
Cambiar contraseña (revoca sesiones existentes)
Body:
- currentPassword (requerido): string
- newPassword (requerido): string

## WABA (/organizations/:orgId/waba)
### GET /organizations/:orgId/waba
Lista las WABAs de la organización.
Query params:
- includeArchived: string

### GET /organizations/:orgId/waba/:id
Obtiene el detalle de una WABA.

### POST /organizations/:orgId/waba/connect-test-number
Conecta manualmente un número de prueba con un permanent access token de Meta (sin Embedded Signup).
Body:
- wabaId (requerido): string
- phoneNumberId (requerido): string
- accessToken (requerido): string
- wabaName: string

### DELETE /organizations/:orgId/waba/:id
Archiva (soft-delete) la WABA. Conversaciones, mensajes y cargos se conservan.

### POST /organizations/:orgId/waba/:id/restore
Restaura una WABA archivada y vuelve a suscribir webhooks.

### DELETE /organizations/:orgId/waba/:id/purge
HARD delete: borra permanentemente la WABA y todo lo asociado. Bloquea si hay cargos pendientes de facturar.

## Wallet (/organizations/:orgId/wallet)
### GET /organizations/:orgId/wallet
Devuelve el saldo actual de la billetera de la organización.

### GET /organizations/:orgId/wallet/transactions
Lista los movimientos de la billetera (paginado por cursor).
Query params:
- limit: string
- cursor: string

## web-chat (/)
### GET /organizations/:orgId/web-chat/channels
Lista los canales de web chat de la org.

### POST /organizations/:orgId/web-chat/channels
Crea un canal de web chat.
Body:
- name (requerido): string
- color: string
- welcomeMessage: string
- allowedDomains: string[]
- precaptureEnabled: boolean
- botEnabled: boolean
- enabled: boolean

### PATCH /organizations/:orgId/web-chat/channels/:id
Actualiza un canal de web chat.
Body:
- name: string
- color: string
- welcomeMessage: string
- allowedDomains: string[]
- precaptureEnabled: boolean
- botEnabled: boolean
- enabled: boolean
- identityRequired: boolean — Si true, exige firma HMAC al recibir identidad pasada por el host site.
- operatingHours: object
- offlineAction: object
- offlineMessage: string
- prechatFields: object[]
- departments: object[]
- proactiveTriggers: object[]
- linkEmailBannerEnabled: boolean

### DELETE /organizations/:orgId/web-chat/channels/:id
Elimina un canal de web chat.

### GET /organizations/:orgId/web-chat/channels/:id/snippet
Devuelve el snippet de instalación del widget para el canal.

### POST /organizations/:orgId/web-chat/channels/:id/identity-secret
Genera o rota el secreto HMAC de identidad (se muestra una sola vez).

### DELETE /organizations/:orgId/web-chat/channels/:id/identity-secret
Revoca el secreto HMAC de identidad del canal.

### POST /organizations/:orgId/conversations/:convId/web-chat/send
Envía un mensaje del agente a una conversación de web chat.
Body:
- type: string [text|image|video|audio|document] — Tipo de mensaje. Si no se especifica, default 'text'.
- body: string — Texto del mensaje (requerido si type='text'; opcional como caption en otros).
- mediaAssetId: string — Id del MediaAsset previamente subido vía /web-chat/media. Requerido cuando type != 'text'.
- replyToMessageId: string — UUID del Message al que el agente responde (cita visible en widget).

### POST /organizations/:orgId/conversations/:convId/web-chat/media
Sube un archivo a S3 para web chat y devuelve su mediaAssetId.

## web-chat-public (/web-chat/:token)
### POST /web-chat/:token/sessions
Público (widget): crea sesión del visitante (anónima, identificada o verify-OTP).
Body:
- visitorId (requerido): string
- mode (requerido): string [anonymous|identified|verify-otp|host-identified]
- name: string
- email: string
- phone: string
- otp: string
- userId: string
- hash: string — HMAC-SHA256 hex de `userId || email`, firmado con `WebChatChannel.identitySecret`.
- attributes: object — Atributos custom del host (plan, role, etc.) — van a visitor.metadata.host.
- departmentId: string
- prechat: object — Respuestas del prechat dinámico: { fieldId: value }.
- url: string — Datos del navegador / contexto.
- referer: string
- title: string
- lang: string
- utm: object

### POST /web-chat/:token/sessions/resend-otp
Público (widget): reenvía el código OTP de verificación por email.
Body:
- email (requerido): string

### GET /web-chat/:token/history
Público (widget): historial reciente del visitante (requiere visitor JWT).

### POST /web-chat/:token/sessions/link-email
Público (widget): vincula un email al visitante (requiere visitor JWT).
Body:
- email (requerido): string
- name: string

### POST /web-chat/:token/upload
Público (widget): sube un adjunto y devuelve su mediaAssetId (requiere visitor JWT).

### POST /web-chat/:token/messages
Público (widget): envía un mensaje con adjunto del visitante (requiere visitor JWT).

## Webhooks (outbound) (/organizations/:orgId/webhooks-outbound)
### GET /organizations/:orgId/webhooks-outbound
Lista los webhooks salientes de la organización (sin el secret).

### POST /organizations/:orgId/webhooks-outbound
Crea un webhook saliente suscrito a eventos.

### PATCH /organizations/:orgId/webhooks-outbound/:id
Actualiza un webhook saliente (URL, eventos, formato, estado).

### DELETE /organizations/:orgId/webhooks-outbound/:id
Elimina un webhook saliente.

### GET /organizations/:orgId/webhooks-outbound/:id/deliveries
Lista el historial de entregas de un webhook saliente.

### GET /organizations/:orgId/webhooks-outbound/:id/secret
Revela el secret de firma del webhook (no aparece en el listado).

## WhatsApp Links (/)
### GET /organizations/:orgId/whatsapp-links
Lista los enlaces Click-to-WhatsApp de la organización.
Query params:
- phoneNumberId: string
- includeArchived: string

### POST /organizations/:orgId/whatsapp-links
Crea un enlace Click-to-WhatsApp con su URL pública.
Body:
- phoneNumberId (requerido): string
- name (requerido): string
- campaignTag: string
- prefilledMessage: string
- metadata: object

### GET /organizations/:orgId/whatsapp-links/:id
Obtiene el detalle de un enlace Click-to-WhatsApp por su id.

### PATCH /organizations/:orgId/whatsapp-links/:id
Actualiza un enlace Click-to-WhatsApp.
Body:
- name: string
- campaignTag: string
- prefilledMessage: string
- metadata: object

### DELETE /organizations/:orgId/whatsapp-links/:id
Toggle archivado del enlace (soft-delete reversible).

### GET /organizations/:orgId/whatsapp-links/:id/stats
Devuelve las estadísticas de clicks de un enlace.

### GET /organizations/:orgId/whatsapp-links/:id/qr
Genera el código QR del enlace en formato PNG o SVG (?format, ?size).
Query params:
- format: string
- size: string