Integrar WhatsApp con tu ERP o CRM: tres vías y una regla

Hay tres formas de conectar WhatsApp con tu ERP, tu CRM o tu tienda, y elegir mal cuesta semanas de mantenimiento. La pregunta que las separa no es técnica, es de dirección: quién empieza la conversación. Si el cliente escribe y el flujo necesita datos tuyos, el flujo consulta tu sistema y no escribes servidor. Si tu sistema es el que decide avisar, entonces tu sistema llama a la API pública. Y si quien responde es un agente de IA, lo que necesitas es darle una herramienta.

Las tres vías, en una tabla

Las tres pueden convivir en el mismo negocio. Lo habitual es empezar por la primera, añadir la segunda cuando el ERP ya tiene los eventos, y la tercera cuando el volumen de preguntas abiertas justifica un agente.

Vía 1: el flujo consulta tu sistema

Un flujo es una secuencia de pasos, y uno de esos tipos de paso es llamada a API. El flujo llega a ese paso, pega a la URL que le indicaste, guarda la respuesta en los datos de la sesión y sigue por una rama u otra según lo que recibió.

Esto resuelve el caso más común sin que escribas ni un servidor de mensajería: el cliente pregunta por su pedido, el flujo consulta tu endpoint con el número de pedido que el cliente acaba de escribir, y responde con el estado real.

Lo que tienes que preparar de tu lado es solo el endpoint:

GET https://tu-erp.com/api/pedidos/4512

{
  "numero": "4512",
  "estado": "en_reparto",
  "courier": "Olva",
  "fecha_estimada": "2026-07-28"
}

Y del lado del flujo, una condición que bifurque por estado. Los detalles de cómo se arma la secuencia y cómo se exporta como JSON re-importable están en flujos en JSON.

Vía 2: tu sistema envía por la API pública

Cuando el evento nace en tu sistema —se confirmó un pago, salió el despacho, se acerca una cita— el que tiene que hablar es tu sistema. Para eso está la API pública, en /api/public/v1, con contrato estable e independiente de la interfaz del dashboard.

Se autentica con una API key de empresa que se crea desde el dashboard y se muestra una sola vez:

curl -X POST https://tudominio.com/api/public/v1/messages \
  -H "Authorization: Bearer fjc_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4512-despacho" \
  -d '{"to": "+51987654321", "type": "text", "text": "Tu pedido 4512 salió a reparto"}'

Tres cosas que conviene saber antes de escribir ese código:

• La key identifica a la empresa. Todo lo que devuelve la API queda limitado a esa cuenta, y cada key lleva permisos explícitos: messages:send para enviar, conversations:read para leer historiales, usage:read para consultar el consumo del mes.
• El acceso depende del plan. Es una prestación del plan, con cuota mensual y límite por minuto por cada key. Si el plan no lo incluye, la API responde que el acceso no está disponible en lugar de fallar de forma ambigua.
• La ventana de 24 horas también aplica aquí. Si intentas mandar texto libre y el cliente no escribió en las últimas 24 horas, la respuesta es un error explícito de ventana expirada. Ese aviso hay que enviarlo con plantilla. Está explicado en detalle en la ventana de 24 horas.

La referencia completa de endpoints, códigos de error y cuotas está en la documentación de la API pública.

La regla: idempotencia o mensajes duplicados

Este es el error que más caro sale, y no es una opinión: es la consecuencia inevitable de reintentar sobre una red real.

Tu sistema llama para enviar el aviso de despacho. La petición llega, el WhatsApp se envía, y la respuesta se pierde por un timeout. Tu código no sabe si se envió; su reintento es correcto. Sin protección, el cliente recibe el mismo aviso dos veces.

La solución es la cabecera Idempotency-Key con un valor que identifique la operación de negocio, no el intento:

-H "Idempotency-Key: pedido-4512-despacho"

Con eso, el reintento devuelve la respuesta original en lugar de enviar otro mensaje, y viene marcado para que sepas que fue una repetición. La misma clave con un cuerpo distinto se rechaza a propósito: significa que tu código reusó la clave para otra cosa, y eso es un error tuyo que conviene ver en desarrollo y no en producción.

Cómo elegir el valor:

• Bien: pedido-4512-despacho, cita-8891-recordatorio-24h, factura-2026-07-1183. Derivan del dominio, son estables entre reintentos y únicos por operación.
• Mal: un identificador aleatorio por intento (no protege de nada), una marca de tiempo (cambia en cada reintento), o solo el número de pedido (colisiona entre el aviso de confirmación y el de despacho).

Vía 3: darle una herramienta al agente de IA

Las dos vías anteriores asumen que tú sabes de antemano qué se va a preguntar. Cuando no es así —"¿me llegó el pago de ayer?", "¿cuánto me falta para el envío gratis?"— el que responde es un agente de IA, y lo que necesita es acceso a tu sistema.

Un agente puede tener herramientas HTTP o MCP: endpoints que consulta cuando la pregunta lo requiere, y cuya respuesta usa para redactar. Es la diferencia entre un agente que dice "no tengo esa información" y uno que da el saldo real.

Dos cuidados que valen más que cualquier ajuste del modelo:

• Devuelve solo lo necesario. Si tu endpoint responde el registro completo del cliente, el agente puede terminar mencionando datos que nadie pidió. Expón una vista mínima para el agente.
• Solo lectura primero. Consultar es seguro; ejecutar acciones que mueven dinero o cancelan pedidos merece confirmación humana hasta que el comportamiento esté medido.

Cómo se acota un agente para que no invente, cómo se le carga la base de conocimiento y cuándo derivar a una persona está en agentes de IA con base de conocimiento.

Cómo elegir sin equivocarte

Cuatro preguntas, en orden:

1. ¿El mensaje nace de un evento de tu sistema? Sí: API pública con idempotencia. No: sigue.
2. ¿La respuesta se puede resolver con un dato concreto que ya tienes? Sí: paso de llamada a API dentro del flujo, que es determinista y de costo fijo.
3. ¿Las preguntas son abiertas y variadas? Sí: agente de IA con herramienta.
4. ¿El aviso sale fuera de la ventana de 24 horas? Entonces necesitas plantilla, sea cual sea la vía.

Ese orden importa porque cada nivel es más caro de mantener que el anterior. Un flujo con una llamada a API se depura leyendo la secuencia; un agente con herramientas requiere revisar conversaciones reales. La decisión entre lo determinista y lo generativo está desarrollada en flujos, IA o los dos.

Preguntas frecuentes

¿Necesito un servidor propio para integrar WhatsApp?

No siempre. Si lo único que hace falta es que la conversación consulte un dato tuyo, el paso de llamada a API del flujo lo resuelve: tú expones un endpoint de lectura y el flujo lo consume. Solo necesitas escribir código que llame a la API cuando el mensaje lo dispara tu sistema.

¿Qué pasa si mi endpoint responde lento o falla?

El paso queda sin respuesta útil y el flujo toma la rama que hayas definido para ese caso. Por eso conviene definirla siempre: un mensaje que reconozca el problema y una derivación a una persona. Si no existe esa rama, la conversación se queda trabada.

¿Puedo enviar plantillas desde la API pública?

En la versión actual el envío por API cubre mensajes de texto; las plantillas se envían desde el dashboard, incluyendo la difusión a varios contactos. Si tu aviso cae fuera de la ventana de 24 horas, ese es el camino.

¿Cómo evito que un reintento duplique el mensaje?

Con la cabecera Idempotency-Key y un valor derivado de la operación de negocio, no del intento. El reintento devuelve la respuesta original y no vuelve a enviar. Es la única protección real: sin ella, cualquier timeout puede terminar en un mensaje duplicado.

¿Puedo leer las conversaciones desde mi sistema?

Sí, con una key que tenga el permiso de lectura de conversaciones. Sirve para volcar los historiales a tu CRM o para tableros propios. Es lectura: el envío requiere el permiso correspondiente por separado, y conviene usar keys distintas para cada uso.