> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Documentação das APIs da DeliveryVip, em português. Regras que mais quebram integrações: (1) Merchant API: faça polling em GET /merchant/v3/events:polling no máximo a cada 30 s por token; confirme todo evento recebido com POST /merchant/v3/events/acknowledgment e corpo [{"id": ""}] (o campo lido é id, não eventId), inclusive eventos repetidos ou que o sistema não trata; deduplique por eventId; o evento é só um aviso, busque o pedido na orderURL. (2) Tokens client_credentials valem 24 h e não têm refresh_token: peça outro ao receber 401. (3) Webhooks: valide a assinatura HMAC sobre o corpo bruto e responda 2xx rápido; o polling é a reconciliação. (4) Open Delivery: host od.deliveryvip.com.br, um client_secret por loja, datas em UTC. (5) Fidelidade: o operador implementa 5 rotas assinadas com HMAC e chama o config push; o estorno precisa ser idempotente. (6) Partner API: scope dv.partner. Não invente endpoints: use a referência gerada das specs OpenAPI. # Open Delivery > Integre seu PDV/ERP com a DeliveryVip usando o padrão aberto Open Delivery, sem precisar da API proprietária. O [**Open Delivery**](https://www.opendelivery.com.br) é uma especificação aberta brasileira que padroniza a integração entre plataformas de pedidos e sistemas de PDV/gestão. Se o seu sistema já fala Open Delivery, você integra com a DeliveryVip sem escrever código específico da nossa API proprietária. ## Papéis Na terminologia do Open Delivery: | Papel | Quem | O que faz | | - | - | - | | **Ordering App** | DeliveryVip | Origem dos pedidos: emite eventos, expõe os pedidos e recebe as transições de status. | | **Merchant** | Seu PDV/ERP | Recebe eventos, consulta pedidos, transiciona status e pode expor seu catálogo no padrão OD para a plataforma importar. | ## Quem chama quem As chamadas acontecem nos dois sentidos. Você chama a API OD da DeliveryVip com um token OAuth por loja; a DeliveryVip chama o seu webhook e o seu endpoint de catálogo. ![O cliente HTTP do PDV chama a API Open Delivery; a DeliveryVip envia eventos ao ordersWebhookURL e importa o catálogo da getMerchantURL](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/od-visao-geral.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=e82aec93f31a1cf78629dc7efab83da0) Quem chama quem no Open Delivery ## Versões suportadas | Spec | Versão | | - | - | | Order | `1.3.0` | | Merchant | `1.0.0` | Os métodos de entrega de eventos disponíveis são **WEBHOOK** e **POLLING**. Recomendamos webhook como canal principal e polling como reconciliação; veja [Recebendo eventos](/docs/guides/open-delivery/recebendo-eventos.md). Você pode consultar as versões em tempo de execução pelos endpoints de versão; veja [Primeiros passos](/docs/guides/open-delivery/primeiros-passos.md). ## Um app, várias lojas Você cadastra **um único app** com a extensão Open Delivery e ele atende todas as lojas que o instalarem. Cada loja instalada recebe: * um **`client_secret` próprio** (o `client_id` é o do app): o token emitido com ele vale só para aquela loja, e é com ele que os webhooks da loja são assinados; * a **própria configuração**: `merchantId`, URL de webhook e endpoint de catálogo, definidos no [onboarding](/docs/guides/open-delivery/onboarding-de-lojas.md); * o **próprio circuito de webhooks**: uma loja com endpoint fora do ar não interrompe as entregas das demais. ## Host da API A API Open Delivery da DeliveryVip roda em um host dedicado: ``` https://od.deliveryvip.com.br ``` Os endpoints da spec ficam sob o prefixo `/v1`. O endpoint de token OAuth fica na **raiz** desse host (`POST /oauth/token`), fora do `/v1`, porque a spec OD pede uma baseURL de autenticação separada. > [!TIP] > > Se o seu sistema monta as rotas direto na URL base, sem o `/v1` (padrão das primeiras versões do Open Delivery), configure a URL base da API como `https://od.deliveryvip.com.br/v1` e mantenha a URL de login em `https://od.deliveryvip.com.br`. Um `404` em todas as chamadas costuma ser esse caso. ## Datas em UTC As datas da API Open Delivery são em **UTC** (RFC 3339, sufixo `Z`, ex.: `2026-08-10T17:39:28Z`), conforme exigido pela spec OD. Note a diferença para a API Merchant V3, que usa UTC-3; veja [Datas e horários](/docs/inicio/conceitos/datas-e-horarios.md). Isso vale também para o `createdAt` dos eventos entregues por webhook. ## Open Delivery ou API Merchant V3? > [card] Open Delivery > > Para quando o seu sistema já implementa (ou vai implementar) o padrão para integrar com múltiplas plataformas. Você reaproveita a mesma integração. > [card] [API Merchant V3](/docs/guides/merchant.md) > > Para acessar os recursos proprietários da plataforma que vão além da spec, como Indoor (comandas e places), descontos e a API de catálogo própria. Os dois caminhos são independentes: o formato dos objetos (pedido, catálogo) no Open Delivery segue a [spec oficial](https://www.opendelivery.com.br), e esta seção documenta apenas o que é específico da DeliveryVip. ## Comece por aqui > [card] [Primeiros passos](/docs/guides/open-delivery/primeiros-passos.md) > > Crie o app, receba a credencial da loja e obtenha o token. > [card] [Onboarding de lojas](/docs/guides/open-delivery/onboarding-de-lojas.md) > > Registre `merchantId`, webhook e endpoint de catálogo de cada loja. > [card] [Recebendo eventos](/docs/guides/open-delivery/recebendo-eventos.md) > > Webhook assinado como canal principal e polling como reconciliação. > [card] [Ciclo de vida do pedido](/docs/guides/open-delivery/ciclo-de-vida-do-pedido.md) > > Detalhes do pedido e as transições de status. > [card] [Seu primeiro pedido](/docs/guides/open-delivery/primeiro-pedido.md) > > Um programa completo: webhook assinado, confirmação do pedido e reconciliação pelo polling. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.