Como funciona
- A credencial é da loja. O token é pedido com o
client_iddo app e oclient_secretda loja (ods_...), e só enxerga aquela loja. O mesmoclient_secretassina os webhooks dela. - Evento é só um aviso. O webhook diz o que mudou (
CREATED,CANCELLED…). Os dados do pedido vêm de umGETnaorderURLdo evento. - Assinatura antes de tudo. O webhook traz um HMAC-SHA256 do corpo bruto no header
X-App-Signature. Valide antes de fazer o parse. - O mesmo evento pode chegar duas vezes. Pelo webhook e pelo polling, ou por um reenvio. Deduplique por
eventIde envie o acknowledgment dos eventos já processados para que saiam do polling. - Datas em UTC. As datas da API Open Delivery vêm em UTC (sufixo
Z), inclusive ocreatedAtdos webhooks.
Antes de começar
Um app com a extensão Open Delivery
Scope
od.all, com o client_id do app em mãos.Uma loja com o app instalado
E o
client_secret dela (ods_...). Peça uma loja de teste no Discord.Node.js 18+ ou Python 3.9+
E uma URL pública HTTPS para o webhook, como um túnel (
cloudflared, ngrok) apontando para a sua máquina.Passo a passo
1
Obtenha o token da loja
O endpoint de token fica na raiz do host OD, fora do
/v1. O token vale 24 horas e só opera a loja daquele client_secret. Enquanto ele não expira, um novo pedido de token devolve o mesmo token.2
Registre o merchantId e a URL de webhook da loja
O onboarding grava o
merchantId da loja no seu sistema e a URL que recebe os webhooks dela. Faça isso uma vez por loja (ou preencha o formulário “Dados da integração da loja” no painel de developers). A URL precisa ser pública; para testar na sua máquina, use a URL do túnel.Com o
merchantId configurado, a orderURL dos eventos aponta para a API OD (https://od.deliveryvip.com.br/v1/orders/...). Sem ele, a loja é identificada pelo id interno da DeliveryVip e a orderURL aponta para a API Merchant V3.3
Receba o evento CREATED no webhook
Cada evento chega em um Antes do parse, recompute o HMAC-SHA256 dos bytes recebidos com o
POST próprio na URL da loja:Evento CREATED
client_secret da loja e compare, em tempo constante, com o header X-App-Signature (hex minúsculo). Assinatura inválida: responda 401 e descarte. Válida: responda 200 na hora e processe depois. A DeliveryVip espera a resposta por até 5 segundos.Com várias lojas, o header
X-App-MerchantId diz de qual loja é o evento: use-o para escolher o secret certo. Veja Validando a assinatura.4
Busque os detalhes do pedido
Faça um
GET na orderURL do evento com o token da loja. O pedido segue a spec Order 1.3.0, com datas em UTC.5
Confirme o pedido
A resposta é 202 com o
id do pedido, e a plataforma emite o evento CONFIRMED.Neste guia o programa confirma todo pedido automaticamente. No seu PDV, confirme quando a loja aceitar, ou cancele se ela recusar.
6
Confirme o recebimento do evento
Eventos entregues por webhook também aparecem no polling até serem confirmados. Envie o acknowledgment com o
eventId no campo id. A resposta é 202 e a operação é idempotente.7
Reconcilie pelo polling
Se o seu endpoint ficar fora do ar, os eventos das últimas 24 horas continuam no
GET /v1/events:polling até receberem o acknowledgment: 200 com até 100 eventos, do mais antigo para o mais recente, ou 204 sem corpo. Processe o que vier (deduplicando por eventId) e confirme. Se vierem 100, consulte de novo sem esperar.O programa completo
Um único processo com as duas metades: o servidor do webhook e um loop de reconciliação a cada 30 segundos. Os dois passam pela mesma funçãohandle, que deduplica por eventId, busca o pedido, confirma e só então marca o evento como processado. Se algo falhar, o evento não é confirmado e volta no próximo polling.
404 no GET da orderURL até o pagamento ser aprovado:
Saída esperada
O pedido aparece como confirmado no painel da loja, e o evento
CONFIRMED chega em seguida no webhook (o programa só confirma o recebimento dele). Para testar a reconciliação, pare o programa, faça outro pedido e suba de novo: o pedido chega pelo polling.Erros comuns
Próximos passos
Ciclo de vida do pedido
Preparo, pronto para retirada, despacho, entrega, cancelamento e rastreio.
Recebendo eventos
Retentativas, suspensão por loja e os filtros do polling.
Catálogo
Exponha o catálogo da loja no padrão OD Merchant para a DeliveryVip importar.
Referência rápida
Endpoints, credenciais e limites em uma página.