api_base_url declarada na extensão do app, e a DeliveryVip as chama durante o checkout, sempre com as requisições assinadas.


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.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.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, ou201semredemptionIdno débito). - Não conta como falha: as respostas de negócio que cada rota prevê, como
403e404no link,404na consulta de saldo,409e422no débito.
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.