API de leads: requisitos, duplicados y horario de cada campaña

Para qué sirve

Cada campaña tiene su comprador, y cada comprador pide cosas distintas: una exige el teléfono, otra una pregunta propia, otra sólo recibe en horario de oficina. Aquí ves dónde leer lo que pide cada una de tus campañas y qué le pasa a tu petición si no lo cumple. Cómo se monta la petición: API de leads: enviar un lead (referencia).

Dónde se leen

• En tu guía de integración, apartado 5. Requirements of your campaigns: una sección por cada campaña activa que tienes asignada, con el título Campaign <número> · <nombre> (<país>). Está en inglés.
• En la ficha de cada oferta del portal, tarjeta Requisitos del lead, en castellano: La ficha de una oferta: integración, requisitos, horario y material.

Los dos se calculan al abrirlos, con lo que la red tenga configurado en ese momento. Si guardaste la guía en PDF o la imprimiste, esa copia no cambia: vuelve a abrirla cuando la red te diga que algo ha cambiado. La plataforma no te avisa sola.

Que una campaña salga en el apartado 5 no garantiza que tenga plaza: los topes no se ven ahí.

Qué pueden pedir

Si la campaña no pide nada más, la guía dice No extra requirements: only the mandatory parameters of section 2.1. The optional parameters of section 2.2 are accepted, but not required.

Si pide algo, sale una tabla con una fila por campo o pregunta:

• MANDATORY: tiene que venir y cumplir lo que dice Details. En la oferta, Obligatorio.
• IF PROVIDED: puedes no mandarlo, pero si lo mandas tiene que cumplirlo. En la oferta, Si lo mandas. Un valor vacío, sólo espacios o una lista vacía cuenta como no mandado; un false sí es un valor.

Lo básico (correo, país, IP, token y fuente) se exige siempre, lo pida la campaña o no.

Los requisitos se comprueban al llegar el lead, antes de guardarlo, sobre lo que mandaste tal cual. Si no los cumple, recibes missing_field o invalid_field con el field que falla, y el lead no se guarda, no se entrega y no gasta tope: corrígelo y reenvíalo. Llega el primer fallo: primero los campos (nombre, apellidos, teléfono, género, fecha, dirección, código postal, ciudad, provincia, SubID y navegador) y después las preguntas, en su orden. Los mensajes: API de leads: mensajes y códigos de error.

Los formatos

• En los teléfonos no cuentan espacios, puntos, guiones ni paréntesis.
• Los límites de caracteres cuentan todo menos los espacios de los extremos: los de dentro, el + y los guiones, sí.
• La edad mínima o máxima se calcula con la fecha de hoy.
• Manda los teléfonos con + y prefijo. Un 34600000001 sin + pasa el formato y después se completa como +3434600000001.

Preguntas propias de la campaña

Van dentro de custom_data, con la clave exacta, mayúsculas incluidas, que da la guía en la columna del parámetro (custom_data.tipo_vivienda se manda como "custom_data": {"tipo_vivienda": "Piso"}).

• Si la pregunta tiene respuestas permitidas, Details las lista (One of: Piso, Casa.). Se comparan sin mayúsculas, sin tildes y sin espacios de más: piso vale por Piso. La ñ no se iguala a la n.
• La respuesta tiene que ser un valor suelto: una lista o un objeto se rechazan. Un true o false se compara como el texto true o false.

Duplicados

Bajo cada campaña, la guía dice cómo cuenta los duplicados (Duplicates: …). La regla:

• Se compara con los leads ya guardados en esa misma campaña: el mismo correo o, si lo mandas, el mismo teléfono. Entre campañas distintas no se mira.
• Por defecto cuenta para siempre y cuenta todos los guardados, también los que el comprador rechazó o no llegaron a entregarse. La campaña puede limitarlo a unos días (in the last 30 days) o a los aceptados (counting only the leads accepted by the buyer).
• Un lead rechazado al llegar (por requisitos, horario o formato) no se guarda: al reenviarlo corregido no cuenta como duplicado.

Horario de recepción

Si la campaña tiene horario, la guía lo dice bajo ella: Receiving hours: Monday to Friday, 09:00–20:00 (Europe/Madrid time). Outside these hours the lead is rejected with outside_schedule.

• La hora final no entra: con 09:00–20:00, un lead de las 20:00:00 ya está fuera.
• La hora es la de la zona de la campaña, con sus cambios de hora.
• Pueden salir días concretos sin recepción.

Fuera de horario recibes outside_schedule con opens_at, la próxima apertura. El lead no se guarda: reenvíalo a partir de esa hora. Detalle en API de leads: mensajes y códigos de error.

Si mandas id_campaign y si no

• Con id_campaign, sólo se prueba esa campaña, si la tienes asignada y activa con la misma fuente. El país del lead no se compara con el de la campaña.
• Sin id_campaign, se prueban las campañas de ese país y esa fuente que tienes asignadas, en orden al azar, y el lead va a la primera que esté abierta, cumpla sus requisitos y tenga plaza en su tope diario. El mismo lead puede ir a campañas distintas en dos envíos.

Sin id_campaign, si no lo acepta ninguna, recibes el primer rechazo por requisitos, si lo hubo; si no, outside_schedule si todas estaban cerradas, y si no, no_campaign_available. Por eso conviene mandar siempre id_campaign.

Relacionado

• API de leads: enviar un lead (referencia)
• API de leads: mensajes y códigos de error
• La ficha de una oferta: integración, requisitos, horario y material
• Tu guía de la API (API Docs)