Como funciona
- A DeliveryVip chama você. Durante o checkout, ela faz requisições HTTP às rotas sob a
api_base_urlda extensão de fidelidade do seu app. Você responde; o saldo vive só do seu lado. - Toda chamada é assinada. O header
X-App-Signaturetraz o HMAC-SHA256, em hex minúsculo, do corpo bruto da requisição, com oclient_secretdo app como chave. Sem corpo (pingereversal), assina-se a string vazia. Não há timestamp na assinatura. - A ativação depende do ping. O config push (
PUT .../loyalty/config) chama o seuGET /v1/loyalty/pingantes de gravar qualquer coisa: o operador precisa estar no ar e validando a assinatura antes de ativar. - Débito e estorno são idempotentes. O débito usa o
relatedOrderIdcomo chave: o mesmo pedido com o mesmo valor devolve o mesmoredemptionId. O estorno de um resgate já estornado responde2xxde novo. - Responda só os códigos do contrato. Respostas de negócio (
404no link,409e422no 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.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 A resposta 200 ecoa a configuração gravada. Um 422 com
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.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:O card mostra o saldo de R$ 20,00. A DeliveryVip guarda a resposta do saldo por até 60 segundos.
Saída esperada (Node.js)
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.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:Volte ao checkout com o mesmo cliente: em até 60 segundos o card mostra de novo o saldo de R$ 20,00.
Saída esperada (Node.js)
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 oconsentrecebido no link. - Acumule saldo sobre os pedidos concluídos: receba o evento
CONCLUDED, busque o pedido comod.alle leia o blocoloyalty. 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.