Convercus

A Convercus é uma plataforma SaaS de fidelidade e cupons que ajuda marcas e varejistas a aumentar a frequência de compra, o valor do carrinho e as taxas de recompra por meio de programas de fidelidade omnicanal e campanhas de cupons personalizadas.

Essa integração é mantida pela Convercus.

Sobre a integração

A integração entre a Braze e a Convercus é bidirecional: dados de fidelidade fluem para a Braze em tempo real como atributos personalizados, eventos personalizados e compras, e Canvas e Campaigns da Braze podem disparar ações de fidelidade na Convercus por meio de webhooks. Use dados sincronizados de nível de membro, saldo de pontos, compras e atividade de cupons em Segments, Liquid e Conteúdo conectado. A partir de jornadas da Braze, você também pode atribuir cupons, registrar, acumular e resgatar transações de pontos, e atualizar preferências de inscrição de e-mail na Convercus.

A Convercus hospeda a integração, então você não precisa instalar infraestrutura adicional. Enquanto a maioria dos conectores de fidelidade apenas envia dados em uma direção, a Convercus fecha o ciclo: reaja na Braze a um evento de fidelidade, execute uma ação na Convercus e meça o resultado de volta na Braze.

Casos de uso

1. Celebração de subida de nível: Quando um membro sobe de nível no programa de fidelidade na Convercus, dispare um Canvas personalizado na Braze com uma mensagem de boas-vindas, um benefício exclusivo do nível e o novo nível e saldo de pontos do membro.
2. Bônus de aniversário e marcos: A partir de uma jornada da Braze, registre pontos bônus na Convercus no aniversário ou data comemorativa de um membro e envie uma mensagem de celebração confirmando o novo saldo.
3. Recuperação de membros inativos: Para membros inativos, faça a Braze atribuir um cupom personalizado na Convercus por meio de um webhook e entregue-o por e-mail, push e mensagens no app.
4. Saldo de pontos em tempo real nas mensagens: Use Conteúdo conectado para buscar o saldo de pontos em tempo real de um membro na Braze via Liquid, alimentando cadências como “faltam X pontos para sua próxima recompensa”.

Pré-requisitos

Antes de começar, você precisa do seguinte:

Você precisa de um identificador de usuário consistente entre os sistemas: o valor usado como external_id (ou o tipo de identificador escolhido) na Braze deve corresponder ao identificador de membro correspondente na Convercus. Caso contrário, os eventos não serão atribuídos ao perfil correto.

Integração

Etapa 1: Configure a Braze no Convercus Selfservice

No Convercus Selfservice (a interface de administração voltada ao cliente — abra-a usando a URL fornecida pelo seu gerente de conta Convercus), abra o programa que você deseja conectar à Braze e use o cartão de integração Braze para:

1. Configurar a conexão com a Braze preenchendo o formulário de integração:

   Campo	Descrição
   apiKey	Sua chave da API REST da Braze (com a permissão users.track).
   apiEndpoint	Seu endpoint REST da Braze, por exemplo https://rest.iad-01.braze.com.
   Tipo de identificador	external_id ou user_alias. Determina como os membros da Convercus são associados aos perfis de usuário da Braze.
   defaultOptins	Seleção múltipla dos canais de opt-in do programa (de membershipOptins). Usado como padrão para o webhook de inscrição de e-mail quando a solicitação omite optins. A configuração da Braze é considerada incompleta até que pelo menos um seja selecionado.

2. Crie uma chave de API para chamadas de entrada. Crie uma credencial X-Convercus-Key por programa. A chave bruta é exibida uma vez na criação, com o prefixo cvc_ (formato: cvc_<base64url>). Armazene-a na Braze ao configurar as Campaigns de webhook e os blocos de Conteúdo conectado na Etapa 2. As chaves podem ser revogadas a qualquer momento no mesmo cartão; a revogação entra em vigor imediatamente.

Após salvar a conexão com a Braze, a Convercus começa imediatamente a transmitir eventos de fidelidade desse programa para a Braze. Nenhuma configuração de infraestrutura adicional é necessária.

Nota

Cada programa Convercus é configurado de forma independente. Um único tenant Convercus pode conectar diferentes programas a diferentes espaços de trabalho da Braze, cada um com sua própria chave de API.

Etapa 2: Configure webhooks na Braze

Para disparar ações da Convercus a partir de um Canvas ou Campaign, crie ações de webhook na Braze que chamem o serviço de integração da Convercus. Todas as solicitações devem incluir os seguintes cabeçalhos:

• X-Convercus-Key: cvc_… — a chave de API gerada na Etapa 1.
• Content-Type: application/json

Todos os endpoints estão sob a URL base <SERVICE_HOST>/v1/programs/{programId}. Substitua <SERVICE_HOST> pelo host fornecido pelo seu gerente de conta Convercus e {programId} pelo ID do seu programa Convercus.

Exemplo — atribuir um cupom a um membro:

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}}}"
}

As outras ações seguem o mesmo padrão, alterando apenas o endpoint e o corpo. Por exemplo, um registro de pontos envia para /members/{accountId}/bookings com booking_type (EARNBOOKING ou BURNBOOKING), booking_type_code, points e reason; o webhook de inscrição de e-mail envia para /subscriptions/email com account_id e status (allowed ou declined).

Respostas de erro e tentativas

Aviso

Respostas 5xx não são seguras para reenvio sem confirmar o sucesso — essas operações não são idempotentes, e tentativas podem duplicar a atribuição de cupons ou o crédito de pontos. Desative o reenvio automático da Braze em 5xx para esses webhooks, ou configure uma contagem máxima de tentativas muito baixa.

Etapa 3: Verifique os dados na Braze

1. Dispare um evento de fidelidade na Convercus — por exemplo, uma mudança de nível de status, uma transação de pontos ou um resgate de cupom.
2. Abra o usuário correspondente na Braze e confirme que o atributo personalizado, evento personalizado ou compra esperado aparece no perfil. Os usuários são associados por external_id (ou o tipo de identificador escolhido na Etapa 1).
3. Para verificar a direção oposta, execute um envio de teste na Braze que chame um dos webhooks da Etapa 2 e confirme a ação na Convercus (cupom atribuído, pontos registrados ou inscrição atualizada).

Use a Convercus com a Braze

Etapa 1: Personalize mensagens com dados de fidelidade sincronizados

Após a integração estar ativa, os eventos da Convercus chegam em cada perfil de usuário na Braze por meio do endpoint /users/track e podem ser usados como qualquer outro dado nativo:

1. Use atributos personalizados de fidelidade (por exemplo, convercus_status_level, convercus_balance) em Segments para segmentar detentores de nível, membros com alto saldo ou usuários recentemente rebaixados.
2. Use eventos personalizados (por exemplo, convercus_status_level_changed, eventos de cupom e associação) como etapas de gatilho em Canvas ou como filtros em Campaigns de reengajamento.
3. Referencie qualquer um desses campos em Liquid para personalização dentro da mensagem (linhas de assunto, corpo do texto, títulos de push).
4. Use eventos de purchase transmitidos pela Convercus para alimentar jornadas baseadas em produtos (reposição, upsell de categoria, solicitações de avaliação pós-compra).

Atributos personalizados

Nota

Dentro de um espaço de trabalho da Braze, os membros são identificados de forma única por convercus_account_id. O convercus_user_id identifica a pessoa subjacente em vários programas Convercus e é fornecido para análise de dados entre programas; para segmentação dentro da Braze, use convercus_account_id.

Mapeamento de email_subscribe

Eventos personalizados

Compras

Transações da Convercus do tipo EARNTRANSACTION (pontos acumulados a partir de gastos do cliente) são reportadas à Braze como compras e contabilizadas na análise de receita da Braze, segmentação RFM e recursos preditivos — usando o ID da transação como identificador do produto e o valor e moeda da transação como preço e moeda.

Transações do tipo PAYWITHPOINTSTRANSACTION (resgate de pontos) não são reportadas como compras — elas fluem como o evento personalizado convercus_account_transaction para que permaneçam disponíveis para segmentação. Estornos e cancelamentos de transações de acúmulo são reportados como compras com preço negativo, mantendo a receita da Braze alinhada com a Convercus.

Etapa 2: Busque dados de fidelidade em tempo real com Conteúdo conectado

Para valores que precisam estar atualizados no momento do envio — saldo de pontos atual, cupons ativos, nível mais recente — chame a Convercus a partir da Braze usando Conteúdo conectado em vez de depender do atributo sincronizado mais recentemente. Ambos os endpoints estão sob a mesma URL base dos webhooks e exigem o cabeçalho X-Convercus-Key.

Os endpoints de Conteúdo conectado sempre retornam HTTP 200 em falhas esperadas para que os templates Liquid possam ramificar com base no campo error:

Exemplo — renderizar o status de fidelidade de um membro (nível, pontos e ofertas ativas):

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 %}

Sempre envolva o Conteúdo conectado em condicionais (verifique member.error e coupons vazio) para que uma falha temporária de consulta nunca envie uma mensagem quebrada. Faça cache do perfil (cache_max_age 300), mas não dos cupons (cache_max_age 0), já que o status do cupom pode mudar entre os envios.

Considerações

• Latência: Os eventos da Convercus para a Braze se propagam por Kafka e chegam à Braze em segundos sob carga normal.
• Limites de taxa da Braze: A integração faz tentativas automaticamente em respostas 429, respeitando o cabeçalho x-ratelimit-retry-after da Braze com backoff exponencial.
• Cache de Conteúdo conectado: A Braze faz cache das respostas de Conteúdo conectado por vários minutos por padrão. Para valores que precisam ser exatos no momento do envio (como saldo de pontos), reduza ou ignore a janela de cache na chamada de Conteúdo conectado.
• Uma configuração por programa: Cada programa de fidelidade é mapeado para um único espaço de trabalho da Braze. Para conectar um segundo espaço de trabalho, configure-o em um programa separado.
• Observabilidade: Estatísticas de chamadas de API por programa e histórico de erros (em ambas as direções) são retidos por 90 dias e estão disponíveis no cartão de integração Braze no Selfservice.

Solução de problemas

• Eventos não aparecem na Braze: Verifique se o valor usado como identificador (selecionado na Etapa 1) corresponde ao external_id (ou tipo de identificador escolhido) do usuário na Braze. Identificadores incompatíveis fazem com que os eventos sejam atribuídos ao perfil errado ou descartados.
• Webhook retorna 401: O cabeçalho X-Convercus-Key está ausente ou a chave de API cvc_… foi revogada. Regenere a chave no Selfservice e atualize a ação de webhook na Braze.
• Webhook retorna 400: A solicitação está sem Content-Type: application/json, ou a carga útil não corresponde ao esquema documentado. Para o webhook de inscrição de e-mail, um 400 também significa que os opt-ins solicitados são desconhecidos para o programa ou nenhum está configurado.
• Depuração mais aprofundada: Revise as estatísticas de chamadas de API por programa e o histórico de erros no cartão de integração Braze no Selfservice, ou entre em contato com seu representante Convercus.