← Frepi Developers

Enviar un formulario desde tu sistema

API de automatizaciones v1 (contrato 1.2) · POST /api/automations/v1/runs con campaign_id · Autenticación Bearer con una llave frk_live_…

1 · Qué hace

Tu sistema avisa que pasó algo (una solicitud de crédito, una cita, un pedido) y Frepi le envía a esa persona la plantilla de una campaña con formulario. Cuando la persona toca el botón de la plantilla, Frepi le manda el formulario de WhatsApp en el mismo chat. Las respuestas quedan en Frepi, en el contacto, y las lees por la API.

Los otros botones de la plantilla le escriben a la línea, como hoy: los contesta el agente de la línea o tu equipo.

2 · Antes de empezar

• La llave. Créala en Frepi: Automatizaciones › Mensajes por evento › Llaves. Solo la ve quien puede configurar el espacio, y se muestra una sola vez. Necesita el permiso automations:run (y automations:read para leer las respuestas).
• El formulario publicado. En Formularios, el formulario debe estar publicado en la línea que envía.
• Una campaña con formulario lanzada desde Frepi. En Formularios pulsa «Enviar» en el formulario, elige la audiencia y la plantilla con el botón que lo abre, y lánzala. Su id está en la dirección de la campaña: …/marketing/broadcasts/<id>. Ese id es tu campaign_id.

3 · Enviar a una persona

curl -X POST https://ejemplo.frepi.ai/api/automations/v1/runs \
  -H "Authorization: Bearer $FREPI_AUTOMATION_KEY" \
  -H "Idempotency-Key: cred-2291" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "6f1c2a9e-4b7d-4c3a-9e8f-2d1b0a7c5e43",
    "to": { "phone": "+573119029020" },
    "external_ref": "CRED-2291"
  }'

• Responde 202 con el id del envío. Frepi envía la plantilla; la persona tiene 24 h para tocar el botón.
• Si la plantilla tiene variables, mándalas en variables (solo texto).
• line solo cuando la campaña sale de más de una línea («La línea del vendedor de cada contacto»): el número de WhatsApp de una de ellas, por ejemplo "line": "+57 601 555 0100". Con una sola línea, no lo mandes.
• No mandes logic, automation_id ni agent con campaign_id.

4 · Aprobar una vez

• Lanzar la campaña en Frepi, con tu sesión iniciada en el navegador, aprueba su lógica: tus llamadas se envían de inmediato.
• Cambiar la plantilla, el botón o el formulario es una campaña nueva, con su propio id. El id anterior sigue funcionando hasta que alguien archive su lógica.
• Si una persona archivó la lógica, la llamada responde 409 logic_archived.
• Una campaña lanzada por MCP o con una llave queda por aprobar: la llamada responde 409 logic_pending_approval con approve_url; una persona la aprueba una vez en Frepi.

5 · Idempotencia

• Idempotency-Key es obligatorio. La misma llave con el mismo cuerpo responde 202 con replayed: true y no envía nada otra vez.
• La misma llave con otro cuerpo responde 409 idempotency_conflict.
• Si recibes un 5xx, vuelve a intentar con la misma llave: nunca se envía dos veces.

6 · Leer las respuestas

• GET /api/automations/v1/runs/{id} trae el estado del envío y answers[]: un campo por respuesta, con su token y su valor.
• Para leer muchas: GET /api/automations/v1/runs?updated_since=… (paginado con cursor). Pide cada pocos minutos lo que cambió desde tu última lectura.
• Una opción llega como su id (por ejemplo "pro"); una fecha, como YYYY-MM-DD.
• Frepi guarda los envíos y sus respuestas 180 días.
• Todavía no avisamos por webhook cuando llega una respuesta: lee por polling.

7 · Errores

Lee el code, nunca el message. Los problemas de validación llegan en 422 validation_failed, en errors[], cada uno con su code y su path.

8 · Límites

• Por llave: 60 envíos por minuto y 5.000 por día. Por teléfono: 3 envíos de la API cada 24 h.
• La plantilla de la campaña tiene hasta 3 botones de hasta 20 caracteres.
• La persona tiene 24 h para tocar el botón; después el envío queda «Sin respuesta».