Pular para o conteúdo principal
Ao final deste guia você tem um operador de fidelidade rodando, com as cinco rotas do contrato, ativo em uma loja de teste. Um cliente adere ao programa no checkout, vê o saldo, resgata cashback no pedido e recebe o saldo de volta quando o pedido é cancelado.
Quer um operador mais completo, com banco de dados, painel e cenários de erro? Veja o Cofrinho, nosso operador de exemplo em Node.js, de código aberto.

Como funciona

  1. A DeliveryVip chama você. Durante o checkout, ela faz requisições HTTP às rotas sob a api_base_url da extensão de fidelidade do seu app. Você responde; o saldo vive só do seu lado.
  2. Toda chamada é assinada. O header X-App-Signature traz o HMAC-SHA256, em hex minúsculo, do corpo bruto da requisição, com o client_secret do app como chave. Sem corpo (ping e reversal), assina-se a string vazia. Não há timestamp na assinatura.
  3. A ativação depende do ping. O config push (PUT .../loyalty/config) chama o seu GET /v1/loyalty/ping antes de gravar qualquer coisa: o operador precisa estar no ar e validando a assinatura antes de ativar.
  4. Débito e estorno são idempotentes. O débito usa o relatedOrderId como chave: o mesmo pedido com o mesmo valor devolve o mesmo redemptionId. O estorno de um resgate já estornado responde 2xx de novo.
  5. Responda só os códigos do contrato. Respostas de negócio (404 no link, 409 e 422 no débito) são lidas como recusa. Qualquer outra coisa conta como falha para o circuit breaker.

Antes de começar

Um app com a extensão de fidelidade

Scopes dv.loyalty e od.all, com client_id e client_secret em mãos.

Uma loja de teste com o app instalado

E o merchantId dela. Peça uma loja de teste no Discord.

Node.js 18+ ou Python 3.9+

E uma URL pública HTTPS para o operador, como um túnel (cloudflared, ngrok) apontando para a sua máquina.
Exporte as credenciais do app como variáveis de ambiente:

O operador completo

Um único arquivo, sem banco: contas e resgates ficam em memória e somem quando o processo para. Toda conta nova ganha R$ 20,00 de saldo, só para você conseguir testar o resgate. A assinatura é validada antes de qualquer rota, sobre os bytes recebidos, e o JSON só é lido depois disso.
A versão Node.js usa só o módulo http, sem dependências. Se você usar um framework, garanta que accounts:link seja tratado como caminho literal: em roteadores como o do Express, : marca o início de um parâmetro.

Passo a passo

1

Rode o operador e teste a assinatura

Suba o operador:
Em outro terminal, assine as requisições como a DeliveryVip faz e chame o operador. A função sign calcula o HMAC-SHA256 do corpo com o client_secret:
Resposta da adesão
204 no ping assinado e 401 no ping com assinatura errada: a verificação está certa. Para testar o débito e o estorno, assine da mesma forma o corpo de redemptions com o id da conta.
2

Exponha o operador e declare a api_base_url

A DeliveryVip precisa alcançar o operador pela internet, em HTTPS. Abra um túnel para a porta 4001 e, na extensão de fidelidade do app, informe a URL do túnel como api_base_url (por exemplo, https://seu-tunel.example.com). A DeliveryVip acrescenta /v1/loyalty/... a ela.
http:// só é aceito em loopback (localhost, 127.x.x.x, ::1). Um operador em localhost não é alcançável pelo checkout da DeliveryVip: para o teste de ponta a ponta, use o túnel.
3

Obtenha o token com os dois scopes

O config push exige o scope dv.loyalty; o od.all serve para ler os pedidos no acúmulo. Peça os dois no mesmo token, separados por espaço.
4

Ative o programa na loja

Com o operador no ar, envie o config push para a loja. O program.id precisa ser o mesmo PROGRAM_ID do operador (clube-teste por padrão): é ele que volta no programId das chamadas. Durante o PUT, o operador recebe o ping e registra GET /v1/loyalty/ping -> 204.
A resposta 200 ecoa a configuração gravada. Um 422 com Verificação da api_base_url falhou no title significa que o ping não passou e nada foi gravado. Veja os demais campos, como os limites de resgate, em Ativando o programa.
5

Adira ao programa no checkout

Abra a loja de teste, entre com uma conta de cliente, monte um carrinho e vá ao checkout. O card do Clube de Teste aparece. A adesão só é oferecida a um cliente logado (convidados não aderem) e com o cadastro completo: nome, telefone, e-mail, CPF e data de nascimento. Se faltar CPF ou data de nascimento, o checkout pede para completar.Ao aceitar participar, o operador recebe o link e, em seguida, a consulta de saldo:
Saída esperada (Node.js)
O card mostra o saldo de R$ 20,00. A DeliveryVip guarda a resposta do saldo por até 60 segundos.
6

Resgate e finalize o pedido

Escolha quanto do saldo usar e finalize o pedido com pagamento na entrega. O débito acontece dentro da criação do pedido: o pedido só nasce se o operador responder 201.
No teste, prefira pagamento na entrega. Um pedido com pagamento online responde 404 em GET /merchant/v3/orders/{orderId} até o pagamento ser aprovado, e um pedido que segue aguardando pagamento depois de 30 minutos é dado como não pago, o que dispara o estorno do resgate.
Saída esperada (Node.js)
O pedido aparece no painel da loja com o desconto do resgate, e o saldo do cliente no operador caiu no mesmo valor.
7

Cancele o pedido e veja o estorno

Cancele o pedido no painel da loja. A DeliveryVip chama o estorno de forma assíncrona, e o saldo volta para a conta:
Saída esperada (Node.js)
Volte ao checkout com o mesmo cliente: em até 60 segundos o card mostra de novo o saldo de R$ 20,00.

Do mínimo para a produção

Este operador cobre o contrato, mas não é um programa de verdade. Antes de produção:
  • Persista tudo em banco, com a idempotência do débito garantida por uma restrição única em relatedOrderId, e guarde o consent recebido no link.
  • Acumule saldo sobre os pedidos concluídos: receba o evento CONCLUDED, busque o pedido com od.all e leia o bloco loyalty. Veja Acúmulo.
  • Diferencie as lojas pelo header X-App-MerchantId, se o seu programa tiver regras por loja.
  • Exija PIN, se o seu programa pedir confirmação na adesão. Veja Vínculo e PIN.
  • Responda rápido: a DeliveryVip espera no máximo 5 segundos, e o débito roda dentro da criação do pedido.

Erros comuns

Próximos passos

Acúmulo

Credite cashback sobre os pedidos concluídos e desfaça no cancelamento.

Vínculo e PIN

O desafio de PIN e os limites de resgate por conta.

Resgate e estorno

Todos os casos do débito síncrono e do estorno.

Referência rápida

Rotas, headers, limites e regras em uma página.

Cofrinho

Operador de exemplo completo: SQLite, painel de controle e painel de caos para testar falhas.