Cómo integrar WhatsApp con tu ERP, CRM o tienda usando API y webhooks

La atención ocurre en WhatsApp, pero el resto del negocio vive en otros sistemas: el ERP con pedidos e inventario, el CRM con la lista de clientes, la tienda en línea, el sistema de agenda. Mientras no se hablen entre sí, alguien hace de puente a mano. Copia el número del pedido, lo pega en la conversación, vuelve al sistema y actualiza el estado.

Este artículo tiene dos partes. La primera es para quien decide: qué conviene automatizar y cómo pensar la integración. La segunda es para quien desarrolla: cómo llamar a la API, recibir webhooks y hacerlo con seguridad.

Parte 1: para quien decide

Qué resuelve una integración

La integración elimina el trabajo manual de repetir la misma información en dos lugares y hace que WhatsApp reaccione a lo que pasa en los otros sistemas, y al revés. Algunos ejemplos genéricos:

• Aviso de pedido. La tienda marca un pedido como enviado y el cliente recibe un mensaje sin que nadie lo escriba.
• Cobranza y recordatorio. El área de finanzas del ERP genera un cobro por vencer y sale un mensaje con el aviso.
• Contacto en el CRM. Cuando el cliente cambia de etapa en la conversación, el CRM recibe la información.
• Agenda conectada al sitio o al sistema propio. Una clínica consulta horarios libres y crea la cita desde el sistema que ya usa.
• Pedidos y tickets. Los pedidos de la tienda y los tickets de soporte entran a la atención y se actualiza su estado.
• Alerta para el equipo. Un evento (conversación nueva, canal desconectado, ticket con plazo vencido) dispara un aviso en otro sistema.

API o webhook, cuál usar

La diferencia es quién toma la iniciativa.

Casi toda integración usa las dos: el webhook avisa que algo pasó y la API hace la acción de vuelta.

Qué preguntar antes de empezar

1. ¿Qué proceso se va a automatizar? Elige uno, el que hoy consume más tiempo.
2. ¿Qué sistema es la fuente de la verdad? Inventario, precio, estado del pedido: define quién manda.
3. ¿Quién se encarga cuando falle? Toda integración falla en algún momento. Alguien tiene que verlo y corregirlo.
4. ¿Qué pasa si el mensaje sale duplicado o no sale? Según el caso, el daño es pequeño o grande.
5. ¿El cliente aceptó recibir el mensaje? Automatizar el envío no elimina las reglas de WhatsApp ni la ley de protección de datos.

Disponibilidad

La API y los webhooks están disponibles desde el plan Pro. Cada integración usa credenciales de la propia empresa, lo que mantiene los datos de una cuenta separados de los de otra. Para agencias, esto significa una integración por cliente, cada una con su token.

Parte 2: para quien desarrolla

La documentación completa, con los formatos de cada recurso, está en /docs/api. Abajo van los conceptos y los cuidados.

Autenticación: un token por empresa

En Configuración, en el área de desarrolladores, creas tokens de la API. Cada token pertenece a una empresa y se envía en el encabezado Authorization: Bearer <token>. El valor aparece una sola vez, así que guárdalo en un gestor de secretos.

Cada token tiene permisos: consultar, crear y modificar, enviar mensajes y pedidos de la tienda. Crea un token por sistema y dale solo lo que necesita. Si un sistema se compromete, revocas un token sin afectar a los demás.

Qué hace la API hoy

• Atención. Consultar conversaciones, mensajes y contactos, enviar mensajes de texto y marcar una conversación como resuelta.
• Agenda. Listar agendas y horarios libres, consultar citas, crear, reprogramar y cancelar.
• Leads del sitio. Consultar leads, cuando está instalada la app de Formularios o la de Captura de leads.
• Pedidos. Consultar y crear pedidos y cambiar su estado, cuando está instalada la app de Pedidos y el token tiene el permiso de pedidos.
• Tickets. Consultar, crear, cambiar el estado y agregar notas, cuando está instalada la app de Tickets.

Dos límites para no prometer de más. El envío de mensajes es de texto: POST /api/v1/messages, con el destino (una conversación o un teléfono) y el texto, de hasta 4096 caracteres. No hay envío de archivos multimedia por la API. Y no hay una ruta solo para registrar o editar contactos: la API consulta los existentes, y un contacto nuevo nace junto con el mensaje a un teléfono, la cita o el pedido que trae ese teléfono.

Un detalle del envío: la respuesta es 202, es decir, el mensaje fue aceptado para envío, no necesariamente entregado. Si el número de la empresa está desconectado, la llamada devuelve error 409. Un mensaje a alguien que nunca conversó con la empresa puede quedar retenido por las protecciones del producto, y la respuesta informa el motivo.

Idempotencia: no envíes lo mismo dos veces

La red se cae, ocurre un timeout y tu sistema reintenta. Sin cuidado, el cliente recibe dos veces el mismo aviso de pago.

Los POST que envían o crean algo (mensaje, cita, pedido, ticket) aceptan el encabezado opcional Idempotency-Key. Con la misma clave, el mismo token y el mismo cuerpo, la segunda llamada devuelve la respuesta de la primera, marcada con Idempotent-Replayed: true, en lugar de repetir la acción. La clave vale 24 horas y admite hasta 100 caracteres. Si reutilizas la clave con otro cuerpo, recibes un error. Solo se guardan las respuestas exitosas, así que una llamada que falló en la validación se puede corregir y reenviar con la misma clave.

Cómo generar la clave: usa algo que identifique el hecho de negocio, como pedido-1234-enviado, y no un número aleatorio nuevo en cada intento. Así el reintento del mismo evento siempre cae en la misma clave.

Webhooks: recibir los eventos

Registras una dirección HTTPS pública y eliges los eventos, o todos. Cada empresa puede tener hasta 10 direcciones. No se aceptan direcciones internas. Entre los eventos están:

• mensajes: message.received, message.sent, message.status;
• conversaciones: conversation.opened, conversation.assigned, conversation.resolved;
• contactos: contact.created, contact.updated, contact.stage_changed;
• captación: lead.created, form.submitted, pixel.event;
• agenda: appointment.created, appointment.rescheduled, appointment.cancelled;
• pedidos, negociaciones y tickets, cuando la app correspondiente está instalada;
• channel.status, cuando cambia el estado de la conexión del número.

Cada entrega es un POST con JSON que contiene id, event, created_at y data. Los encabezados traen X-Integra-Event, X-Integra-Delivery (el identificador de la entrega) y X-Integra-Signature.

Verifica la firma

Cualquiera que descubra tu dirección puede mandar un POST falso. La firma lo impide. El encabezado tiene el formato t=<timestamp>,v1=<hex>. El valor v1 es un HMAC-SHA256 de <timestamp>.<cuerpo sin procesar>, usando como clave el secreto del webhook, que aparece una sola vez cuando lo creas.

Hazlo así:

1. Lee el cuerpo sin procesar de la solicitud, antes de convertirlo a objeto.
2. Calcula el HMAC con tu secreto y compáralo con v1, en tiempo constante.
3. Verifica que t sea reciente, por ejemplo dentro de unos minutos, para frenar el reenvío de una captura vieja.
4. Si algo no coincide, responde con error y no proceses.

Responde rápido y maneja las repeticiones

IntegraWhats espera una respuesta 2xx en un máximo de 10 segundos y no sigue redirecciones. Haz lo mínimo al recibir: valida, guarda en una cola y responde. Procesa después.

Cuando la entrega falla, por error de red o por un estado distinto de 2xx, se repite después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 24 horas. Tras 50 fallas seguidas la dirección se desactiva y tienes que reactivarla en el panel.

Esto tiene una consecuencia importante: el mismo evento puede llegar más de una vez y no se puede contar con el orden. Guarda el X-Integra-Delivery de cada entrega procesada e ignora la repetición. Y mira el estado actual del dato, no solo la secuencia de eventos.

Lista de verificación para producción

• Un token por sistema, con los mínimos permisos.
• Secretos fuera del código y fuera del repositorio.
• Idempotency-Key en toda llamada que cree algo.
• Firma verificada en todo webhook.
• Respuesta 2xx rápida y procesamiento en cola.
• Deduplicación por el identificador de la entrega.
• Alerta para cuando el webhook se desactive por fallas.
• Prueba con un número de WhatsApp de prueba antes de pasar a producción.

Cómo empezar en IntegraWhats

Con el plan Pro o superior, abre Configuración y el área de desarrolladores, crea un token con los permisos que necesitas y registra la dirección del webhook. Hay un botón para enviar un evento de prueba. La dirección de la documentación es /docs/api.

Preguntas frecuentes

¿Puedo enviar imágenes o documentos por la API?

Hoy no. La API envía mensajes de texto. Los archivos multimedia los sigue enviando el equipo desde la bandeja de entrada.

¿Se puede registrar un contacto por la API?

No hay una ruta solo para eso. El contacto se crea junto con otra acción: enviar un mensaje a un teléfono nuevo, crear una cita o registrar un pedido con teléfono.

¿Cuántos webhooks puedo registrar?

Hasta 10 direcciones por empresa, cada una con los eventos que elijas.

¿Qué pasa si mi servidor queda fuera de línea?

Las entregas se repiten hasta por 24 horas, según la secuencia de intentos. Pasado ese plazo la entrega se marca como fallida, y tras 50 fallas seguidas la dirección se desactiva. Para recuperar lo que pasó, consulta la API por el estado actual de los datos.

¿Una agencia puede integrar a varios clientes?

Sí. Cada empresa tiene sus tokens y sus webhooks, así que cada cliente tiene su propia integración, aislada de las demás.