Webhook - Adicionar Pontos

Criada por Lucas Almeida Portilho Barcelos, Modificado em Seg, 9 Fev na (o) 4:39 PM por Isabelly Souza

Documentação do Payload de Webhook de Fidelidade (Focado no Cliente)

Este documento descreve a estrutura JSON dos payloads de webhook enviados pelo sistema de Fidelidade para o seu endpoint registrado quando eventos específicos ocorrem.

Estrutura Base do Webhook

Todas as notificações de webhook entregues ao seu endpoint seguirão este formato JSON básico:

{
  "Uuid": "a_unique_identifier_string",
  "Timestamp": "2025-04-15T14:30:00Z",
  "Topic": "Actual_Topic_Name",
  "Payload": { ... }
}

Uuid (string): Um identificador único (UUID) para esta tentativa específica de entrega de webhook. Use isso para logs ou para garantir que você não processe a mesma entrega várias vezes (idempotência).

Exemplo: "f47ac10b-58cc-4372-a567-0e02b2c3d479"

Timestamp (string): A data e hora (no formato ISO 8601, UTC) em que o evento ocorreu originalmente no sistema de Fidelidade.

Exemplo: "2025-04-15T14:30:00.123Z"

Topic (string): Uma string que identifica o tipo de evento ocorrido. Isso determina a estrutura e o conteúdo do objeto Payload. Veja as seções abaixo para detalhes sobre os payloads associados a cada tópico específico.

Exemplo: "Communication_EarnPurchasePoints"

Payload (object): Um objeto JSON contendo os detalhes específicos relevantes ao Topic do evento. A estrutura deste objeto varia dependendo do tópico e da sua configuração de assinatura (veja a seção de Payloads Customizados).

Objetos de Dados Comuns

Estes objetos JSON aparecem frequentemente em diferentes estruturas de payload:

Objeto Customer (Cliente)

Contém informações sobre o cliente relacionado ao evento.

{
  "Email": "customer@example.com",
  "Id": "original_customer_id_123",
  "Name": "John Doe",
  "Phone": "+15551234567",
  "Document": "12345678900 | null",
  "BirthdayDate": "1990-05-20T00:00:00Z | null",
  "PointsBalance": 1500
}

Email (string): Endereço de e-mail principal do cliente.
Id (string): Identificador único do cliente, geralmente o ID do sistema de origem (ex: sua plataforma de e-commerce).
Name (string): Nome completo do cliente.
Phone (string): Número de telefone do cliente, normalmente incluindo o código do país.
Document (string | null): Número de identificação nacional (ex: CPF no Brasil), se fornecido. Caso contrário, null.
BirthdayDate (string | null): Data de nascimento do cliente (formato ISO 8601), se fornecida. Caso contrário, null.
PointsBalance (number - inteiro): O saldo total de pontos do cliente no momento em que o evento ocorreu. Isso pode não refletir o saldo após o evento, caso o próprio evento tenha modificado o saldo (veja o Objeto Points Balance para isso).

Objeto Points Balance (Saldo de Pontos)

Contém detalhes sobre o saldo de pontos e cashback do cliente após o processamento do evento.

{
  "PointsBalance": 1650,
  "CashbackBalance": 16.50
}

PointsBalance (number - inteiro): O saldo total de pontos disponível do cliente após a aplicação dos efeitos do evento.
CashbackBalance (number): O saldo total de cashback disponível (como valor decimal) após a aplicação dos efeitos do evento.

Definições de Enum

Vários campos de payload representam tipos enumerados. Estes são enviados como inteiros no payload JSON. Aqui estão os mapeamentos para os enums comuns:

`CouponType (Inteiro)`

Indica o tipo de um cupom.

0: FixedValue ("Valor fixo" - Desconto em valor fixo)
1: Percent ("Valor percentual" - Desconto percentual)
2: FreeShipping ("Frete grátis")
3: DiscountShipping ("Desconto em frete")
4: Others ("Outros" - Outros tipos, frequentemente pré-gerados)

`ObjectiveType (Inteiro)`

Indica a razão ou atividade que disparou um evento, geralmente relacionado ao acúmulo de pontos.

0: Purchase ("Fazer compras")
1: Signup (Cadastro)
2: Birthday ("Fazer aniversário")
3: Review ("Fazer um review")
4: Referral ("Indique um Amigo")
5: SocialMediaFollowInstagram ("Siga no Instagram")
6: SocialMediaFollowFacebook ("Siga no Facebook")
7: Quiz ("Responda um Quiz")
8: Custom ("Objetivo Customizado")

`PointType (Inteiro)`

Especifica o motivo detalhado de uma transação de pontos.

0: Purchase ("Fez uma compra")
1: Signup ("Criou conta")
2: Birthday ("Fez aniversário")
3: Ordinary ("Concedido por administrador")
4: Reward ("Trocou por recompensa")
5: Review ("Fez um review")
6: Refund ("Reembolso de pontos")
7: Expire ("Pontos expirados")
8: Referral ("Indicou um amigo")
9: SocialMediaFollowFacebook ("Seguiu nas redes sociais Facebook")
10: SocialMediaFollowInstagram ("Seguiu nas redes sociais Instagram")
11: PartialOrderRefund ("Reembolso parcial de pedido")
12: Quiz ("Respondeu um quiz")
13: CustomObjective ("Pontos de objetivo personalizado")
14: ReferralAffiliate ("Indicação de afiliado")

`PointAction (Inteiro)`

Indica se os pontos foram adicionados ou removidos em uma transação.

0: Take (Pontos foram removidos ou gastos)
1: Grant (Pontos foram adicionados ou concedidos)

Garantias de Entrega e Retentativas de Webhook

Idempotência: Cada entrega de webhook inclui um Uuid único. Você deve armazenar e verificar este Uuid do seu lado para evitar o processamento do mesmo evento múltiplas vezes. Embora o sistema de Fidelidade tente evitar o envio de eventos duplicados, confiar no Uuid no recebimento é a melhor prática.
Retentativas: Se o sistema falhar ao entregar um webhook (ex: erro de rede, resposta 5xx do seu servidor ou timeout), ele tentará reenviar automaticamente com um período de intervalo crescente (backoff).
Timeout: O sistema aguarda até 30 segundos por uma resposta de sucesso (HTTP 2xx) do seu endpoint antes de considerar a tentativa de entrega como falha.
Falhas e Desativação: Se as tentativas de entrega falharem consistentemente (atualmente após mais de 5 tentativas sem sucesso para um único evento), o sistema pode desativar automaticamente a assinatura. Você precisará investigar as falhas e reativar a assinatura na interface do sistema de Fidelidade. Certifique-se de que seu endpoint responda prontamente com um status HTTP 2xx. Processe o payload de forma assíncrona, se necessário.

Customização

Ao configurar sua assinatura de webhook, você tem opções para customizar a entrega:

Corpo do Payload Customizado: Você pode definir uma estrutura JSON personalizada usando uma linguagem de template. Se configurado, o campo Payload conterá o seu JSON renderizado em vez dos objetos padrão.
Variáveis na URL do Endpoint: Sua URL de endpoint pode incluir variáveis derivadas dos dados do evento (ex: https://seu-endpoint.com/webhook/{{Customer.Id}}).
Método HTTP Customizado: Você pode especificar o método HTTP (ex: PUT, POST).
Headers Customizados: Você pode configurar cabeçalhos HTTP estáticos (pares chave-valor) para autenticação ou roteamento.

Consulte a interface de configuração de webhook do sistema de fidelidade para obter detalhes sobre o idioma do modelo e as variáveis disponíveis.

Considerações de Segurança

HTTPS: Sempre use uma URL https:// para garantir que os dados sejam criptografados em trânsito.
Sigilo do Endpoint: Mantenha a URL do seu endpoint difícil de adivinhar.
Segredo Compartilhado (via Headers Customizados): Como o sistema não implementa assinatura de payload (HMAC) no momento, você pode configurar um cabeçalho customizado (ex: X-Loyalty-Secret) com um valor secreto. Seu endpoint deve verificar a presença e a correção deste cabeçalho.

Payloads de Eventos por Tópico

Tópico: Communication_CouponsToUse

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

Estrutura do Payload:

{
  "CouponType": 1, // Integer, see Enum Definitions
  "ValidDateEnd": "2025-12-31T23:59:59Z | null",
  "CouponValue": 10.00, // e.g., 10.00 for 10% or R$10.00
  "CouponCode": "WELCOME10",
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

CouponType (number - inteiro): Indica o tipo do cupom. Veja as Definições de Enum CouponType.
ValidDateEnd (string | null): A data e hora de expiração do cupom (formato ISO 8601), se houver. Caso contrário, null.
CouponValue (number): O valor associado ao cupom (ex: 10.0 para um desconto de 10%, ou 25.50 para um desconto fixo de R$ 25,50). A interpretação depende do CouponType.
CouponCode (string): O código real que o cliente precisa inserir para resgatar o cupom.
Customer (object): Detalhes do cliente ao qual esta comunicação se refere. Veja o Objeto Customer.

Tópico: Communication_RewardCustomRedeemNotification

Enviado quando um cliente resgata pontos por uma recompensa personalizada.

Estrutura do Payload:

{
  "Points": 500,
  "RewardDescription": "Free Mug with Logo",
  "Coupon": "MUGREDEEM123 | null",
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

Points (number - inteiro): O número de pontos que o cliente gastou para resgatar esta recompensa.
RewardDescription (string): Uma descrição da recompensa personalizada específica que foi resgatada.
Coupon (string | null): Se o resgate da recompensa personalizada gerou um código de cupom, ele será incluído aqui. Caso contrário, null.
Customer (object): Detalhes do cliente que resgatou a recompensa. Veja o Objeto Customer.

Tópicos para Comunicações de Ganho de Pontos

Estes tópicos são enviados quando o cliente ganha pontos por diversos motivos.

Campos Base Comuns:

{
  "EarnedPoints": 100,
  "ObjectiveType": 2,
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  },
  "BirthdayPoints": 100,
  "BirthdayBonification": "Happy Birthday Bonus!",
  "CouponType": 1,
  "CouponCode": "BDAYGIFT | null",
  "RedeemUrl": "https://example.com/redeem-bday | null"
}

EarnedPoints: Pontos ganhos neste evento específico.
ObjectiveType: Veja Definições de Enum.
Customer: Detalhes do cliente.

Tópicos Específicos e Campos Adicionais:

Communication_EarnPurchasePoints: Ganho de pontos por compra.

{
  "EarnedPoints": 150,
  "ObjectiveType": 0, // 0 = Purchase
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  },
  "CashbackEarned": 1.50,
  "ValidDate": "2026-04-15T00:00:00Z", 
  "OrderDate": "2025-04-15T10:05:00Z",
  "OrderValue": 150.00,
  "PercentCashbackEarned": 0.01, // 1%
  "Date": "2025-04-15T10:05:10Z" 
}

CashbackEarned (number | null): Valor monetário de cashback acumulado nesta compra.
ValidDate (string | null): Data/hora de expiração para estes pontos/cashback, se aplicável.
OrderDate (string): Data/hora em que o pedido associado foi realizado.
OrderValue (number): Valor monetário total do pedido associado.
PercentCashbackEarned (number | null): Taxa percentual em que o cashback foi acumulado (ex: 0.01 para 1%).
Date (string): Data/hora em que o evento de acúmulo de pontos foi registrado.

Communication_EarnBirthdayPoints: Bônus de aniversário.

{
  "EarnedPoints": 100,
  "ObjectiveType": 2,
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  },
  "BirthdayPoints": 100,
  "BirthdayBonification": "Happy Birthday Bonus!",
  "CouponType": 1,
  "CouponCode": "BDAYGIFT | null",
  "RedeemUrl": "https://example.com/redeem-bday | null"
}

BirthdayPoints (number - inteiro): Pontos concedidos especificamente pelo aniversário.
BirthdayBonification (string | null): Descrição do bônus de aniversário.
CouponType (number - inteiro | null): Tipo de cupom também concedido, se houver. Veja as Definições de Enum CouponType.
CouponCode (string | null): Código do cupom concedido, se houver.
RedeemUrl (string | null): URL para resgatar o benefício/cupom, se aplicável.

Communication_EarnSignupPoints: Ganho de pontos por cadastro.

{
  "EarnedPoints": 50,
  "ObjectiveType": 1,
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

(Nenhum campo adicional específico para inscrição é exibido no editor)

Communication_EarnReviewPoints: Ganho de pontos por avaliação.

{
  "EarnedPoints": 25,
  "ObjectiveType": 3,
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

(Nenhum campo adicional específico para inscrição é exibido no editor)

Communication_ReferralCommunicationPoints: Ganho de pontos por indicação.

{
  "EarnedPoints": 200,
  "ObjectiveType": 4,
  "Customer": {
    "Email": "referrer@example.com",
    "Id": "original_referrer_id_456",
    "Name": "Referrer Name",
    "Phone": "+15559876543",
    "Document": "09876543211",
    "BirthdayDate": "1985-11-10T00:00:00Z",
    "PointsBalance": 2500
  },
  "FriendName": "Jane Smith"
}

FriendName: Nome do amigo indicado.

Communication_EarnQuizPoints: Ganho por responder quiz.

{
  "EarnedPoints": 30,
  "ObjectiveType": 7,
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

(Nenhum campo adicional específico para inscrição é exibido no editor)

Communication_EarnCustomObjectivePoints: Ganho por objetivo customizado.

{
  "EarnedPoints": 75,
  "ObjectiveType": 8,
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

(Nenhum campo adicional específico para inscrição é exibido no editor)

Tópico: Communication_CustomerPointChangeNotification

Enviado em caso de alteração manual ou diversa no saldo de pontos.

Estrutura do Payload:

{
  "Points": -50,
  "PointsValidDate": "2025-08-01",
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

Points (number - inteiro): O número de pontos envolvidos na alteração (positivo para adição, negativo para subtração).
PointsValidDate (string): Uma string formatada representando a data de expiração relacionada a esta alteração de pontos, se aplicável (ex: "dd/MM/yyyy" ou "yyyy-MM-dd").
Customer (object): Detalhes do cliente cujo saldo foi alterado. Veja o Objeto Customer.

Tópico: Communication_PointsToUse

Informa o cliente sobre seu potencial de resgate.

Estrutura do Payload:

{
  "PointsToUse": 1500,
  "MaxValueDiscount": "R$ 15,00",
  "MaxPercentDiscount": "10%",
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

PointsToUse (number - inteiro): O total de pontos que o cliente tem disponível atualmente para resgate.
MaxValueDiscount (string): Uma string formatada representando o desconto monetário máximo que o cliente pode alcançar com seus pontos atuais (ex: "R$ 15,00").
MaxPercentDiscount (string): Uma string formatada representando o desconto percentual máximo que o cliente pode alcançar (ex: "10%").
Customer (object): Detalhes do cliente. Veja o Objeto Customer.

Tópico: Communication_NotifyExpirablePoints

Notifica sobre pontos próximos da expiração.

Estrutura do Payload:

{
  "PointsToExpire": 250,
  "ExpirationAt": "2025-07-31T23:59:59Z",
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  },
  "ExpirationDate": "31/07/2025"
}

PointsToExpire (number - inteiro): O número de pontos que estão programados para expirar em breve.
ExpirationAt (string): A data e hora exata (formato ISO 8601) em que estes pontos irão expirar.
Customer (object): Detalhes do cliente cujos pontos estão expirando. Veja o Objeto Customer.
ExpirationDate (string): Uma string formatada representando a data de expiração (ex: "dd/MM/yyyy").

Tópico: Communication_RedeemPoints

Enviado após resgate de uma recompensa padrão (ex: cupom de desconto).

Estrutura do Payload:

{
  "CouponCode": "REDEEM5OFF",
  "CouponDescription": "R$ 5,00 Discount Coupon",
  "Points": 500,
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

CouponCode (string): O código de cupom gerado ou utilizado para este resgate.
CouponDescription (string): Uma descrição da recompensa obtida através do resgate.
Points (number - inteiro): O número de pontos que o cliente gastou.
Customer (object): Detalhes do cliente que resgatou os pontos. Veja o Objeto Customer.

Tópico: Communication_SentOTPToCustomer

Enviado quando uma comunicação (provavelmente SMS ou e-mail) contendo uma senha de uso único (OTP) é disparada. Nota de Segurança: Tenha cautela ao processar OTPs recebidas via webhooks; certifique-se de que seu endpoint e sua lógica de tratamento sejam seguros.

Estrutura do Payload:

{
  "Otp": "123456",
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

Otp (string): A senha de uso único (One-Time Password) que foi enviada ao cliente.
Customer (object): Detalhes do cliente para quem o OTP foi enviado. Veja o Objeto Customer.

Tópicos: Communication_CustomerTierUpgradeNotification / Downgrade

Enviado quando uma comunicação é disparada porque o nível (tier) de fidelidade de um cliente mudou (seja por upgrade ou downgrade).

Estrutura do Payload:

{
  "TierName": "Gold",
  "Benefits": [
    "Free Shipping on all orders",
    "Early access to sales",
    "Dedicated support line"
  ],
  "NextTierTargets": [
    "Spend R$ 5000 in the next 6 months",
    "Maintain Gold status for 1 year"
  ],
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  }
}

TierName (string): O nome do nível (tier) em que o cliente acaba de entrar.
Benefits (array de string): Uma lista de descrições em texto dos benefícios associados a este novo nível.
NextTierTargets (array de string): Uma lista de descrições em texto detalhando o que o cliente precisa fazer para alcançar o próximo nível (se aplicável; pode estar vazio em casos de downgrade ou se o cliente já estiver no nível mais alto).
Customer (object): Detalhes do cliente cujo nível foi atualizado. Veja o Objeto Customer.

Tópicos para Transações Diretas de Pontos

Estes tópicos referem-se ao registro direto ou à modificação de pontos no sistema, frequentemente disparando também eventos de comunicação relacionados.

Point_Add, Point_Update, Point_Removed: Alterações gerais de registro de pontos.

Estrutura do Payload:

{
  "Points": 150,
  "PointType": 0,
  "PointAction": 1,
  "Customer": {
    "Email": "customer@example.com",
    "Id": "original_customer_id_123",
    "Name": "John Doe",
    "Phone": "+15551234567",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-20T00:00:00Z",
    "PointsBalance": 1500
  },
  "PointsBalance": {
    "PointsBalance": 1650,
    "CashbackBalance": 16.50
  },
  "PointId": 98765
}

Points (number - inteiro): O número de pontos envolvidos neste registro de transação específico.
PointType (number - inteiro): A categoria ou motivo da transação de pontos. Veja as Definições de Enum PointType.
PointAction (number - inteiro): A ação específica realizada neste registro. Veja as Definições de Enum PointAction.
Customer (object): Detalhes do cliente envolvido. Veja o Objeto Customer.
PointsBalance (object): O saldo de pontos e cashback do cliente após esta transação. Veja o Objeto Points Balance.
PointId (number - inteiro): O identificador interno único para este registro de transação de pontos específico dentro do sistema de Fidelidade.

EarnPointsReferralAffilidate: Um afiliado ganha pontos/cashback a partir da ação de um cliente indicado.

Estrutura do Payload:

{
  "Points": 250,
  "CashbackReceived": 2.50,
  "OrderPlacementDate": "2025-04-14T16:20:00Z",
  "Customer": {
    "Email": "affiliate@example.com",
    "Id": "original_affiliate_id_789",
    "Name": "Affiliate Name",
    "Phone": "+15551112233",
    "Document": "11223344556",
    "BirthdayDate": "1988-03-15T00:00:00Z",
    "PointsBalance": 5000
  },
  "PointsBalance": {
    "PointsBalance": 5250,
    "CashbackBalance": 52.50
  }
}

Points (number - inteiro): Pontos acumulados pelo afiliado. CashbackReceived (number): Valor de cashback acumulado pelo afiliado.
OrderPlacementDate (string): Data e hora (formato ISO 8601) em que o cliente indicado realizou o pedido qualificado que gerou esta recompensa.
Customer (object): Detalhes do cliente afiliado que acumulou a recompensa. Veja o Objeto Customer .
PointsBalance (object): O saldo de pontos e cashback do afiliado após este evento. Veja o Objeto Points Balance .