> ## Documentation Index > Fetch the complete documentation index at: https://developers.bonifiq.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks - Comunicações > Payloads de webhook para eventos de comunicação do sistema de Fidelidade 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](./01-introducao#objetos-de-dados-comuns) 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 Enviado quando uma comunicação é disparada referente a cupons disponíveis para o cliente usar. ```json theme={null} { "CouponType": 1, "ValidDateEnd": "2025-12-31T23:59:59Z", "CouponValue": 10.00, "CouponCode": "BEMVINDO10", "Customer": { ... }, "PointsBalance": { ... } } ``` Tipo do cupom. Veja [CouponType](./01-introducao#definições-de-enum) Data de expiração (ISO 8601), se houver. Pode ser `null`. Valor do cupom (ex: `10.0` para 10% ou R\$10,00) Código para resgate [Objeto Cliente](./01-introducao#objetos-de-dados-comuns) [Objeto Saldo de Pontos](./01-introducao#objetos-de-dados-comuns) *** ## Resgate de Recompensas Enviado após um cliente resgatar pontos por uma recompensa personalizada. ```json theme={null} { "Points": 500, "RewardDescription": "Caneca Grátis com Logo", "Coupon": "RESGATECAN123", "Customer": { ... }, "PointsBalance": { ... } } ``` Pontos gastos no resgate Descrição da recompensa Código de cupom gerado, se aplicável. Pode ser `null`. [Objeto Cliente](./01-introducao#objetos-de-dados-comuns) [Objeto Saldo de Pontos](./01-introducao#objetos-de-dados-comuns) *** ## 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:** Pontos ganhos neste evento Tipo de objetivo. Veja [ObjectiveType](./01-introducao#definições-de-enum) [Objeto Cliente](./01-introducao#objetos-de-dados-comuns) [Objeto Saldo de Pontos](./01-introducao#objetos-de-dados-comuns) Ganho de pontos por uma compra. ```json theme={null} { "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:** Cashback ganho Cashback ganho formatado em moeda (pt-BR) Expiração dos pontos/cashback Data de expiração formatada (dd/MM/yyyy) Data do pedido Data do pedido formatada (dd/MM/yyyy) Valor total do pedido Valor total do pedido formatado em moeda (pt-BR) Taxa de cashback (ex: `0.01` = 1%) Taxa de cashback formatada em percentual (pt-BR) Data do registro do evento ID do pedido no sistema de origem ID interno do registro de ponto Ganho de pontos como bônus de aniversário. ```json theme={null} { "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:** Pontos do aniversário Descrição do bônus Tipo do cupom concedido Código do cupom URL para resgate Ganho de pontos por cadastro. Usa apenas os campos base comuns. Ganho de pontos por review. Usa apenas os campos base comuns. Ganho de pontos por indicação. ```json theme={null} { "EarnedPoints": 200, "ObjectiveType": 4, "Customer": { ... }, "PointsBalance": { ... }, "FriendName": "Maria Souza" } ``` **Campo Adicional:** Nome do amigo indicado Ganho de pontos por quiz. Usa apenas os campos base comuns. Ganho de pontos por objetivo personalizado. Usa apenas os campos base comuns. 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 Enviado quando há alteração manual ou diversa no saldo de pontos. ```json theme={null} { "Points": -50, "PointsValidDate": "01/08/2025", "Customer": { ... }, "PointsBalance": { ... } } ``` Pontos da alteração (positivo = adição, negativo = subtração) Data de expiração formatada [Objeto Cliente](./01-introducao#objetos-de-dados-comuns) [Objeto Saldo de Pontos](./01-introducao#objetos-de-dados-comuns) *** ## Pontos Disponíveis Enviado para informar o cliente sobre seu potencial de resgate. ```json theme={null} { "PointsToUse": 1500, "maxValueDiscount": "R$ 15,00", "maxPercentDiscount": "10%", "CashbackToUse": 15.00, "CashbackToUseFormatted": "R$ 15,00", "Customer": { ... }, "PointsBalance": { ... } } ``` Total de pontos disponíveis Desconto monetário máximo formatado Desconto percentual máximo formatado Cashback disponível para uso. Pode ser `null`. Cashback disponível formatado em moeda (pt-BR) [Objeto Cliente](./01-introducao#objetos-de-dados-comuns) [Objeto Saldo de Pontos](./01-introducao#objetos-de-dados-comuns) *** ## Expiração de Pontos Enviado para notificar sobre pontos próximos da expiração. ```json theme={null} { "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": { ... } } ``` Quantidade de pontos que expirarão Data/hora de expiração (ISO 8601) Data formatada para exibição ID interno do registro de ponto Data de validade dos pontos (ISO 8601). Pode ser `null`. Data de validade formatada (dd/MM/yyyy) Valor de cashback que expirará. Pode ser `null`. Valor de cashback formatado em moeda (pt-BR) [Objeto Cliente](./01-introducao#objetos-de-dados-comuns) [Objeto Saldo de Pontos](./01-introducao#objetos-de-dados-comuns) *** ## Resgate de Pontos Enviado após resgate de pontos por recompensa padrão. ```json theme={null} { "CouponCode": "RESGATE5OFF", "CouponDescription": "Cupom de Desconto R$ 5,00", "Points": 500, "Customer": { ... }, "PointsBalance": { ... } } ``` Código do cupom gerado Descrição da recompensa Pontos gastos [Objeto Cliente](./01-introducao#objetos-de-dados-comuns) [Objeto Saldo de Pontos](./01-introducao#objetos-de-dados-comuns) *** ## OTP (Código de Verificação) 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. ```json theme={null} { "OTP": "123456", "Customer": { ... } } ``` Senha de uso único enviada [Objeto Cliente](./01-introducao#objetos-de-dados-comuns) *** ## Níveis/Tiers Enviado quando o nível de fidelidade do cliente muda. ```json theme={null} { "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": { ... } } ``` Nome do novo nível Lista de benefícios do nível Requisitos para próximo nível (vazio se for o mais alto) [Objeto Cliente](./01-introducao#objetos-de-dados-comuns) [Objeto Saldo de Pontos](./01-introducao#objetos-de-dados-comuns) *** Documentação atualizada em Dezembro de 2025.