Entregar los leads por API (Host & Post)

Para qué sirve

Con Host & Post (API), cada lead que entra en la campaña se envía en el momento al sistema del anunciante, con una petición a la dirección que él te dé. Su respuesta decide si el lead es una venta.

Quién puede usarlo

Necesitas Permitido en Gestionar (Editar / Operar), en la fila Campañas de Affiliate Cloud del panel de permisos. Si no lo tienes, pídeselo a un administrador de tu cuenta. Una campaña nueva la crea un administrador: Crear una campaña.

Paso a paso

1. Abre la ficha de la campaña y la pestaña Integración. Elige Host & Post (API) ①; en una campaña nueva ya viene elegido.

   

2. En Método HTTP ②, el que pida el anunciante:
   • POST (JSON) y PUT: el cuerpo es la plantilla rellena. Si no pones una cabecera Content-Type, se añade application/json.
   • POST (x-www-form-urlencoded): se envía como un formulario; si la plantilla es JSON, cada clave va como un campo.
   • GET (Query String): sin cuerpo; las claves de la plantilla van en la dirección (ver «Lo que conviene saber»).
3. En Endpoint URL ③, la dirección que te dé el anunciante, empezando por https:// o http://. Sin ella, la campaña no se puede activar, salvo que tenga autenticación OAuth2, que lleva su propia dirección de envío.
4. Si el anunciante pide cabeceras, en HTTP Headers pulsa Añadir Header ④ y escribe el nombre y el valor, por ejemplo x-api-key y TU_CLAVE. Una fila sin nombre no se guarda. Los valores van tal cual: en las cabeceras no se sustituyen variables.
5. En Mapeo del Body / Payload ⑤, escribe lo que espera el anunciante, con una variable donde va cada dato del lead:

{
  "nombre": "{name}",
  "telefono": "{phone}",
  "email": "{email}",
  "referencia": "{id_lead}"
}

Qué variables hay y en qué formato sale cada una: Variables de la plantilla de entrega. 6. Si el anunciante quiere algún dato de otra forma (sin prefijo, con otros valores, como número sin comillas), añade Reglas de Transformación de Datos: Reglas de transformación: adaptar los datos a lo que pide el anunciante. 7. En Mapeo de Respuestas (Validación S2S), di qué tiene que responder el anunciante para dar el lead por aceptado: Cómo se decide si el anunciante aceptó el lead (Mapeo de Respuestas). 8. Pulsa Guardar Cambios. Si la campaña estaba activa y le falta la Endpoint URL, se guarda pausada y la ficha lo avisa.

Si el anunciante pide un token de acceso (Client ID y Client Secret), se configura aparte, debajo: Autenticación OAuth2 de la entrega por API.

Antes de activarla: el lead de prueba

Más abajo, en la sección Enviar un lead de prueba, el botón Enviar lead de prueba manda un lead con la configuración guardada y enseña la respuesta del anunciante tal cual. No se guarda, no se factura y no cuenta en ningún tope.

Ojo: en una campaña sin autenticación OAuth2 guardada no hay entorno de pruebas. El lead de prueba va al destino real del anunciante, el mismo que los leads de verdad, y el anunciante puede llamar al teléfono que escribas. La pantalla lo avisa en rojo ① y pide confirmación antes de enviarlo. Con autenticación OAuth2 eliges el entorno, y el de producción también es el real: también pide confirmación.

Cómo se usa y qué dice cada resultado: Enviar un lead de prueba desde la ficha de la campaña.

Qué pasa con cada lead

Antes de enviarlo, el lead pasa sus comprobaciones (requisitos, horario, topes, duplicado), se guarda y recibe su número. Después:

• se espera la respuesta del anunciante 15 segundos como máximo;
• se envía una sola vez. Si no hay respuesta, no se reintenta: puede que al anunciante sí le llegara. Con autenticación OAuth2 hay una excepción: si el anunciante rechaza el token guardado, se pide otro y se repite una vez;
• cuenta como venta sólo si el anunciante lo acepta. Entonces suma en los topes de la asignación y se avisa al afiliado por su postback, si lo tiene configurado y el lead trae su subid_lead.

Todo lo demás que puede recibir el afiliado, en Por qué se rechaza el lead de un afiliado. En el Directorio de Leads, el botón Log de cada lead enseña lo que se envió y lo que respondió el anunciante, con los datos personales tapados.

Lo que conviene saber

• Cada variable, entre comillas, también la que deba salir como número: eso lo hace la regla «Enviar como número». Si una variable va sin comillas, la plantilla deja de ser JSON y entonces ningún valor se escapa: un nombre con comillas puede romper el envío. La ficha lo recuerda bajo la plantilla; el alta, no.
• Una plantilla que no es JSON también vale: con la forma a=1&b=2, cada valor se codifica para la dirección; con cualquier otra forma, los valores van sin escapar.
• Una plantilla vacía no se avisa ni al guardar ni en la lista de campañas: la campaña puede estar activa y responder campaign_not_ready a cada lead.
• Sin Mapeo de Respuestas (Validación S2S), las reglas estándar aceptan mucho: un JSON con "status": "success", con "error": false o con un "Message" que contenga «exitoso», y también una respuesta que no sea JSON ni una página web y contenga «success» o «true» en cualquier parte, incluso «unsuccessful». Con el mapeo puesto, si la respuesta no trae su clave, también se aplican estas reglas. Para que sólo cuente una respuesta con la clave, usa el modo estricto: Cómo se decide si el anunciante aceptó el lead (Mapeo de Respuestas).
• Un error HTTP del anunciante le llega al afiliado como rechazo, también un 500, que es un fallo del anunciante: recibe rejected_by_advertiser, no advertiser_unreachable.
• Con autenticación OAuth2, los leads van a la dirección de envío del entorno de la autenticación, no a la Endpoint URL.
• Un lead rechazado o no entregado ya está guardado. Si el afiliado lo reenvía a la misma campaña, cuenta como duplicado, salvo que en Requisitos del lead esté marcada la casilla de contar sólo los aceptados o haya pasado la ventana de días que tenga configurada: Requisitos del lead de una campaña: qué se exige y qué se rechaza.
• No hay botón para reenviar un lead.
• Con GET (Query String), los parámetros que escribas en la Endpoint URL detrás de ? no se envían: los sustituyen las claves de la plantilla. Si el anunciante pide una clave en la dirección, ponla también en la plantilla.
• Cambiar la campaña a Envío por Email y guardar borra las cabeceras y las reglas, y el método vuelve a POST (JSON): Ficha de campaña: las cuatro pestañas.

Errores frecuentes

Relacionado

• Variables de la plantilla de entrega
• Reglas de transformación: adaptar los datos a lo que pide el anunciante
• Cómo se decide si el anunciante aceptó el lead (Mapeo de Respuestas)
• Autenticación OAuth2 de la entrega por API
• Enviar un lead de prueba desde la ficha de la campaña
• Por qué se rechaza el lead de un afiliado