> ## 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": "<eventId>"}] (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.

# Eventos

> Entenda o polling de eventos, a fila de 100 eventos por chamada e quando combinar polling com webhook.

Toda mudança relevante numa loja gera um evento: um pedido criado, confirmado, despachado ou cancelado, um cliente chamando o garçom ou pedindo a conta. O seu sistema recebe esses eventos de duas formas, que funcionam de modo independente.

> [card] [Webhook](/docs/guides/merchant/webhooks.md)
>
> A DeliveryVip faz um `POST` na sua URL assim que o evento acontece. Sem fila para drenar, sem limite de 100 e sem intervalo de consulta.

> [card] [Polling](/docs/guides/merchant/order/fluxo-de-integracao/consultar-novos-pedidos.md)
>
> O seu sistema chama `GET /merchant/v3/events:polling` a cada 30 segundos e confirma o que processou.

> [!TIP]
>
> Uma integração robusta usa o **webhook como canal principal** e o **polling como reconciliação**. Receber um evento por webhook não o tira da fila do polling, e vice-versa.

## Como funciona o polling

![A cada 30 segundos o sistema chama o polling; com eventos, processa, descarta repetidos e envia o acknowledgment; com a fila vazia recebe 204](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/eventos-polling.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=92d92decdbf8f062313115636b171738)

O ciclo do polling de eventos

**1. Consulte a fila**

`GET /merchant/v3/events:polling` devolve até **100 eventos**, do mais antigo para o mais recente, ou `204` quando não há nada novo.

**2. Processe cada evento**

Use o `eventType` para decidir o que fazer. Eventos de pedido trazem a `orderURL` para buscar os detalhes.

**3. Confirme o recebimento**

Envie os `eventId` processados em `POST /merchant/v3/events/acknowledgment`. Eventos sem acknowledgment voltam na próxima chamada.

> [!WARNING]
>
> Se a resposta trouxer 100 eventos, a fila está acumulada. Envie o acknowledgment e chame o polling de novo **sem esperar os 30 segundos**, até receber menos de 100 eventos ou `204`.

> [!NOTE]
>
> O polling só considera eventos criados nas **últimas 24 horas**. Eventos mais antigos deixam de ser retornados, mesmo sem acknowledgment.

## Tipos de evento

> [card] [Eventos de pedidos](/docs/guides/merchant/order/fluxo-de-integracao/eventos-de-pedidos.md)
>
> `CREATED`, `CONFIRMED`, `DISPATCHED`, `CANCELLED` e os demais estados do pedido.

> [card] [Eventos de indoor](/docs/guides/merchant/indoor/fluxo-de-integracao/eventos-de-indoor.md)
>
> `CALL_WAITER` e `CLOSE_ACCOUNT`, gerados pelas comandas e mesas do autoatendimento.

## Próximos passos

> [card] [Consultar novos pedidos](/docs/guides/merchant/order/fluxo-de-integracao/consultar-novos-pedidos.md)
>
> Requisição, filtros por tipo de evento, tipo de pedido e loja.

> [card] [Acknowledgment](/docs/guides/merchant/order/fluxo-de-integracao/acknowledgment-de-eventos.md)
>
> Como confirmar os eventos e tirar da fila.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.