Skip to main content
A extensão de fidelidade permite que o seu sistema atue como operador de fidelidade dentro da DeliveryVip: o cliente adere ao seu programa direto no checkout, resgata saldo (cashback) como desconto no pedido e acumula sobre os pedidos concluídos, tudo sem que o saldo saia do seu lado.

​
Papéis

O dinheiro de fidelidade nunca vive do lado da DeliveryVip. A plataforma guarda apenas o vínculo do cliente com o programa (consentimento e um accountId opaco que você fornece) e o registro dos resgates. Saldo, extrato e regras de acúmulo são seus.

​
As duas metades da integração

A integração tem dois sentidos, com autenticações diferentes. Vale ter isso claro antes de escrever qualquer código.
O cliente HTTP do operador chama a Merchant API com OAuth; o checkout da DeliveryVip chama o servidor do contrato do operador com HMAC; eventos de pedido chegam por webhookO cliente HTTP do operador chama a Merchant API com OAuth; o checkout da DeliveryVip chama o servidor do contrato do operador com HMAC; eventos de pedido chegam por webhook

As duas metades da integração: o que você chama e o que a DeliveryVip chama

1. APIs que você chama

Autenticação OAuth2 (client credentials) e a API Merchant V3:
  • PUT/DELETE /merchant/v3/{merchantId}/loyalty/config: o config push que ativa o programa por loja;
  • GET /merchant/v3/orders/{orderId}: a leitura do pedido para o acúmulo.

2. O contrato que você implementa

Cinco rotas sob a api_base_url do seu app, chamadas pela DeliveryVip com assinatura HMAC:
  • ping, accounts:link e a consulta de saldo;
  • o débito do resgate e o estorno.

​
O que o cliente vê

No checkout (tanto na loja própria quanto no marketplace: o programa acompanha a loja), o cliente vê um card do seu programa:
  • Só para clientes identificados: a adesão é oferecida a clientes logados (nunca convidados) com cadastro completo: nome, telefone, e-mail, CPF e data de nascimento. Se faltar CPF ou data de nascimento, o checkout pede para completar.
  • Opt-in com consentimento: o clique de adesão é o consentimento (LGPD). Se o seu programa exigir, um PIN é solicitado e validado por você.
  • Resgate com limite: o cliente escolhe quanto do saldo usar. O resgate se aplica somente à soma dos itens: frete e taxas nunca entram.
  • 1 resgate por pedido. Um resgate que cobre 100% do pedido vira o pagamento REDEEM.

​
A jornada de ponta a ponta

Config push e ping, adesão, consulta de saldo, resgate no pedido e acúmulo a partir do evento CONCLUDEDConfig push e ping, adesão, consulta de saldo, resgate no pedido e acúmulo a partir do evento CONCLUDED

A jornada de ponta a ponta

​
Escopo da v1

  • Tipo de saldo: cashback (valor em BRL). Outros tipos de saldo poderão ser adicionados em versões futuras do contrato.
  • O programa pode ser de loja (store), rede (chain) ou coalizão (coalition).

​
Comece por aqui

Primeiros passos

Crie o app com o scope dv.loyalty, declare a extensão de fidelidade e obtenha o token com os dois scopes necessários.

Ativando o programa

Ative o programa por loja com o config push, verificado na hora por um ping assinado no seu endpoint.

Contrato do operador

As cinco rotas HTTP que o seu sistema implementa e a DeliveryVip chama, todas assinadas com HMAC-SHA256 do corpo bruto.

Acúmulo

Receba o evento, busque o pedido com od.all e leia o bloco loyalty. A base de cálculo é sua.

Operador mínimo

Um operador completo em Node.js ou Python, ativo em uma loja de teste: adesão, saldo, resgate e estorno.