Saltar al contenido principal
Aprende a integrarte con la API de Campaigns de Yuno para automatizar comunicaciones personalizadas de recuperación de pagos rechazados.

Endpoints

URL base: https://api-sandbox.y.uno/v1

Descripción general

La API de Campaigns te permite crear campañas de comunicación automatizadas que se activan cuando se rechaza el pago de un cliente. Cuando un evento de pago coincide con las reglas de segmentación de tu campaña, Yuno envía automáticamente un mensaje personalizado al cliente por el canal configurado (WhatsApp o llamada telefónica), lo que ayuda a recuperar la transacción fallida.

Conceptos clave

  • Campaña: define a quién dirigirse, por qué canal y cuándo enviar las comunicaciones.
  • Reglas: condiciones asociadas a una campaña que determinan qué pagos rechazados califican. Todas las reglas activas deben cumplirse para que un pago active la campaña (lógica AND).
  • Programación: controla la ventana horaria diaria y la zona horaria para enviar las comunicaciones.
  • Duración: las fechas de inicio y fin durante las cuales la campaña está activa.

Cómo funciona

Ejemplo: creas una campaña dirigida a pagos rechazados en Colombia con montos superiores a 50,000 COP. Cuando se rechaza el pago de 80,000 COP de un cliente colombiano, Yuno le envía automáticamente un mensaje de WhatsApp con una sugerencia personalizada de recuperación.

Autenticación

Todas las solicitudes a la API requieren los siguientes encabezados:

Modelos de datos

Objeto de campaña

Objeto de regla

Referencia de tipos de regla

Las reglas definen qué pagos rechazados califican para una campaña. Todas las reglas activas de una campaña deben cumplirse (lógica AND) para que se active una comunicación.

Reglas de datos del pago

Estas reglas evalúan datos disponibles directamente en el evento de pago.

Reglas de datos enriquecidos

Estas reglas evalúan datos enriquecidos de la transacción (método de pago, proveedor, detalles de la tarjeta, etc.).

Reglas de metadata

Evalúan campos de metadata personalizados asociados al pago.
Ejemplo: dirígete a los pagos de una vertical de negocio específica:

Reglas de límite de frecuencia

Controlan la frecuencia de las comunicaciones para evitar enviar demasiados mensajes al mismo usuario.
Notas importantes sobre las reglas de límite de frecuencia:
  • Tanto USER_COMMS_PER_DAY como UNIQUE_BY_USER requieren que el campo user_id esté presente en la metadata del pago.
  • USER_COMMS_PER_DAY no requiere el campo conditional. Proporciona solo values con el límite diario.
  • UNIQUE_BY_USER no requiere values ni conditional. Solo incluye el rule_type.

Referencia de operadores condicionales

Estos operadores pertenecen al motor de reglas propio de Communications Campaigns. No son los operadores de enrutamiento: AMOUNT con BETWEEN en el enrutamiento toma dos valores más un campo currency aparte, y rechaza un tercero. Consulta Condiciones de enrutamiento.
Nota sobre BETWEEN con AMOUNT_AND_CURRENCY: al usar BETWEEN con AMOUNT_AND_CURRENCY, proporciona 3 valores: ["min", "max", "currency"]. Para los demás tipos de regla, proporciona 2 valores: ["min", "max"].

Primeros pasos

Paso 1: crea una campaña

Define a quién dirigirte, qué canal usar y cuándo se deben enviar las comunicaciones.
Nota: la campaña se crea con estado ACTIVE de forma predeterminada. Guarda el id devuelto para el siguiente paso.

Paso 2: agrega reglas de segmentación

Define qué pagos rechazados deben activar esta campaña. Usa el id de la campaña del Paso 1.
Esta campaña ahora activará un mensaje de WhatsApp cuando:
  • El estado del pago sea DECLINED Y
  • La moneda sea COP Y
  • El monto sea mayor que 50,000 Y
  • El usuario haya recibido menos de 2 comunicaciones hoy

Paso 3: verifica tu campaña

Confirma que la campaña está configurada correctamente junto con sus reglas.

Paso 4: monitorea y administra

  • Pausa una campaña temporalmente: PATCH con {"status": "PAUSED"}
  • Reanuda una campaña pausada: PATCH con {"status": "ACTIVE"}
  • Desactiva una regla específica sin eliminarla: PATCH /rules/{rule_id}/status con {"status": "INACTIVE"}
  • Finaliza una campaña de forma permanente: PATCH con {"status": "COMPLETED"}

Ejemplos de casos de uso

  1. Recuperación básica de pagos rechazados

Envía un mensaje de WhatsApp a clientes en México cuyos pagos con tarjeta son rechazados. Campaña:
Reglas:

  1. Recuperación de transacciones de alto valor mediante llamada telefónica

Llama a los clientes cuyas transacciones superiores a 500 USD fueron rechazadas. Campaña:
Reglas:

  1. Recuperación por proveedor específico con rango de monto

Dirígete a los pagos rechazados de un proveedor específico dentro de un rango de monto. Reglas:

  1. Segmentación basada en metadata

Dirígete a segmentos de clientes específicos usando la metadata del pago (por ejemplo, la vertical de negocio o el nivel del cliente). Reglas:

  1. Excluir códigos de respuesta específicos

Envía mensajes de recuperación para todos los pagos rechazados, excepto aquellos con códigos de respuesta específicos que indican fraude o problemas permanentes. Reglas:
Nota: los códigos ISO 14 (número de tarjeta inválido), 43 (tarjeta robada) y 59 (sospecha de fraude) se excluyen porque no deben recibir comunicaciones de recuperación.

Manejo de errores

Todas las respuestas de error siguen un formato consistente:

Códigos de estado HTTP

Errores de validación comunes