Webhooks - Clientes - BonifiQ Developers

Este documento descreve os payloads de webhook relacionados a clientes.

Eventos de Clientes

Customer_Created

Enviado quando um novo cliente é criado no sistema.

{
  "Customer": {
    "Id": "12345",
    "OriginalId": "cliente_original_123",
    "Email": "cliente@exemplo.com",
    "Name": "João Silva",
    "Phone": "+5511999998888",
    "Document": "12345678900",
    "BirthDate": "1990-05-20",
    "Level": "Ouro",
    "Active": "true"
  },
  "PointsBalance": {
    "PointsBalance": 0,
    "CashbackBalance": 0.00
  }
}

object

required

Objeto com informações do cliente criado. Veja abaixo.

object

required

Objeto Saldo de Pontos

Customer_Updated

Enviado quando um cliente existente é atualizado.

{
  "Customer": {
    "Id": "12345",
    "OriginalId": "cliente_original_123",
    "Email": "cliente@exemplo.com",
    "Name": "João Silva Santos",
    "Phone": "+5511999998888",
    "Document": "12345678900",
    "BirthDate": "1990-05-20",
    "Level": "Platina",
    "Active": "true"
  },
  "PointsBalance": {
    "PointsBalance": 1500,
    "CashbackBalance": 15.00
  }
}

object

required

Objeto com informações atualizadas do cliente. Veja abaixo.

object

required

Objeto Saldo de Pontos

Mudança de nível

O tópico Customer_TierChanged (29) registra a troca efetiva do nível de um cliente. No painel, ele aparece como Cliente: mudança de nível. Use este tópico para acompanhar níveis em sua integração. Ele é independente de Communication_CustomerTierUpgradeNotification e Communication_CustomerTierDowngradeNotification, que continuam seguindo as regras de comunicação.

Quando o evento é gerado

O evento compara o ID do nível anterior com o ID final, incluindo:

atribuição inicial de um nível, inclusive o base;
subida ou descida no recálculo automático;
alterações pelo Admin, API e importações;
retorno ao nível base;
remoção do vínculo com um nível, inclusive por desativação do nível;
alteração do nível do cliente sobrevivente em uma unificação de cadastros.

Uma troca entre níveis diferentes gera evento mesmo que tenham a mesma ordem. Alterações apenas na carência, nos comentários, no nome ou na ordem do mesmo nível não geram evento. Na unificação, a exclusão do cadastro absorvido não gera uma mudança de nível para esse cadastro. As regras de classificação e carência continuam determinando quando o nível pode mudar. A captura do evento não depende de inscrição do cliente em comunicações, de envio de e-mail, de horário de comunicação ou da janela de sete dias de GracePeriodDateUpdate.

Apenas assinaturas ativas com este tópico selecionado no momento da mudança recebem o evento. Ativar a assinatura ou adicionar o tópico não envia uma carga inicial nem recupera mudanças anteriores. Se a assinatura estiver inativa no momento da entrega, a chamada não é realizada.

Exemplo de troca de nível

Exemplo completo com o envelope padrão, em uma mudança de Prata para Ouro:

{
  "Uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "Timestamp": "2026-09-18T14:30:00Z",
  "Topic": 29,
  "TopicName": "Customer_TierChanged",
  "Payload": {
    "Customer": {
      "Id": 12345,
      "PublicId": "9f51e71e-0b71-4d73-9e89-32b0ab74c6dc",
      "OriginalId": "cliente_original_123",
      "Email": "cliente@exemplo.com"
    },
    "PreviousTier": {
      "Id": 2,
      "Name": "Prata",
      "IsBase": false
    },
    "CurrentTier": {
      "Id": 3,
      "Name": "Ouro",
      "IsBase": false
    },
    "OccurredAtUtc": "2026-09-18T14:30:00Z",
    "Sequence": 98765
  }
}

Campos do payload

Os dados representam o momento da captura. Uma renomeação de nível ou outra alteração posterior do cliente não modifica o payload dessa transição nas retentativas.

Campo	Tipo	Descrição
`Customer.Id`	integer	ID interno do cliente na BonifiQ. Neste tópico, é um número.
`Customer.PublicId`	string (UUID)	Identificador público do cliente.
`Customer.OriginalId`	string ou null	Identificador no sistema de origem.
`Customer.Email`	string ou null	E-mail do cliente.
`PreviousTier`	object ou null	Nível anterior; `null` quando o cliente não tinha nível.
`CurrentTier`	object ou null	Nível final; `null` quando o cliente fica sem nível.
`OccurredAtUtc`	string (date-time)	Instante de registro da transição, em UTC. Não é a data de referência usada pelo recálculo.
`Sequence`	integer (int64)	Sequência da transição, compartilhada entre as assinaturas destinatárias da mesma mudança. Pode conter lacunas.

Quando presentes, PreviousTier e CurrentTier têm a mesma estrutura:

Campo	Tipo	Descrição
`Id`	integer	ID interno do nível. Use este campo para identificar a mudança.
`Name`	string	Nome do nível no momento da captura.
`IsBase`	boolean	Indica se é o nível base.

O objeto Customer deste tópico tem apenas os quatro campos descritos acima. O payload não inclui saldo, benefícios, metas ou RFM.

Entrada no base e remoção

Na atribuição inicial do nível base, PreviousTier é null. Exemplo de payload, sem o envelope:

{
  "Customer": {
    "Id": 12345,
    "PublicId": "9f51e71e-0b71-4d73-9e89-32b0ab74c6dc",
    "OriginalId": null,
    "Email": null
  },
  "PreviousTier": null,
  "CurrentTier": {
    "Id": 1,
    "Name": "Bronze",
    "IsBase": true
  },
  "OccurredAtUtc": "2026-09-18T10:00:00Z",
  "Sequence": 98760
}

Na remoção sem atribuição de outro nível, CurrentTier é null. Isso também ocorre quando a desativação de um nível remove o vínculo do cliente. Exemplo de payload, sem o envelope:

{
  "Customer": {
    "Id": 12345,
    "PublicId": "9f51e71e-0b71-4d73-9e89-32b0ab74c6dc",
    "OriginalId": "cliente_original_123",
    "Email": "cliente@exemplo.com"
  },
  "PreviousTier": {
    "Id": 3,
    "Name": "Ouro",
    "IsBase": false
  },
  "CurrentTier": null,
  "OccurredAtUtc": "2026-09-18T16:00:00Z",
  "Sequence": 98780
}

Um retorno ao base tem CurrentTier preenchido com IsBase: true. Se um nível for atribuído após uma remoção, essa atribuição gera outra transição.

Duplicidade e ordem de entrega

As entregas são assíncronas, podem se repetir e podem chegar fora de ordem. Duas mudanças no mesmo dia geram eventos distintos.

Use o Uuid do envelope para deduplicar as tentativas da mesma entrega. Ele permanece igual nas retentativas; assinaturas diferentes têm seus próprios Uuid.
Para manter o estado atual, armazene a maior Sequence processada por empresa e cliente. Uma sequência menor não deve sobrescrever um nível recebido com sequência maior.
Se sua integração mantém histórico, preserve também as transições mais antigas que chegarem depois. As lacunas na sequência não indicam, por si só, eventos perdidos.

Este tópico usa a política de entrega existente, com os headers, método, URL e corpo configurados na assinatura. Não há garantia de entrega exatamente uma vez ou de ordem estrita. Mudanças feitas diretamente por SQL externo não são capturadas.

Prefira o envelope padrão para ter acesso ao Uuid. Um corpo personalizado recebe os campos deste payload, como Customer.Id e Sequence, mas não recebe automaticamente os campos do envelope. Consulte a configuração do corpo personalizado.

Objeto CustomerInfo

Estrutura do objeto Customer nos tópicos Customer_Created e Customer_Updated. Para Customer_TierChanged, use os campos da mudança de nível.

{
  "Id": "12345",
  "OriginalId": "cliente_original_123",
  "Email": "cliente@exemplo.com",
  "Name": "João Silva",
  "Phone": "+5511999998888",
  "Document": "12345678900",
  "BirthDate": "1990-05-20",
  "Level": "Ouro",
  "Active": "true"
}

string

required

ID interno do cliente no sistema BonifiQ

string

required

ID do cliente no sistema de origem (ex: plataforma e-commerce)

string

required

Endereço de e-mail do cliente

string

required

Nome completo do cliente

string

Número de telefone. Pode ser null.

string

Documento de identificação (ex: CPF). Pode ser null.

string

Data de nascimento. Pode ser null.

string

Nome do nível/tier do cliente. Pode ser null.

string

Status de ativo do cliente (“true” ou “false”). Pode ser null.

Tópicos Disponíveis

Tópico	Descrição
`Customer_Created`	Cliente criado
`Customer_Updated`	Cliente atualizado
`Customer_TierChanged`	Mudança efetiva de nível (código `29`)

Documentação atualizada em Setembro de 2026.

​Eventos de Clientes

​Mudança de nível

​Quando o evento é gerado

​Exemplo de troca de nível

​Campos do payload

​Entrada no base e remoção

​Duplicidade e ordem de entrega

​Objeto CustomerInfo

​Tópicos Disponíveis

Eventos de Clientes

Mudança de nível

Quando o evento é gerado

Exemplo de troca de nível

Campos do payload

Entrada no base e remoção

Duplicidade e ordem de entrega

Objeto CustomerInfo

Tópicos Disponíveis