Endpoints
URL base:https://api-sandbox.y.uno/v1
- Crear campaña
- Obtener campaña
- Listar campañas
- Actualizar estado de la campaña
- Crear reglas
- Obtener regla
- Actualizar regla
- Actualizar estado de la regla
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.Reglas de límite de frecuencia
Controlan la frecuencia de las comunicaciones para evitar enviar demasiados mensajes al mismo usuario.- Tanto
USER_COMMS_PER_DAYcomoUNIQUE_BY_USERrequieren que el campouser_idesté presente en la metadata del pago. USER_COMMS_PER_DAYno requiere el campoconditional. Proporciona solovaluescon el límite diario.UNIQUE_BY_USERno requierevaluesniconditional. Solo incluye elrule_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 sobreBETWEENconAMOUNT_AND_CURRENCY: al usarBETWEENconAMOUNT_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 estadoACTIVEde forma predeterminada. Guarda eliddevuelto para el siguiente paso.
Paso 2: agrega reglas de segmentación
Define qué pagos rechazados deben activar esta campaña. Usa elid de la campaña del Paso 1.
- El estado del pago sea
DECLINEDY - La moneda sea
COPY - 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:
PATCHcon{"status": "PAUSED"} - Reanuda una campaña pausada:
PATCHcon{"status": "ACTIVE"} - Desactiva una regla específica sin eliminarla:
PATCH /rules/{rule_id}/statuscon{"status": "INACTIVE"} - Finaliza una campaña de forma permanente:
PATCHcon{"status": "COMPLETED"}
Ejemplos de casos de uso
- 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:
- 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:
- 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:
- 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:
- 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 ISO14(número de tarjeta inválido),43(tarjeta robada) y59(sospecha de fraude) se excluyen porque no deben recibir comunicaciones de recuperación.