Pular para o conteúdo principal
Ao final deste guia você tem um programa rodando que recebe os pedidos de uma loja pelo Open Delivery e confirma cada um deles. Ele usa o webhook como canal principal e o polling como reconciliação, o mesmo desenho recomendado para produção.

Como funciona

  1. A credencial é da loja. O token é pedido com o client_id do app e o client_secret da loja (ods_...), e só enxerga aquela loja. O mesmo client_secret assina os webhooks dela.
  2. Evento é só um aviso. O webhook diz o que mudou (CREATED, CANCELLED…). Os dados do pedido vêm de um GET na orderURL do evento.
  3. Assinatura antes de tudo. O webhook traz um HMAC-SHA256 do corpo bruto no header X-App-Signature. Valide antes de fazer o parse.
  4. O mesmo evento pode chegar duas vezes. Pelo webhook e pelo polling, ou por um reenvio. Deduplique por eventId e envie o acknowledgment dos eventos já processados para que saiam do polling.
  5. Datas em UTC. As datas da API Open Delivery vêm em UTC (sufixo Z), inclusive o createdAt dos 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.
Exporte as credenciais como variáveis de ambiente:

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.
O onboarding substitui a configuração inteira da loja. Se ela já tem um endpoint de catálogo (getMerchantURL), envie-o junto, ou ele é apagado.
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 POST próprio na URL da loja:
Evento CREATED
Antes do parse, recompute o HMAC-SHA256 dos bytes recebidos com o 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ção handle, 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.
Rode, exponha a porta pelo túnel (a mesma URL do onboarding) e faça um pedido de teste na loja com pagamento na entrega. Um pedido com pagamento online responde 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.