Skip to main content
Esta é a metade da integração em que a DeliveryVip é o cliente e o seu sistema é o servidor. Você expõe cinco rotas sob a api_base_url declarada na extensão do app, e a DeliveryVip as chama durante o checkout, sempre com as requisições assinadas.
Config push chama o ping; adesão chama accounts:link; ver saldo chama accounts/{accountId}; resgate chama redemptions; pedido cancelado chama reversalConfig push chama o ping; adesão chama accounts:link; ver saldo chama accounts/{accountId}; resgate chama redemptions; pedido cancelado chama reversal

Quando a DeliveryVip chama cada rota do contrato

As cinco rotas

A spec OpenAPI completa do contrato está em loyalty_operator.yaml e na aba de referência.
O prefixo /v1 é a versão do contrato, definida pela DeliveryVip. Ele é acrescentado à sua api_base_url, que pode ter um prefixo próprio: com https://operador.example.com/dv, o ping chega em https://operador.example.com/dv/v1/loyalty/ping. Um futuro contrato v2 será chamado em /v2 sob a mesma api_base_url. A rota accounts:link usa dois-pontos (método customizado, no mesmo estilo do events:polling da API Merchant).

Autenticação das chamadas

As chamadas do contrato não usam OAuth. Cada requisição carrega estes headers:
Os webhooks de pedido usam os mesmos nomes de header, mas lá o X-App-Id é um identificador fixo da plataforma, não o client_id do seu app. A assinatura segue a mesma regra nos dois casos.
Para validar, recompute o HMAC sobre os bytes recebidos e compare com o header em tempo constante:
Verifique a assinatura sobre os bytes exatamente como recebidos, antes de qualquer parse ou re-serialização do JSON. Fazer parse e re-encodar muda os bytes: escapes \uXXXX viram UTF-8, espaçamento e ordem de chaves mudam, 25.00 vira 25, e o digest não bate. Esse é o erro de integração mais comum.
A chave é o Client Secret atual do app. Se você renovar o secret no painel de developers, as chamadas seguintes já chegam assinadas com o novo valor: atualize o seu lado na mesma hora, ou o próximo ping, link ou débito falha.
Rejeite qualquer requisição cuja assinatura não confira: ela é a única prova de que a chamada veio da DeliveryVip. Use o X-App-MerchantId para saber de qual loja é a chamada, se o seu programa diferencia lojas.

Timeouts e circuit breaker

  • A DeliveryVip usa timeouts curtos: 3 s para conectar, 5 s para ler. Responda rápido, em especial no débito, que roda dentro da criação do pedido.
  • 5 falhas em 5 minutos abrem um circuit breaker de 5 minutos para a extensão inteira: o card do programa some do checkout até o circuito fechar. Qualquer resposta esperada zera a contagem de falhas.
  • Conta como falha: timeout, erro de conexão, 5xx, um código que a rota não prevê e um corpo malformado (JSON inválido, ou 201 sem redemptionId no débito).
  • Não conta como falha: as respostas de negócio que cada rota prevê, como 403 e 404 no link, 404 na consulta de saldo, 409 e 422 no débito.
Responda só os códigos documentados em cada rota. Um 400 ou 401 no débito, por exemplo, não é lido como recusa de negócio: conta para o breaker e o cliente vê uma indisponibilidade genérica.

Compatibilidade

Campos desconhecidos que você emitir nas respostas (ex.: expiresAt, metadata) são ignorados pela DeliveryVip, então é seguro incluí-los. Do outro lado, trate campos novos que apareçam nas requisições futuras da mesma forma: ignore o que não conhece.

Próximos passos

Vínculo e PIN

accounts:link, o desafio de PIN e a consulta de saldo.

Resgate e estorno

O débito síncrono no checkout e o estorno idempotente.