API: enviar al CRM los leads de tu formulario web

Para qué sirve

Es la referencia para quien conecta el formulario de una web (WordPress, Elementor, Zapier o un desarrollo propio) con el CRM de su cuenta. La clave se genera en API & Integraciones: recibir en el CRM los leads de tu web, y qué pasa en el CRM con cada lead está en Los leads que llegan desde el formulario de tu web.

Quién puede usarlo

No hay usuarios ni permisos: quien tenga la clave del CRM de la cuenta puede enviar, y la clave decide en qué cuenta entra el lead. Hay una sola clave por cuenta, sin caducidad. Si alguien genera otra o la revoca, la anterior deja de valer en ese momento.

La dirección

POST https://app.affiliatracker.com/api/crm/leads/ingest

• Exacta: con https:// y sin barra al final. Con http:// o con barra final, la dirección redirige y la petición deja de ser un POST: el lead se pierde sin error.
• Sólo POST. Un GET redirige a la página de inicio de sesión.
• De servidor a servidor, como los webhooks de Elementor, de los complementos de WordPress o de Zapier. Desde el navegador del visitante no podrías leer la respuesta, y la clave quedaría a la vista en tu página.

La clave

Se busca en este orden:

1. En la cabecera Authorization: Bearer <clave>. Escribe Bearer con la B mayúscula: con bearer la clave no se reconoce.
2. En la dirección: https://app.affiliatracker.com/api/crm/leads/ingest?api_key=<clave>. Es la forma para Elementor, que no deja poner cabeceras.
3. En el cuerpo, en un campo api_key.

Si llega una cabecera Authorization con algo escrito, se usa ésa y no se miran las otras dos. Usa la cabecera cuando tu formulario lo permita: una clave en la dirección puede quedar en los registros de cualquier servidor intermedio.

El cuerpo

Puede ser JSON, un formulario normal (application/x-www-form-urlencoded o multipart/form-data) o el envío de Elementor Pro (fields, con el ID, el título y el valor de cada campo). Los nombres de los campos no distinguen mayúsculas: Email y email valen igual.

• Ningún campo es obligatorio. Sin nombre, se usa lo que va delante de la @ del correo o, sin correo, «Contacto web».
• Manda nombre y apellidos por separado. Un nombre completo en name entra entero como nombre.
• En Elementor, cada campo se reconoce por su ID o por su título («Nombre», «Email», «Teléfono», «Mensaje»…). La pantalla de la clave tiene la tabla de IDs.

Campos extra

Lo que no es uno de esos campos se guarda en la ficha, en sus datos extra y en las notas como «clave: valor»: hasta 30 campos de 1.000 caracteres cada uno. Un valor vacío o (not set) se salta. Los datos técnicos de WordPress y sus complementos (form_id, form_name, _wpnonce, g-recaptcha-response…) no se guardan.

Canal y atribución

source_channel acepta uno de estos valores: web_form, demo_web, website_external, email, correo, call, whatsapp, linkedin, linkedin_inmail, linkedin_connect, advertising, event, fair, seminar, ref_external, ref_internal, ref_employee, support, job_portal, crm u other. Hay algún valor más, de uso interno. Uno que el sistema no reconozca entra como other. Si no lo mandas, se usa el canal por defecto de tu cuenta o, si no tiene, other.

Para un formulario de tu web, manda source_channel con web_form. rt_source y rt_medium se guardan además aparte, con 100 caracteres como mucho. utm_source, utm_medium, utm_campaign, gclid y demás entran como campos extra. Cómo los usa el Panel Marketing: Atribución de marketing: los canales de origen de tus leads.

Ejemplo

curl -X POST "https://app.affiliatracker.com/api/crm/leads/ingest" \
  -H "Authorization: Bearer TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d @formulario.json

Con formulario.json:

{
  "first_name": "Ana",
  "last_name": "Martín",
  "email": "ana.martin@ejemplo.test",
  "phone": "+34600000001",
  "company_name": "Grupo Ejemplo",
  "notes": "Quiero información.",
  "source_channel": "web_form",
  "rt_medium": "cpc",
  "utm_campaign": "rebajas"
}

Las respuestas

• El éxito y el duplicado responden 200, a propósito: Elementor trata cualquier otro código como error y se lo enseñaría al visitante. Para saber qué ha pasado, mira success.
• id_prospect es el número del cliente potencial creado. assigned_to es el nombre del comercial al que se ha asignado, o null si no se asignó a nadie.
• Un duplicado no crea nada: se anota la consulta en la ficha que ya existe, como mucho una vez por hora. No dice si es un contacto o un cliente potencial. Sin correo no se buscan duplicados.
• Las tildes llegan escapadas en el JSON (\u00e1): léelo con un decodificador JSON.

Lo que conviene saber

• Valida antes de enviar. El CRM no comprueba el contenido: un envío vacío, o un JSON mal formado con la clave buena, crea un cliente potencial «Contacto web» sin datos. Y un dato más largo que su máximo hace fallar la petición sin explicación.
• No comprueba el captcha: lo valida tu formulario antes de enviar.
• Sólo crea clientes potenciales: ni contactos, ni empresas, ni oportunidades.
• No hay entorno de pruebas: cada envío con la clave buena crea (o anota) en el CRM real de la cuenta. Para probar, usa un correo que no esté en el CRM y búscalo después en Clientes Potenciales.
• Si alguien cambia o revoca la clave, el formulario deja de crear leads y recibe 401. El CRM no avisa a nadie.

Errores frecuentes

Relacionado

• API & Integraciones: recibir en el CRM los leads de tu web
• Los leads que llegan desde el formulario de tu web
• Atribución de marketing: los canales de origen de tus leads