API de leads: enviar un lead (referencia)

Para qué sirve

Es la referencia para programar el envío de tus leads a la red: adónde, con qué datos y qué te responde. Si empiezas de cero, lee antes Primeros pasos con la API de leads. Los mensajes de error, uno por uno, están en API de leads: mensajes y códigos de error.

Quién puede usarlo

La API no tiene usuarios ni permisos: cada petición se identifica con el token del afiliado. Lo encuentras en tu guía de integración, que abres en el portal con API Docs, en el apartado 1. Authentication. Para que un lead se acepte, la red tiene que haberte asignado campañas activas.

La dirección

POST https://app.affiliatracker.com/api/lead
Content-Type: application/json

• Escribe la dirección exacta: con https:// y sin barra al final. http:// y /api/lead/ redirigen, y al seguir la redirección la petición deja de ser un POST: el lead no entra y no recibes ningún error de la API.
• Sólo POST. Un GET no llega a la API: te redirige a la página de inicio de sesión.
• De servidor a servidor. Llámala desde tu servidor, no desde una página web: con Content-Type: application/json, el navegador hace antes una consulta previa que la API no atiende. Así, además, tu token no viaja al navegador de tus usuarios.

El cuerpo

Un objeto JSON. Si el cuerpo no es un objeto JSON con algún dato dentro (texto, {}, una lista, un formulario), la respuesta es HTTP 400 con invalid_json.

Obligatorios

La fuente tiene que ser la de tu asignación. Si mandas otra, recibes no_campaign_available aunque la campaña esté activa (o invalid_field si esa fuente no existe).

Opcionales

El correo admite hasta 255 caracteres y la IP, 50. Un valor más largo que su máximo hace fallar la petición con HTTP 500 internal_error, sin más detalle, y el lead no se guarda. Lo más fácil de pisar: un click ID de más de 50 caracteres o un código postal de más de 10.

Manda el teléfono con el + delante. Sin él, el número se completa con el prefijo del país y un 34600000001 puede acabar como +3434600000001.

Cada campaña puede convertir en obligatorio un opcional, pedir un formato o esperar respuestas en custom_data: API de leads: requisitos, duplicados y horario de cada campaña.

Ejemplo

curl -X POST "https://app.affiliatracker.com/api/lead" \
  -H "Content-Type: application/json" \
  -d @lead.json

Con lead.json:

{
  "token_affiliate": "TU_TOKEN",
  "id_campaign": 12,
  "id_source": 1,
  "email_lead": "ana.martin@ejemplo.test",
  "country_lead": "ES",
  "ip_lead": "203.0.113.45",
  "name_lead": "Ana",
  "lastname_lead": "Martín",
  "phone_lead": "+34600000001",
  "zip_lead": "28001",
  "city_lead": "Madrid",
  "subid_lead": "clic-000123",
  "custom_data": {
    "tipo_vivienda": "Piso"
  }
}

12 y tipo_vivienda son de ejemplo: el número de tu campaña y sus preguntas están en el apartado 5 de tu guía. El ejemplo de la guía trae YOUR_CAMPAIGN_ID si tienes varias campañas: sin sustituirlo, el cuerpo no es JSON válido y recibes invalid_json.

La respuesta

Lead aceptado, con HTTP 200:

{"status":"success","message":"Lead successfully registered."}

Lead rechazado, también con HTTP 200:

{"status":"error","message":"The country format is incorrect.","code":"invalid_field","field":"country_lead"}

• status es success o error. message va en inglés. code es estable: programa contra code, no contra message, cuyo texto puede mejorar.
• field sólo sale cuando falla un campo concreto; en una pregunta de custom_data, como custom_data.tipo_vivienda.
• HTTP 200 en todo, aceptado o rechazado, salvo invalid_json (400) e internal_error (500). Lee siempre status.
• Llega un solo error: el primero que falla. Corregirlo puede destapar el siguiente.
• La respuesta de éxito no trae un identificador del lead. Para conciliar, usa tu subid_lead y el postback.

Lee la respuesta con un decodificador JSON: las comillas y los acentos de algunos mensajes llegan escapados.

La respuesta espera a la entrega. El lead se entrega al comprador en la misma petición, y la respuesta tarda lo que tarde él: por API, la espera al comprador es de hasta 15 segundos, y la petición entera puede durar algo más; si la campaña entrega por correo, no hay un tope fijo. Si tienes postback, espera también a esa llamada, hasta 3 segundos más. Pon en tu cliente HTTP un tiempo de espera holgado.

No hay entorno de pruebas

Cada lead que pasa las comprobaciones se guarda y se entrega al comprador real en ese momento, aunque sea una prueba. Para probar tu código sin entregar nada, usa peticiones que el servidor rechaza: Primeros pasos con la API de leads.

Lo que conviene saber

• Con id_campaign, el lead va a esa campaña y no se compara su país con el de la campaña. Si mandas un número equivocado y también tienes asignada esa otra campaña, el lead se entrega a su comprador.
• Sin id_campaign, la campaña se elige entre las de ese país y esa fuente que te tiene asignadas la red, al azar si hay varias. Mándalo siempre.
• Tras un rechazo del comprador o un fallo de entrega el lead queda guardado: no lo reenvíes. Qué rechazos lo dejan guardado: API de leads: mensajes y códigos de error.
• Guarda tu token en secreto: identifica tus leads en cada petición. No lo pongas en una página web ni en código que se ejecute en el navegador. Si crees que se ha filtrado, habla con tu red.

Errores frecuentes

Relacionado

• Primeros pasos con la API de leads
• API de leads: mensajes y códigos de error
• API de leads: requisitos, duplicados y horario de cada campaña
• Postback: avisar a tu sistema de cada venta
• Tu guía de la API (API Docs)