## Visión general

La **API REST** permite leer y escribir datos de la plataforma (contactos, conversaciones, mensajes y
más). La autenticación usa un **token de acceso**, y los **webhooks** entregan eventos a tu sistema en
tiempo real.

## Requisitos previos

- Un token de acceso válido.
- Un endpoint HTTPS para recibir webhooks.

## Paso a paso

1. Genera un token de acceso en la configuración.
2. Incluye el token en el encabezado de autenticación de tus llamadas a la API.
3. Realiza solicitudes a los recursos de la API (ej.: listar contactos, crear conversación).
4. Configura un webhook indicando la URL y los eventos deseados.
5. Valida la firma/secreto del webhook antes de procesar el payload.

## Configuración y opciones

- **Alcance del token**: limita el acceso a lo necesario.
- **Eventos del webhook**: suscríbete solo a los eventos que usas.
- **Secreto de firma**: se muestra una sola vez, justo después de crear el webhook. Cópialo y guárdalo
  de forma segura; las respuestas de listado y edición solo confirman que hay un secreto configurado
  y nunca lo revelan. Si se pierde, crea un webhook de reemplazo y retira el destino anterior.
- **Entrega duradera**: cada entrega de webhook de cuenta se registra antes de entrar en la cola. Los
  errores de red y respuestas 5xx usan reintentos con backoff y siguen visibles en el historial.
- **Historial y reenvío**: en **Configuración → Integraciones → Webhooks**, abre el historial del
  destino para buscar, filtrar y ordenar intentos. Un administrador puede reenviar una o varias filas;
  el resultado masivo mantiene separados los IDs procesados y fallidos.
- **Payload de Commerce**: por defecto solo se envían identificadores canónicos. Activa **Incluir datos
  comerciales** en un destino únicamente cuando el receptor necesite comprador, producto/variante e
  ítems normalizados. El opt-in nunca agrega credenciales ni el payload bruto de la pasarela.
- **Idempotencia del receptor**: usa el encabezado `X-Chatwoot-Delivery` como clave de idempotencia; un
  reenvío manual reutiliza el mismo identificador.

### Catálogo de eventos (grupos de módulos)

Todos los eventos siguientes son **suscripciones a nivel de cuenta** (configuradas por cuenta, en la
pantalla de Webhooks). Para que un módulo entregue sus eventos, la **función del módulo debe estar
habilitada** en la cuenta — la suscripción se acepta aunque la función esté apagada, pero no se
entrega nada hasta activarla.

- **Conversaciones, mensajes, contactos, bandeja y escritura** — el ciclo de vida de la atención.
- **CRM (negocios)** — creación, etapa, ganado/perdido, prioridad, valor, salud, lista de tareas, SLA y fechas de cierre.
- **Catálogo y Commerce** — productos, variantes/stock y el ciclo de pago de Commerce.
- **Pedidos e ingresos** — registro de pedido, estado, pagado, reembolsado, ingresos y afiliados.
- **Tareas, Calendario y reservas, Pagos y Follow-ups** — el ciclo de vida de cada módulo.
- **Contratos y firma electrónica, Gestión de Ventas y Engagement/Lead Score**.
- **Account Brain** — riesgo, insights, ejecución de departamento y mejoras propuestas.
- **Distribución (Clases de Lanzamiento)** — inscripción, invitación, ingreso de miembros y finalización de unidades.
- **Growth Social y Ads** — comentarios, leads de anuncio, estado de campaña y ventana del Clic-a-WhatsApp.
- **WhatsApp Hub** — difusiones, eventos de participantes y bienvenidas/despedidas de grupo (Cloud y WazMeow).
- **Llamadas y respuestas de Flow de WhatsApp** — ciclo de vida de llamadas y respuestas de WhatsApp Flows.
- **Gestión de Equipo** — cambio de estado, pausas y turnos de los agentes.
- **FlowBuilder** — ciclo de vida de las sesiones de flujo.
- **Enrutamiento Inteligente** — asignación de agente.

Los campos reales de cada payload están en [Eventos por módulo](/hc/ajuda/articles/api-developers-eventos-por-modulo-es).

## Casos de uso

- Replicar conversaciones en un data warehouse.
- Notificar a un sistema externo cuando una conversación se crea o se resuelve.

## Consejos, límites y buenas prácticas

- Verifica siempre la firma del webhook antes de actuar.
- Garantiza idempotencia con `X-Chatwoot-Delivery`, también en reintentos y reenvíos manuales.
- Respeta los límites de tasa y usa backoff en errores 429/5xx.

## Solución de problemas

- **401/403**: token inválido o sin permiso.
- **Webhook duplicado**: confirma que el receptor deduplica `X-Chatwoot-Delivery`.
- **Entrega fallida**: abre el historial del destino y revisa su estado HTTP/error y el próximo intento.
  Después de corregir el receptor, selecciona la fila y confirma el reenvío.

## Ver también

- [SDK, API REST y MCP de Dashboard Apps](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-es)
- [Visión general de API y Desarrolladores](/hc/ajuda/articles/api-developers-overview-es)
- [Eventos por módulo](/hc/ajuda/articles/api-developers-eventos-por-modulo-es)
- [Referencia de API (Swagger / OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-es)