Webhooks - Comunicações - BonifiQ Developers

Este documento descreve os payloads de webhook relacionados a comunicações com clientes. Campo comum adicional: todos os payloads de comunicação abaixo também expõem PointsBalance no nível raiz, usando o Objeto Saldo de Pontos para o saldo consolidado de pontos e cashback do cliente após o processamento do evento. O campo legado Customer.PointsBalance permanece disponível por compatibilidade.

Cupons

Communication_CouponsToUse

Enviado quando uma comunicação é disparada referente a cupons disponíveis para o cliente usar.

{
  "CouponType": 1,
  "ValidDateEnd": "2025-12-31T23:59:59Z",
  "CouponValue": 10.00,
  "CouponCode": "BEMVINDO10",
  "Customer": { ... },
  "PointsBalance": { ... }
}

number

required

Tipo do cupom. Veja CouponType

string

Data de expiração (ISO 8601), se houver. Pode ser null.

number

required

Valor do cupom (ex: 10.0 para 10% ou R$10,00)

string

required

Código para resgate

object

required

Objeto Cliente

object

required

Objeto Saldo de Pontos

Resgate de Recompensas

Para acompanhar todos os resgates e cancelamentos independentemente das regras de comunicação, use Reward_Redeemed (código 30) e Reward_Cancelled (código 31).

Communication_RewardCustomRedeemNotification

Enviado após um cliente resgatar pontos por uma recompensa personalizada.

{
  "Points": 500,
  "RewardDescription": "Caneca Grátis com Logo",
  "Coupon": "RESGATECAN123",
  "Customer": { ... },
  "PointsBalance": { ... }
}

number

required

Pontos gastos no resgate

string

required

Descrição da recompensa

string

Código de cupom gerado, se aplicável. Pode ser null.

object

required

Objeto Cliente

object

required

Objeto Saldo de Pontos

Ganho de Pontos

Estes tópicos são enviados quando um cliente ganha pontos. A estrutura varia conforme o tipo de objetivo. Campos Base Comuns:

number

required

Pontos ganhos neste evento

number

required

Tipo de objetivo. Veja ObjectiveType

object

required

Objeto Cliente

object

required

Objeto Saldo de Pontos

Communication_EarnPurchasePoints

Ganho de pontos por uma compra.

{
  "EarnedPoints": 150,
  "ObjectiveType": 0,
  "Customer": { ... },
  "PointsBalance": { ... },
  "CashbackEarned": 1.50,
  "CashbackEarnedFormatted": "R$ 1,50",
  "ValidDate": "2026-04-15T00:00:00Z",
  "ValidDateFormatted": "15/04/2026",
  "OrderDate": "2025-04-15T10:05:00Z",
  "OrderDateFormatted": "15/04/2025",
  "OrderValue": 150.00,
  "OrderValueFormatted": "R$ 150,00",
  "PercentCashbackEarned": 0.01,
  "PercentCashbackEarnedFormatted": "1,00%",
  "Date": "2025-04-15T10:05:10Z",
  "OrderId": "pedido_123",
  "PointId": 98765
}

Campos Adicionais:

number

Cashback ganho

string

Cashback ganho formatado em moeda (pt-BR)

string

Expiração dos pontos/cashback

string

Data de expiração formatada (dd/MM/yyyy)

string

required

Data do pedido

string

required

Data do pedido formatada (dd/MM/yyyy)

number

required

Valor total do pedido

string

required

Valor total do pedido formatado em moeda (pt-BR)

number

Taxa de cashback (ex: 0.01 = 1%)

string

Taxa de cashback formatada em percentual (pt-BR)

string

required

Data do registro do evento

string

required

ID do pedido no sistema de origem

number

required

ID interno do registro de ponto

Communication_EarnBirthdayPoints

Ganho de pontos como bônus de aniversário.

{
  "EarnedPoints": 100,
  "ObjectiveType": 2,
  "Customer": { ... },
  "PointsBalance": { ... },
  "BirthdayPoints": 100,
  "BirthdayBonification": "Bônus Feliz Aniversário!",
  "CouponType": 1,
  "CouponCode": "NIVERPRESENTE",
  "RedeemUrl": "https://exemplo.com/resgatar-niver"
}

Campos Adicionais:

number

required

Pontos do aniversário

string

Descrição do bônus

number

Tipo do cupom concedido

string

Código do cupom

string

URL para resgate

Communication_EarnSignupPoints

Ganho de pontos por cadastro. Usa apenas os campos base comuns.

Communication_EarnReviewPoints

Ganho de pontos por review. Usa apenas os campos base comuns.

Communication_ReferralCommunicationPoints

Ganho de pontos por indicação.

{
  "EarnedPoints": 200,
  "ObjectiveType": 4,
  "Customer": { ... },
  "PointsBalance": { ... },
  "FriendName": "Maria Souza"
}

Campo Adicional:

string

Nome do amigo indicado

Communication_EarnQuizPoints

Ganho de pontos por quiz. Usa apenas os campos base comuns.

Communication_EarnCustomObjectivePoints

Ganho de pontos por objetivo personalizado. Usa apenas os campos base comuns.

Communication_Participation

Ganho de pontos por participação em campanha.

{
  "EarnedPoints": 10,
  "ObjectiveType": 11,
  "Customer": { ... },
  "PointsBalance": { ... },
  "CashbackEarned": 2.50,
  "CashbackEarnedFormatted": "R$ 2,50",
  "PercentCashbackEarned": 0.10,
  "PercentCashbackEarnedFormatted": "10,00%",
  "CampaignId": 123,
  "CampaignName": "Campanha de participação"
}

Campos Adicionais:

number

Cashback ganho nesta participação. Pode ser 0 quando a campanha concede apenas pontos.

string

Cashback ganho formatado em moeda (pt-BR).

number

Taxa de cashback aplicada (ex: 0.10 = 10%).

string

Taxa de cashback formatada em percentual (pt-BR).

number

required

ID interno da campanha de participação.

string

required

Nome da campanha de participação.

Comunicações de Redes Sociais

Os tópicos abaixo usam a estrutura base comum:

Communication_EarnSocialMediaFollowInstagram (ObjectiveType: 5)
Communication_EarnSocialMediaFollowFacebook (ObjectiveType: 6)
Communication_EarnSocialMediaFollowLinkedin (ObjectiveType: 9)
Communication_EarnSocialMediaFollowTikTok (ObjectiveType: 10)

Alteração de Pontos

Communication_CustomerPointChangeNotification

Enviado quando há alteração manual ou diversa no saldo de pontos.

{
  "Points": -50,
  "PointsValidDate": "01/08/2025",
  "Customer": { ... },
  "PointsBalance": { ... }
}

number

required

Pontos da alteração (positivo = adição, negativo = subtração)

string

required

Data de expiração formatada

object

required

Objeto Cliente

object

required

Objeto Saldo de Pontos

Pontos Disponíveis

Communication_PointsToUse

Enviado para informar o cliente sobre seu potencial de resgate.

{
  "PointsToUse": 1500,
  "maxValueDiscount": "R$ 15,00",
  "maxPercentDiscount": "10%",
  "CashbackToUse": 15.00,
  "CashbackToUseFormatted": "R$ 15,00",
  "Customer": { ... },
  "PointsBalance": { ... }
}

number

required

Total de pontos disponíveis

string

required

Desconto monetário máximo formatado

string

required

Desconto percentual máximo formatado

number

Cashback disponível para uso. Pode ser null.

string

Cashback disponível formatado em moeda (pt-BR)

object

required

Objeto Cliente

object

required

Objeto Saldo de Pontos

Expiração de Pontos

Communication_NotifyExpirablePoints

Enviado para notificar sobre pontos próximos da expiração.

{
  "PointsToExpire": 250,
  "ExpirationAt": "2025-07-31T23:59:59Z",
  "ExpirationDate": "31/07/2025",
  "PointId": 12345,
  "ValidDate": "2025-07-31T23:59:59Z",
  "ValidDateFormatted": "31/07/2025",
  "CashbackToExpire": 2.50,
  "CashbackToExpireFormatted": "R$ 2,50",
  "Customer": { ... },
  "PointsBalance": { ... }
}

number

required

Quantidade de pontos que expirarão

string

required

Data/hora de expiração (ISO 8601)

string

required

Data formatada para exibição

number

required

ID interno do registro de ponto

string

Data de validade dos pontos (ISO 8601). Pode ser null.

string

Data de validade formatada (dd/MM/yyyy)

number

Valor de cashback que expirará. Pode ser null.

string

Valor de cashback formatado em moeda (pt-BR)

object

required

Objeto Cliente

object

required

Objeto Saldo de Pontos

Resgate de Pontos

Para acompanhar todos os resgates e cancelamentos independentemente das regras de comunicação, use Reward_Redeemed (código 30) e Reward_Cancelled (código 31).

Communication_RedeemPoints

Enviado após resgate de pontos por recompensa padrão.

{
  "CouponCode": "RESGATE5OFF",
  "CouponDescription": "Cupom de Desconto R$ 5,00",
  "Points": 500,
  "Customer": { ... },
  "PointsBalance": { ... }
}

string

required

Código do cupom gerado

string

required

Descrição da recompensa

number

required

Pontos gastos

object

required

Objeto Cliente

object

required

Objeto Saldo de Pontos

OTP (Código de Verificação)

Communication_SentOTPToCustomer

Enviado quando um código OTP é enviado ao cliente.

Nota de Segurança: Seja cauteloso ao processar OTPs via webhooks. Garanta que seu endpoint e lógica sejam seguros.

{
  "OTP": "123456",
  "Customer": { ... }
}

string

required

Senha de uso único enviada

object

required

Objeto Cliente

Níveis/Tiers

Para acompanhar mudanças efetivas de nível independentemente das regras de comunicação, use Customer_TierChanged (código 29). Os tópicos abaixo continuam sendo comunicações de subida e descida, com seu próprio payload e critérios de envio.

Communication_CustomerTierUpgradeNotification / Communication_CustomerTierDowngradeNotification

Enviado quando a mudança de nível de fidelidade do cliente atende aos critérios de comunicação de subida ou descida.

{
  "TierName": "Ouro",
  "Benefits": [
    "Frete Grátis em todos os pedidos",
    "Acesso antecipado a promoções"
  ],
  "NextTierTargets": [
    "Gastar R$ 5000 nos próximos 6 meses"
  ],
  "Customer": { ... },
  "PointsBalance": { ... }
}

string

required

Nome do novo nível

array

required

Lista de benefícios do nível

array

required

Requisitos para próximo nível (vazio se for o mais alto)

object

required

Objeto Cliente

object

required

Objeto Saldo de Pontos

Documentação atualizada em Dezembro de 2025.

Primeiros Passos

Tópicos

Webhooks - Comunicações

Cupons

Resgate de Recompensas

Ganho de Pontos

Alteração de Pontos

Pontos Disponíveis

Expiração de Pontos

Resgate de Pontos

OTP (Código de Verificação)

Níveis/Tiers

​Cupons

​Resgate de Recompensas

​Ganho de Pontos

​Alteração de Pontos

​Pontos Disponíveis

​Expiração de Pontos

​Resgate de Pontos

​OTP (Código de Verificação)

​Níveis/Tiers

Cupons

Resgate de Recompensas

Ganho de Pontos

Alteração de Pontos

Pontos Disponíveis

Expiração de Pontos

Resgate de Pontos

OTP (Código de Verificação)

Níveis/Tiers