Convercus

Convercus es una plataforma SaaS de fidelización y cupones que ayuda a marcas y comercios minoristas a aumentar la frecuencia de compra, el valor de la cesta y las tasas de recompra a través de programas de fidelización omnicanal y campañas de cupones personalizadas.

Esta integración es mantenida por Convercus.

Acerca de la integración

La integración de Braze y Convercus es bidireccional: los datos de fidelización fluyen hacia Braze en tiempo real como atributos personalizados, eventos personalizados y compras, y los Canvas y Campaigns de Braze pueden desencadenar acciones de fidelización en Convercus a través de webhooks. Usa el nivel de miembro sincronizado, el saldo de puntos, las compras y la actividad de cupones en Segments, Liquid y contenido conectado. Desde los recorridos de Braze, también puedes asignar cupones, registrar, acumular y canjear transacciones de puntos, y actualizar las preferencias de suscripción de correo electrónico en Convercus.

Convercus aloja la integración, por lo que no necesitas instalar infraestructura adicional. Mientras que la mayoría de los conectores de fidelización solo envían datos en una dirección, Convercus cierra el ciclo: reacciona en Braze ante un evento de fidelización, ejecuta una acción en Convercus y mide el resultado de vuelta en Braze.

Ejemplos

• Celebración de ascenso de nivel: Cuando un miembro sube de nivel en un programa de fidelización en Convercus, desencadena un Canvas personalizado en Braze con un mensaje de bienvenida, un beneficio exclusivo del nivel y el nuevo nivel y saldo de puntos del miembro.
• Bonificaciones de cumpleaños e hitos: Desde un recorrido de Braze, registra puntos de bonificación en Convercus en el cumpleaños o aniversario de un miembro, y luego envía un mensaje de celebración confirmando el nuevo saldo.
• Recuperación de miembros inactivos: Para miembros inactivos, haz que Braze asigne un cupón personalizado en Convercus a través de un webhook y lo entregue por correo electrónico, push y mensajes dentro de la aplicación.
• Saldo de puntos en vivo en la mensajería: Usa contenido conectado para obtener el saldo de puntos en tiempo real de un miembro en Braze Liquid, impulsando cadencias como “estás a X puntos de tu próxima recompensa”.

Requisitos previos

Antes de empezar, necesitas lo siguiente:

Necesitas un identificador de usuario coherente entre los sistemas: el valor utilizado como external_id (o el tipo de identificador elegido) en Braze debe coincidir con el identificador de miembro correspondiente en Convercus. De lo contrario, los eventos no se atribuyen al perfil correcto.

Integración

Paso 1: Configurar Braze en Convercus Selfservice

En Convercus Selfservice (la interfaz de administración orientada al cliente; ábrela usando la URL que te proporcione tu director de cuentas de Convercus), abre el programa que deseas conectar a Braze y usa la tarjeta de integración de Braze para:

1. Configurar la conexión con Braze completando el formulario de integración:

   Campo	Descripción
   apiKey	Tu clave de API REST de Braze (con el permiso users.track).
   apiEndpoint	Tu endpoint REST de Braze, por ejemplo https://rest.iad-01.braze.com.
   Tipo de identificador	external_id o user_alias. Determina cómo se asocian los miembros de Convercus con los perfiles de usuario de Braze.
   defaultOptins	Selección múltiple de los canales de adhesión voluntaria del programa (de membershipOptins). Se usa como valor predeterminado para el webhook de suscripción de correo electrónico cuando la solicitud omite optins. La configuración de Braze se considera incompleta hasta que se seleccione al menos uno.

2. Crear una clave de API para las llamadas entrantes. Crea una credencial X-Convercus-Key por programa. La clave sin procesar se muestra una sola vez al crearla, con el prefijo cvc_ (formato: cvc_<base64url>). Almacénala en Braze cuando configures las Campaigns de webhook y los bloques de contenido conectado en el paso 2. Las claves se pueden revocar en cualquier momento desde la misma tarjeta; la revocación surte efecto de inmediato.

Después de guardar la conexión con Braze, Convercus comienza a transmitir de inmediato los eventos de fidelización de ese programa a Braze. No se requiere ninguna configuración de infraestructura adicional.

Nota

Cada programa de Convercus se configura de forma independiente. Un solo tenant de Convercus puede conectar diferentes programas a diferentes espacios de trabajo de Braze, cada uno con su propia clave de API.

Paso 2: Configurar webhooks en Braze

Para desencadenar acciones de Convercus desde un Canvas o una Campaign, crea acciones de webhook en Braze que llamen al servicio de integración de Convercus. Todas las solicitudes deben incluir los siguientes encabezados:

• X-Convercus-Key: cvc_… - la clave de API generada en el paso 1.
• Content-Type: application/json

Todos los endpoints se encuentran bajo la URL base <SERVICE_HOST>/v1/programs/{programId}. Reemplaza <SERVICE_HOST> con el host proporcionado por tu director de cuentas de Convercus y {programId} con tu ID de programa de Convercus.

Ejemplo — asignar un cupón a un miembro:

1
2
3
4
5
6
7
8
POST <SERVICE_HOST>/v1/programs/{programId}/campaigns/{couponId}/assign
X-Convercus-Key: cvc_…
Content-Type: application/json

{
  "account_id": "{{custom_attribute.${convercus_account_id}}}",
  "braze_campaign_id": "{{campaign.${api_id}}}"
}

Las demás acciones siguen el mismo patrón, cambiando solo el endpoint y el cuerpo. Por ejemplo, un registro de puntos se envía a /members/{accountId}/bookings con booking_type (EARNBOOKING o BURNBOOKING), booking_type_code, points y reason; el webhook de suscripción de correo electrónico se envía a /subscriptions/email con account_id y status (allowed o declined).

Respuestas de error y reintentos

Advertencia

Las respuestas 5xx no son seguras para reintentar sin confirmar el éxito; estas operaciones no son idempotentes, y los reintentos pueden duplicar la asignación de cupones o la acreditación de puntos. Desactiva el reintento automático de Braze en 5xx para estos webhooks, o configura un número máximo de reintentos muy bajo.

Paso 3: Verificar los datos en Braze

1. Desencadena un evento de fidelización en Convercus, por ejemplo, un cambio de nivel de estado, una transacción de puntos o un canje de cupón.
2. Abre el usuario correspondiente en Braze y confirma que el atributo personalizado, evento personalizado o compra esperados aparecen en el perfil. Los usuarios se asocian por external_id (o el tipo de identificador elegido en el paso 1).
3. Para verificar la dirección opuesta, ejecuta un envío de prueba en Braze que llame a uno de los webhooks del paso 2 y confirma la acción en Convercus (cupón asignado, puntos registrados o suscripción actualizada).

Usa Convercus con Braze

Paso 1: Personaliza mensajes con datos de fidelización sincronizados

Una vez que la integración está en vivo, los eventos de Convercus llegan a cada perfil de usuario en Braze a través del endpoint /users/track y se pueden usar como cualquier otro dato nativo:

1. Usa atributos personalizados de fidelización (por ejemplo, convercus_status_level, convercus_balance) en Segments para segmentar a titulares de nivel, miembros con saldo alto o usuarios recientemente degradados.
2. Usa eventos personalizados (por ejemplo, convercus_status_level_changed, eventos de cupones y membresías) como pasos desencadenantes en Canvas o como filtros en campañas de reactivación.
3. Haz referencia a cualquiera de estos campos en Liquid para personalización dentro del mensaje (líneas del asunto, cuerpo del texto, títulos push).
4. Usa eventos purchase transmitidos desde Convercus para impulsar recorridos basados en productos (reposición, venta cruzada por categoría, solicitudes de reseña post-compra).

Atributos personalizados

Nota

Dentro de un espacio de trabajo de Braze, los miembros se identifican de forma única mediante convercus_account_id. convercus_user_id identifica a la persona subyacente en múltiples programas Convercus y se proporciona para análisis entre programas; para segmentación dentro de Braze, usa convercus_account_id.

Mapeado de email_subscribe

Eventos personalizados

Compras

Las transacciones de Convercus de tipo EARNTRANSACTION (puntos ganados por gasto del cliente) se reportan a Braze como compras y se contabilizan en los análisis de ingresos de Braze, la segmentación RFM y las características predictivas, usando el ID de transacción como identificador de producto y el monto y la moneda de la transacción como precio y moneda.

Las transacciones de tipo PAYWITHPOINTSTRANSACTION (quema de puntos) no se reportan como compras; fluyen como el evento personalizado convercus_account_transaction para que sigan disponibles para segmentación. Las reversiones y cancelaciones de transacciones de acumulación se reportan como compras con precio negativo, manteniendo los ingresos de Braze alineados con Convercus.

Paso 2: Obtén datos de fidelización en vivo con contenido conectado

Para valores que deben estar actualizados en el momento del envío —saldo de puntos actual, cupones activos, último nivel— llama a Convercus desde Braze usando contenido conectado en lugar de depender del atributo sincronizado más reciente. Ambos endpoints se encuentran bajo la misma URL base que los webhooks y requieren el encabezado X-Convercus-Key.

Los endpoints de contenido conectado siempre devuelven HTTP 200 en fallos esperados para que las plantillas Liquid puedan ramificarse según el campo error:

Ejemplo — renderizar el estado de fidelización de un miembro (nivel, puntos y ofertas activas):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{% connected_content
  https://<SERVICE_HOST>/v1/programs/{programId}/members/{{custom_attribute.${convercus_account_id}}}/profile
  :headers { "X-Convercus-Key": "cvc_…" }
  :content_type application/json
  :cache_max_age 300
  :retry
  :save member
%}

{% connected_content
  https://<SERVICE_HOST>/v1/programs/{programId}/members/{{custom_attribute.${convercus_account_id}}}/coupons?lang=en
  :headers { "X-Convercus-Key": "cvc_…" }
  :content_type application/json
  :cache_max_age 0
  :retry
  :save coupon_data
%}

{% unless member.error %}
  <h2>Your Loyalty Status</h2>
  <p>Hi {{member.first_name}}, you're a <strong>{{member.tier_name}}</strong> member.</p>
  <p>Points balance: <strong>{{member.points_balance}}</strong></p>

  {% if coupon_data.coupons.size > 0 %}
    <h3>Your Active Offers</h3>
    {% for coupon in coupon_data.coupons %}
      <p><strong>{{coupon.title}}</strong> — valid until {{coupon.valid_to}}</p>
    {% endfor %}
  {% endif %}
{% endunless %}

Envuelve siempre el contenido conectado en condicionales (verifica member.error y coupons vacío) para que un fallo temporal de consulta nunca envíe un mensaje roto. Almacena en caché el perfil (cache_max_age 300) pero no los cupones (cache_max_age 0), ya que el estado de los cupones puede cambiar entre envíos.

Consideraciones

• Latencia: Los eventos de Convercus a Braze se propagan a través de Kafka y llegan a Braze en segundos bajo carga normal.
• Límites de velocidad de Braze: La integración reintenta automáticamente ante respuestas 429, respetando el encabezado x-ratelimit-retry-after de Braze con retirada exponencial.
• Caché de contenido conectado: Braze almacena en caché las respuestas de contenido conectado durante varios minutos de forma predeterminada. Para valores que deben ser exactos en el momento del envío (como el saldo de puntos), reduce o evita la ventana de caché en la llamada de contenido conectado.
• Una configuración por programa: Cada programa de fidelización se mapea a un único espacio de trabajo de Braze. Para conectar un segundo espacio de trabajo, configúralo en un programa separado.
• Observabilidad: Las estadísticas de llamadas a la API por programa y el historial de errores (en ambas direcciones) se conservan durante 90 días y están disponibles desde la tarjeta de integración de Braze en Selfservice.

Solución de problemas

• Los eventos no aparecen en Braze: Verifica que el valor utilizado como identificador (seleccionado en el paso 1) coincida con el external_id del usuario (o el tipo de identificador elegido) en Braze. Los identificadores que no coinciden provocan que los eventos se atribuyan al perfil incorrecto o se descarten.
• El webhook devuelve 401: Falta el encabezado X-Convercus-Key o la clave de API cvc_… ha sido revocada. Regenera la clave en Selfservice y actualiza la acción del webhook en Braze.
• El webhook devuelve 400: A la solicitud le falta Content-Type: application/json, o la carga útil no coincide con el esquema documentado. Para el webhook de suscripción de correo electrónico, un 400 también significa que las adhesiones voluntarias solicitadas son desconocidas para el programa o que no hay ninguna configurada.
• Depuración más profunda: Revisa las estadísticas de llamadas a la API por programa y el historial de errores en la tarjeta de integración de Braze en Selfservice, o contacta a tu representante de Convercus.