API de WhatsApp y CRM: primeros pasos

La API pública de FlujosChat es una API REST para conectar tu sistema con WhatsApp y con el CRM: enviar mensajes y plantillas, leer y actualizar conversaciones, sincronizar los datos de tus clientes y recibir eventos en tiempo real por webhook.

Está pensada para integraciones servidor a servidor: un ERP que avisa que el pedido salió, una tienda WooCommerce o Shopify que confirma la compra, un script que sincroniza el CRM, o un flujo de Zapier/Make.

Qué puedes hacer

• Enviar WhatsApp — texto libre dentro de la ventana de 24 horas de Meta, o una plantilla aprobada para escribir primero.
• Leer conversaciones y mensajes — con paginación por cursor y sincronización incremental por updatedAfter.
• Actualizar el estado — cerrar o reabrir un chat, pausar el bot cuando tu sistema toma el control, corregir el nombre.
• Sincronizar la ficha del cliente — leer y escribir campos personalizados (DNI, RUC, dirección, lo que tengas definido).
• Recibir eventos — webhooks firmados con HMAC-SHA256 en vez de estar preguntando cada minuto.

URL base y versión

Todos los endpoints viven bajo una única URL base, y la versión va en la ruta:

https://www.flujoschat.foo/api/public/v1

Es una superficie separada del panel y estable: no cambia cuando cambia la interfaz. Cuando haya cambios incompatibles, saldrá unav2 y v1 seguirá funcionando.

Tu primer request

Creá una API key en tu panel (Configuración → API Keys) y pedile a la API que te diga quién sos. Si responde con los datos de tu empresa, ya estás dentro:

curl https://www.flujoschat.foo/api/public/v1/me \
  -H "Authorization: Bearer fjc_live_xxxxxxxxxxxx"

Convenciones

Envoltorio de respuesta

Todo lo que responde bien usa el mismo envoltorio, así que tu cliente lo parsea una sola vez: { success, message, data }. Los errores traen { success: false, message, error: { code } } con un código estable por el que podés ramificar.

Paginación por cursor

Los listados devuelven nextCursor: lo pasás como ?cursor= para la página siguiente y cuando llega null ya no hay más. No hay números de página: un cursor no se desordena si entran registros nuevos mientras paginás.

Idempotencia

Los envíos aceptan el header Idempotency-Key. Si tu sistema reintenta por un timeout o un reinicio, el mensaje no se envía dos veces.

Multi-tenant implícito

La key identifica a tu empresa: no existe un parámetro de empresa y nunca vas a ver datos de otra. Por eso una key filtrada se revoca desde el panel y deja de funcionar al instante.