Skip to main content

​
Introdução

A integração com PDV permite que sistemas de ponto de venda utilizem os recursos de fidelidade da BonifiQ diretamente no fluxo de compra do consumidor utilizando nossas APIs. Esta documentação cobre todos os endpoints e fluxos necessários para uma integração completa.
Disponibilizamos um projeto de referência no GitHub com um PDV mockado que implementa todos os fluxos descritos nesta documentação. Use-o como guia durante sua implantação.
Base URL da API: https://api.bonifiq.com.br/v1/pvt/POSConsulte também a documentação interativa Swagger

​
Autenticação

Saiba mais como utilizar a autenticação (Basic Authentication) com a BonifiQ acessando esse link

​
Fluxo de Resgate de Recompensas

​
Visão Geral

O diagrama abaixo ilustra o fluxo completo de resgate de uma recompensa no PDV: O fluxo pode ser dividido em três etapas principais:

1. Consulta de Recompensas

Consulta das recompensas disponíveis para o cliente

2. Validação (Opcional)

Verificação de identidade via código PIN

3. Resgate e Conclusão

Resgate da recompensa e aplicação do desconto

​
Consulta de Recompensas

Na BonifiQ é possível que sejam configuradas uma ou mais recompensas. As recompensas podem ser aplicadas aos pedidos, oferecendo um desconto na compra do cliente. Alguns exemplos: “desconto de 10% por 1000 pontos”, “desconto de R$ 10 por 100 pontos”, “cashback de R$ 10,00”, etc Para realizar essa consulta, pode-se chamar o endpoint POS/rewards/available. No corpo da chamada, deve-se informar o identificador do usuário (geralmente o CPF ou CNPJ). Esse endpoint retorna uma lista de Recompensas disponíveis para este consumidor. As recompensas podem ser de 2 tipos:
  • Desconto fixo (ex: R$ 10,00) ou Desconto percentual (ex: 10%)
  • Cashback (que também pode ser um desconto)
No caso em que exista mais de uma recompensa possível o PDV deverá exibir uma lista de recompensas ao vendedor, que escolhe apenas uma delas: somente uma recompensa é permitida por compra. Caso a recompensa escolhida seja Cashback deverá ser possível ao vendedor informar o valor que deseja ser aplicado. Por ex: o cliente possui R$ 20,00 de Cashback, mas deseja utilizar apenas R$10,00 nesta compra. Outro campo importante a se notar é o “Requirements”, ele elenca as regras que serão aplicadas para que seja possível utilizar a recompensa. Por exemplo: A recompensa é R$ 20,00 de Cashback, mas somente poderá ser utiliza em compras acima de R$ 100,00. Nesse caso, ao tentar utilizar uma recompensa que não atende às regras, a BonifiQ retorna um erro.

​
Mockups de Exemplo

Os mockups abaixo ilustram um fluxo comum de consulta de recompensas:
  • O primeiro passo é a consulta das recompensas. É feita chamada para o endpoint, informando o documento do consumidor (apenas números) e o valor atual do pedido.
  • A primeira possibilidade de retorno é uma lista de recompensas disponíveis de Desconto. A imagem detalha quais campos do retorno são utilizados na exibição de cada elemento. Esse cenário não contempla uso de Cashback. É importante notar que a última recompensa está inativa (CanUse=false) pois o consumidor não possui pontos suficientes. Ao clicar em Escolher o fluxo pode continuar.
  • A segunda possibilidade de retorno é o Cashback. É importante notar que é possível que sejam retornados Cashback e Descontos ao mesmo tempo. Ao clicar em Escolher, deve-se exibir o seletor de valor (vide abaixo).
  • Quando se deseja utilizar Cashback é possível que seja utilizado apenas parte do mesmo. No exemplo acima podemos observar: a) O valor total de cashback que o cliente tem é R$100,00 b) O máximo de cashback que ele pode utilizar na compra atual é R$10,00 (devido à regra descrita em Requirements) c) O cliente pode escolher qualquer valor entre R$1,00 e R$10,00 Ao clicar em Confirmar o fluxo pode continuar normalmente.
  • Por fim, a terceira possibilidade desse fluxo é de que não há recompensas disponíveis para utilização.

​
API: Consultar Recompensas Disponíveis

​
/rewards/available
Retorna a lista de recompensas disponíveis para um cliente específico.
Este endpoint retorna todas as recompensas configuradas, mesmo aquelas que o cliente não pode usar no momento (por falta de pontos, por exemplo). Isso permite exibir ao cliente quais recompensas ele poderá obter no futuro.
​
CustomerId
string
required
Identificador do cliente. Pode ser e-mail ou documento (CPF/CNPJ). Importante: Se for documento, utilize apenas números.
​
PurchaseValue
decimal
required
Valor atual do pedido. Não deve incluir descontos, cupons ou outras promoções.
​
DiscountValue
decimal
Valor de desconto já aplicado no pedido (que não seja da BonifiQ). A BonifiQ usa esta informação para retornar apenas recompensas que podem ser acumuladas com outros descontos. Se não houver desconto, envie null ou 0.
{
  "CustomerId": "12345678900",
  "PurchaseValue": 150.00,
  "DiscountValue": null
}
Campos de Resposta Importantes
​
HasRewards
boolean
Se false, não há recompensas disponíveis. O fluxo de recompensas deve ser ignorado.
​
ShouldValidateCustomer
boolean
Se true, o fluxo deve seguir para a validação do cliente (envio de código PIN). Se false, a validação pode ser pulada.
​
AvailablePoints
integer
Quantidade de pontos que o cliente possui atualmente.
​
CashbackEnabled
boolean
Se true, existe uma recompensa de Cashback configurada.
​
AvailableCashback
decimal
Valor total de cashback que o cliente possui.
​
MaxCashbackForCurrentPurchase
decimal
Valor máximo de cashback que pode ser utilizado na compra atual, considerando as regras configuradas.
Campos de Cada Recompensa
​
Rewards[].Id
integer
ID único da recompensa. Usado posteriormente no resgate.
​
Rewards[].Title
string
Título amigável da recompensa para exibição ao usuário. Exemplos: “R$50,00 de desconto”, “10% de desconto”, “Usar Cashback”
​
Rewards[].RewardType
enum
Tipo da recompensa:
  • 0 - Desconto Percentual (ex: 15% off)
  • 1 - Desconto em Valor (ex: R$10,00)
  • 3 - Cashback (ex: R$10,00 em compras acima de R$30,00)
  • 4 - Recompensa Customizada (ex: Brinde)
​
Rewards[].Value
decimal
Valor da recompensa:
  • Desconto Percentual: Valor do percentual (ex: 10.00 para 10%)
  • Desconto em Valor: Valor em reais (ex: 10.00 para R$10,00)
  • Cashback: Valor de cada ponto em reais
​
Rewards[].CanUse
boolean
Se true, o cliente pode usar esta recompensa. Se false, exiba a recompensa como desabilitada para que o cliente saiba o que pode conquistar no futuro.
​
Rewards[].Points
integer
Quantidade de pontos necessários para resgatar esta recompensa.
​
Rewards[].Requirements
string
Texto amigável descrevendo os requisitos para usar a recompensa. Exemplo: “Válido para compras acima de R$50,00”
​
Rewards[].IsCashback
boolean
Se true, esta é uma recompensa de cashback e o cliente pode escolher o valor a utilizar.
​
Rewards[].MaxCashbackForCurrentPurchase
decimal
Para cashback, o valor máximo que pode ser usado nesta compra específica.
​
Rewards[].RewardCanBeCumulative
boolean
Se true, a recompensa pode ser usada junto com outros descontos. Se false, a recompensa só pode ser usada se não houver outros descontos no pedido.

​
Validação do Cliente (Opcional)

Essa é uma etapa de segurança, que visa reduzir chances de mal-uso dos benefícios. Sua aplicação é opcional e configurável dentro da BonifiQ.
Para determinar se o PDV deve executar este fluxo, verifique o campo ShouldValidateCustomer retornado pela chamada /POS/rewards/available:
  • Se true: o fluxo de validação deve acontecer.
  • Se false: o fluxo de validação não deve acontecer (deve ser pulado) e o PDV deve ir direto para a etapa de resgate da recompensa.
Quando a validação for necessária, após a escolha da recompensa, o PDV deverá chamar o endpoint POS/customers//challenge. O nesse caso é o CPF ou CNPJ do consumidor. O endpoint também pode receber um número de telefone, para o caso de ainda não existir um número cadastrado. A BonifiQ, então, irá enviar um código PIN ao consumidor. Ele deverá informar esse código ao vendedor, que por fim, informa ao PDV. O PDV, então, informa esse código ao endpoint POS/customers//challengevalidate. Se houver uma resposta positiva, o PDV libera para que a compra seja concluída.
1

Enviar Challenge

Chame o endpoint de challenge para enviar o código PIN ao cliente.
2

Cliente Recebe o Código

O cliente recebe o código PIN pelo canal configurado.
3

Validar Código

O cliente informa o código ao vendedor, que valida através da API.

​
API: Enviar Challenge

​
/customers/{id}/challenge
Envia um código PIN de validação para o cliente.
Path Parameters
​
id
string
required
Identificador do cliente (CPF/CNPJ apenas números, ou e-mail).
​
TransactionId
string
ID único para identificar esta transação. Pode ser qualquer string vinculada à compra atual. Se não houver um ID disponível, use o timestamp atual.
​
Phone
string
Telefone do cliente. Use este campo se o cliente ainda não tiver telefone cadastrado na BonifiQ.
​
Email
string
E-mail do cliente. Use este campo se o cliente ainda não tiver e-mail cadastrado na BonifiQ.
{
  "TransactionId": "PDV-001-2024-01-15-10:30",
  "Phone": "11999998888",
  "Email": null
}
Campos de Resposta
​
Success
boolean
Se true, o challenge foi enviado com sucesso.
​
SentBySMS
boolean
Se true, o código foi enviado por SMS.
​
SentByEmail
boolean
Se true, o código foi enviado por e-mail.
​
ShouldInformPhone
boolean
Se true e Success=false, é necessário informar o telefone do cliente em uma nova requisição.
​
ShouldInformEmail
boolean
Se true e Success=false, é necessário informar o e-mail do cliente em uma nova requisição.
​
FriendlyErrorMessage
string
Mensagem de erro amigável para exibição ao usuário.

​
API: Validar Challenge

​
/customers/{id}/challengevalidate
Valida o código PIN informado pelo cliente.
Path Parameters
​
id
string
required
Identificador do cliente (mesmo usado no challenge).
​
TransactionId
string
Mesmo ID usado na chamada de challenge.
​
Code
string
required
Código PIN informado pelo cliente.
{
  "TransactionId": "PDV-001-2024-01-15-10:30",
  "Code": "123456"
}
Se success=false, o fluxo não deve continuar. O vendedor pode solicitar um novo código ou cancelar a operação.

​
Resgate da Recompensa

Agora, ao finalizar a compra, o PDV chama o endpoint de resgate de recompensa confirmando o resgate. Deve-se utilizar o endpoint POS/rewards//redeem. Com a resposta positiva da API, o PDV deve então aplicar o respectivo desconto no pedido.

​
API: Resgatar Recompensa

​
/rewards/{id}/redeem
Realiza o resgate de uma recompensa para o cliente.
Importante: Diferente de outros endpoints da BonifiQ, este endpoint NÃO gera um cupom automaticamente. O PDV é responsável por aplicar o desconto diretamente no pedido.
Path Parameters
​
id
integer
required
ID da recompensa a ser resgatada (obtido no endpoint /rewards/available).
​
CustomerId
string
required
Identificador do cliente (CPF/CNPJ ou e-mail).
​
Value
decimal
Obrigatório apenas para Cashback. Valor de cashback que o cliente deseja utilizar. Deve estar entre R$1,00 e o maxCashbackForCurrentPurchase.
​
Points
integer
Alternativa ao Value para Cashback. Quantidade de pontos a utilizar. Use Value ou Points, não ambos.
​
OriginalKey
string
required
Chave única para garantir idempotência. Mesmo que a requisição seja feita mais de uma vez, o resgate acontecerá apenas uma vez.Sugestão de formato: {rewardId}-{customerId}-{orderId}-{value}Exemplo: 3-12345678900-PDV001-15.00
​
Branch
object
Informações da filial/loja onde a compra está sendo realizada.
​
SalesPerson
object
Informações do vendedor responsável pela venda.
​
Metadatas
array
Lista de metadados customizados para necessidades específicas do negócio.
{
  "CustomerId": "12345678900",
  "Value": null,
  "Points": null,
  "OriginalKey": "1-12345678900-PDV001",
  "Branch": {
    "OriginalId": "LOJA-001",
    "Name": "Loja Centro"
  },
  "SalesPerson": {
    "OriginalId": "VEND-123",
    "Name": "João Silva"
  }
}
​
Result.RewardId
integer
ID único do resgate realizado. Use este ID para cancelar a recompensa se necessário.
​
Result.ExternalCode
string
IMPORTANTE: Este código deve ser enviado no campo Coupon quando o pedido for cadastrado na BonifiQ. Isso vincula o resgate ao pedido.
​
Result.OriginalKey
string
Mesma chave enviada na requisição, confirmando a idempotência.
​
Result.Point.PointId
integer
ID do registro de pontos gerado pelo resgate.
​
Result.Point.Quantity
integer
Quantidade de pontos utilizados (valor negativo indica débito).
Após receber a resposta de sucesso, aplique o desconto correspondente no pedido do PDV. O tipo e valor do desconto foram informados no endpoint /rewards/available.

​
Cadastro de Pedidos

Após a conclusão de uma venda, esta deve ser enviada à BonifiQ para que os pontos sejam creditados ao cliente.
Importante: Todos os pedidos devem ser enviados à BonifiQ - mesmo aqueles em que não se utilizou um benefício.

​
Cadastrar Pedido

​
/orders
Cadastra um pedido na BonifiQ para que o cliente receba os pontos correspondentes.
Deve-se notar que o campo OrderTotal deve conter o valor pago pelo consumidor, portanto não deve conter valores de descontos, cupons, cashback, promoções, etc.
​
OriginalId
string
required
ID do pedido no sistema do cliente (PDV).
​
OrderPlacementDate
datetime
required
Data/hora em que o pedido foi realizado.
​
OrderCompletedDate
datetime
Data/hora em que o pedido foi concluído. Obrigatório se IsCompleted=true.
​
OrderCancelledDate
datetime
Data/hora do cancelamento. Obrigatório se IsCancelledOrReturned=true.
​
OrderStatus
string
Status do pedido no sistema de origem (informativo).
​
IsCompleted
boolean
required
Se true, o pedido está finalizado e os pontos serão concedidos ao cliente.
​
IsCancelledOrReturned
boolean
required
Se true, o pedido foi cancelado ou devolvido.
​
OrderTotal
decimal
required
Valor pago pelo cliente. Este valor determina quantos pontos o cliente receberá.
NÃO inclua neste valor:
  • Frete
  • Descontos
  • Cupons
  • Cashback
  • Promoções
  • Gift cards
​
Coupon
string
IMPORTANTE: Se o pedido utilizou uma recompensa da BonifiQ, informe aqui o ExternalCode retornado no resgate. Se não utilizou recompensa BonifiQ mas usou outro cupom, informe o código do cupom.
​
Customer
object
required
Dados do cliente comprador.
​
Products
array
Lista de produtos do pedido.
​
PaymentMethod
object
Método de pagamento utilizado.
​
Branch
object
Filial onde a compra foi realizada.
​
SalesPerson
object
Vendedor responsável pela venda.
​
Metadatas
array
Lista de metadados customizados.
{
  "OriginalId": "PDV-2024-001234",
  "OrderPlacementDate": "2024-01-15T10:30:00Z",
  "OrderCompletedDate": "2024-01-15T10:35:00Z",
  "OrderCancelledDate": null,
  "OrderStatus": "Concluído",
  "IsCancelledOrReturned": false,
  "IsCompleted": true,
  "OrderTotal": 140.00,
  "Coupon": "BNF-2024-ABC123",
  "Customer": {
    "OriginalId": "CLI-12345",
    "Name": "Maria Silva",
    "Email": "maria@email.com",
    "Phone": "11999998888",
    "Document": "12345678900",
    "BirthdayDate": "1990-05-15",
    "SignupDate": "2023-06-01T00:00:00Z",
    "IsEnrolled": true
  },
  "Products": [
    {
      "OriginalId": "PROD-001",
      "Name": "Camiseta Azul M",
      "Quantity": 2,
      "Price": 75.00
    }
  ],
  "PaymentMethod": {
    "OriginalId": "PIX",
    "Name": "PIX"
  },
  "Branch": {
    "OriginalId": "LOJA-001",
    "Name": "Loja Centro"
  },
  "SalesPerson": {
    "OriginalId": "VEND-123",
    "Name": "João Silva"
  },
  "Metadatas": [
    {
      "Name": "canal_venda",
      "Value": "presencial"
    }
  ]
}

​
Cancelar Pedido

​
/orders/{orderId}/cancel
Cancela um pedido existente na BonifiQ.
Quando um pedido é cancelado, a BonifiQ automaticamente:
  • Marca o pedido como Cancelado (refletido nos relatórios)
  • Estorna os pontos concedidos ao cliente (se houver)
  • Estorna as recompensas utilizadas (se houver)

​
Path Parameters

​
orderId
string
required
O OriginalId do pedido que foi enviado quando o pedido foi criado.
​
OrderCancelledDate
datetime
required
Data/hora do cancelamento.
​
OrderStatus
string
Novo status do pedido (informativo).
{
  "OrderCancelledDate": "2024-01-15T15:30:00Z",
  "OrderStatus": "Cancelado"
}

​
Cancelamento Parcial de Pedido

​
/{orderId}/partialcancel
Cancela parcialmente um pedido, estornando pontos/cashback proporcionalmente.
Use este endpoint quando o cliente devolve apenas parte dos produtos de uma compra.

​
Path Parameters

​
orderId
string
required
O OriginalId do pedido.
​
ValueToRefund
decimal
required
Valor a ser estornado. Deve ser maior que zero e menor ou igual ao OrderTotal original.
​
CancelKey
string
required
Chave única para garantir idempotência. Evita cancelamentos duplicados do mesmo valor. Use um ID único para cada solicitação de cancelamento parcial.
{
  "ValueToRefund": 50.00,
  "CancelKey": "REFUND-PDV001-2024-001"
}
O cancelamento parcial estorna pontos/cashback proporcionalmente ao valor devolvido. Por exemplo, se o pedido original era de R$200,00 e rendeu 200 pontos, um estorno de R$50,00 removerá aproximadamente 50 pontos do cliente.

​
Cancelamento de Recompensas

Quando um resgate é realizado, os pontos correspondentes são debitados do cliente. Se a venda ainda não foi concluída, é possível cancelar o resgate - devolvendo os pontos (ou cashback) de volta ao cliente. Existem duas formas de cancelar uma recompensa resgatada:

​
Cancelar por ID da Recompensa

​
/rewards/{id}
Cancela uma recompensa pelo ID do resgate.

​
Path Parameters

​
id
integer
required
O RewardId retornado no endpoint de resgate.
DELETE /v1/pvt/POS/rewards/456

​
Cancelar por OriginalKey

​
/rewards
Cancela uma recompensa pela OriginalKey usada no resgate.
​
OriginalKey
string
required
A mesma OriginalKey utilizada no momento do resgate.
{
  "OriginalKey": "1-12345678900-PDV001"
}
O cancelamento de uma recompensa devolve os pontos ao cliente. Esta operação não pode ser desfeita.

​
Tratamento de Erros

Todos os endpoints retornam erros no seguinte formato: 
{
  "HasError": true,
  "ErrorMessage": "Descrição técnica do erro",
  "FriendlyErrorMessage": "Mensagem amigável para o usuário"
}

​
Códigos de Erro Comuns

CenárioAção Recomendada
Cliente não encontradoVerificar se o documento foi digitado corretamente
Pontos insuficientesInformar ao cliente que ele não tem pontos suficientes
Valor de compra abaixo do mínimoInformar o valor mínimo necessário
Challenge expiradoSolicitar novo código ao cliente
Código PIN inválidoPermitir nova tentativa ou cancelar
Recompensa já resgatada (idempotência)A operação já foi realizada, prosseguir

​
Boas Práticas

Em sistemas distribuídos, falhas de rede podem causar requisições duplicadas. Use sempre a OriginalKey com um valor único e consistente para evitar resgates ou cancelamentos duplicados.
Sempre envie o ExternalCode retornado no resgate como valor do campo Coupon ao cadastrar o pedido. Isso permite rastreamento completo.
O OrderTotal deve refletir apenas o valor efetivamente pago pelo cliente, sem frete, descontos, cupons ou promoções. Isso garante o cálculo correto de pontos.
Verifique o campo shouldValidateCustomer antes de iniciar o fluxo de challenge. Se false, pule direto para o resgate.
Mesmo que canUse=false, exiba a recompensa ao cliente (em estado desabilitado). Isso o motiva a acumular mais pontos para futuras compras.

​
Projeto de Referência

Disponibilizamos um repositório público no GitHub com um PDV mockado que demonstra a integração completa com a BonifiQ. Este projeto pode ser usado como referência para auxiliar no desenvolvimento da sua integração.

PDV BonifiQ Integration Example

Repositório com código-fonte de um PDV de exemplo integrado com a API da BonifiQ. Inclui implementação de todos os fluxos documentados nesta página.
O projeto de referência inclui:
  • Implementação completa do fluxo de resgate de recompensas
  • Exemplos de tratamento de erros
  • Integração com autenticação Basic Auth
  • Interface de usuário mockada para testes

​
Checklist de Implementação

Use esta lista para acompanhar seu progresso na integração:
  • Obter credenciais de API (usuário e senha)
  • Configurar autenticação Basic Auth no sistema
  • Testar conexão com a API em ambiente de sandbox
  • Implementar consulta de recompensas (/rewards/available)
  • Exibir lista de recompensas disponíveis ao vendedor
  • Tratar cenário “sem recompensas disponíveis”
  • Implementar seleção de valor para Cashback
  • Implementar validação via challenge (se aplicável)
  • Implementar resgate de recompensa (/rewards/{id}/redeem)
  • Aplicar desconto no pedido após resgate
  • Implementar cadastro de pedidos (/orders)
  • Enviar ExternalCode no campo Coupon quando houver resgate
  • Implementar cancelamento total de pedidos
  • Implementar cancelamento parcial (se necessário)
  • Tratar erros de autenticação
  • Tratar erros de cliente não encontrado
  • Tratar erros de pontos insuficientes
  • Exibir mensagens amigáveis ao usuário
  • Testar fluxo completo de resgate em sandbox
  • Testar cancelamento de recompensa
  • Testar cadastro de pedido com e sem recompensa
  • Validar idempotência com OriginalKey
  • Testar em produção com valores reais

​
Ambiente de Testes (Sandbox)

Para desenvolvimento e testes, utilize o mesmo endpoint de produção, porém com credenciais específicas de sandbox, fornecidas pela BonifiQ.
URL de Sandbox: https://api.bonifiq.com.br/v1/pvt/POSEntre em contato com o suporte para obter credenciais de teste.

​
Limites da API (Rate Limits)

Para garantir a estabilidade do serviço, a API possui limites de requisições:
Tipo de LimiteValorPeríodo
Requisições por segundo10Por segundo
Requisições por minuto300Por minuto
Requisições por hora10.000Por hora
Se você atingir o limite, receberá uma resposta HTTP 429 Too Many Requests. Implemente um mecanismo de retry com backoff exponencial para lidar com esses casos.

​
Glossário

Benefício que o cliente pode resgatar usando seus pontos acumulados. Pode ser um desconto fixo (ex: R$10,00), desconto percentual (ex: 15% off), ou cashback.
Unidade de crédito acumulada pelo cliente a cada compra. A quantidade de pontos é calculada com base no valor do pedido e nas regras configuradas pelo lojista.
Pontos e Cashback são intercambiáveis - cada ponto possui um valor em reais definido pelo lojista. Ao resgatar uma recompensa de cashback, o cliente utiliza seus pontos para obter um saldo em reais. Ela é um tipo especial de recompensa: diferente dos pontos, o cliente pode escolher quanto do cashback deseja utilizar.
Processo de validação de identidade onde um código PIN é enviado ao cliente. O cliente deve informar este código ao vendedor para confirmar que é o titular da conta.
Chave única usada para garantir idempotência nas operações. Se a mesma OriginalKey for enviada mais de uma vez, a API garante que a operação será executada apenas uma vez, evitando duplicações.
Código informado no momento do resgate de uma recompensa. Este código deve ser enviado no campo Coupon ao cadastrar o pedido, permitindo vincular o resgate ao pedido final.
Sistema de Ponto de Venda utilizado em lojas físicas para processar vendas. A integração com a BonifiQ permite que o PDV consulte e resgate recompensas durante o processo de venda.
Valor efetivamente pago pelo cliente, excluindo frete, descontos, cupons e promoções. Este valor é usado para calcular os pontos que o cliente receberá pela compra.

​
FAQ - Perguntas Frequentes

Se você enviar um pedido com o mesmo OriginalId, a BonifiQ atualizará o pedido já existente na base.
Não. O sistema permite apenas uma recompensa por compra. Se houver múltiplas recompensas disponíveis, o vendedor deve apresentar as opções ao cliente para que ele escolha qual deseja utilizar.
O e-mail sempre é enviado, quando disponível. WhatsApp e SMS precisam ser contratados à parte com a BonifiQ. Também é possível enviar o PIN via webhooks para disparos externos.
O código PIN é válido por 60 minutos após o envio. Se expirar, o vendedor deve solicitar um novo código através do endpoint de challenge.
Não necessariamente. Se o cliente não existir, ele será criado automaticamente quando o primeiro pedido for cadastrado. Porém, para consultar recompensas e resgatar benefícios, o cliente precisa ter um histórico de compras que tenha gerado pontos.
Verifique o campo ShouldValidateCustomer na resposta do endpoint /rewards/available. Se for true, você deve executar o fluxo de challenge antes do resgate. Se for false, pode pular direto para o resgate.
Sim, desde que o pedido ainda não tenha sido finalizado. Use o endpoint de cancelamento de recompensa (DELETE /rewards/{id}) ou envie a OriginalKey para cancelar. Os pontos/cashback serão devolvidos ao cliente.
A OriginalKey é uma chave única que identifica uma operação específica. Recomendamos o formato: {rewardId}-{customerId}-{orderId}-{timestamp}. Ela garante que mesmo se houver falha de rede e você reenviar a requisição, a operação será executada apenas uma vez.
O OrderTotal representa o valor real da compra para cálculo de pontos. Se incluir descontos, o cliente receberia menos pontos do que deveria. Envie sempre o valor dos produtos antes de qualquer desconto, cupom ou promoção.
Sim! Todos os pedidos devem ser enviados à BonifiQ, independentemente de terem utilizado recompensas ou não. Isso é essencial para que os clientes acumulem pontos em todas as compras.
O cancelamento parcial permite estornar apenas parte do valor do pedido (ex: devolução de um item). A BonifiQ calcula proporcionalmente os pontos a serem removidos. Por exemplo, se um pedido de R$200 gerou 200 pontos e você estorna R$50, aproximadamente 50 pontos serão removidos do cliente.

​
Suporte

Em caso de dúvidas ou problemas na integração: