> ## 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. # Consultar novos eventos > Faça o polling dos eventos de chamar garçom e fechar conta, drene a fila e filtre por tipo e loja. Os eventos de indoor chegam pelo mesmo endpoint de polling dos pedidos. Chame-o **a cada 30 segundos**. | Resposta | Quando | | - | - | | `200 OK` | Há eventos novos: uma lista com **até 100**, do mais antigo para o mais recente. | | `204 No Content` | Não há eventos novos. A resposta vem sem corpo. | > [!TIP] > > Chamar garçom é urgente. Use o [webhook](/docs/guides/merchant/webhooks.md) para receber cada evento no momento em que ele acontece, e mantenha o polling como reconciliação. ## Requisição Para receber só os eventos do salão, filtre por `eventType`. ```bash cURL theme={null} curl 'https://api.deliveryvip.com.br/merchant/v3/events:polling?eventType=CALL_WAITER&eventType=CLOSE_ACCOUNT' \ --header 'Authorization: Bearer {token}' \ --header 'x-polling-merchants: {merchantId}' ``` ```js Node.js theme={null} const url = new URL('https://api.deliveryvip.com.br/merchant/v3/events:polling') url.searchParams.append('eventType', 'CALL_WAITER') url.searchParams.append('eventType', 'CLOSE_ACCOUNT') const response = await fetch(url, { headers: { Authorization: `Bearer ${token}`, 'x-polling-merchants': merchantId }, }) const events = response.status === 204 ? [] : await response.json() ``` ```python Python theme={null} response = requests.get( "https://api.deliveryvip.com.br/merchant/v3/events:polling", params={"eventType": ["CALL_WAITER", "CLOSE_ACCOUNT"]}, headers={"Authorization": f"Bearer {token}", "x-polling-merchants": merchant_id}, ) events = [] if response.status_code == 204 else response.json() ``` ```json Resposta (200) theme={null} [ { "eventId": "78b58a39-e222-44a4-a2c4-083c4837ed7d", "createdAt": "2025-06-13T09:44:37-03:00", "merchantId": "86fb4f52-573e-4869-9764-87238bcbad01", "eventType": "CALL_WAITER", "metadata": { "placeName": "Mesa 20", "placeId": "indoor_qrcode_a7f4a8b1-8e6d-4614-be9a-b81b10a0de99" }, "placeName": "Mesa 20", "placeId": "indoor_qrcode_a7f4a8b1-8e6d-4614-be9a-b81b10a0de99" } ] ``` Os campos de cada evento estão em [eventos de indoor](/docs/guides/merchant/indoor/fluxo-de-integracao/eventos-de-indoor.md). ## A fila de eventos Eventos sem acknowledgment continuam voltando nas próximas chamadas até serem confirmados ou saírem da janela de 24 horas. **1. Polling** Chame o polling e processe os eventos recebidos. **2. Acknowledgment** Envie o [acknowledgment](/docs/guides/merchant/indoor/fluxo-de-integracao/acknowledgment-de-eventos.md) de todos os eventos recebidos. **3. Próximo lote** Chame o polling de novo: os eventos confirmados saem da fila e vem o próximo lote. > [!WARNING] > > **Lote cheio = fila acumulada.** Se a resposta vier com 100 eventos, há mais esperando. Envie o acknowledgment e chame o polling de novo **sem esperar os 30 segundos**, até receber menos de 100 eventos ou `204`. > [!CAUTION] > > Sem acknowledgment, a sua integração recebe sempre os mesmos eventos, os mais antigos primeiro, e nunca chega aos novos. ## Filtros Os filtros podem ser combinados. Um valor inválido em qualquer filtro retorna **`403 Forbidden`**. **eventType** `string[]` Tipos de evento a receber. Repita o parâmetro para cada valor, sem colchetes (`style: form`, `explode: true`). Os tipos de indoor são `CALL_WAITER` e `CLOSE_ACCOUNT`; os demais valores aceitos estão em [consultar novos pedidos](/docs/guides/merchant/order/fluxo-de-integracao/consultar-novos-pedidos.md#filtros). ```text theme={null} /merchant/v3/events:polling?eventType=CALL_WAITER&eventType=CLOSE_ACCOUNT ``` **orderType** `string[]` Filtra eventos pelo tipo do pedido (`DELIVERY`, `TAKEOUT` ou `INDOOR`). > [!WARNING] > > **`orderType` esconde os eventos de indoor.** Esse filtro só deixa passar eventos ligados a um pedido, e `CALL_WAITER` e `CLOSE_ACCOUNT` não pertencem a pedido nenhum. Até `orderType=INDOOR` os exclui. Se a sua integração filtra por `orderType`, faça uma chamada separada com `eventType=CALL_WAITER&eventType=CLOSE_ACCOUNT` ou use o webhook. **x-polling-merchants** `string[]` Lojas das quais receber eventos. Sem ele, o polling traz os eventos de **todas** as lojas que o token alcança. Envie um header por loja. Se o token não tiver acesso a alguma delas, a resposta é `403` e lista as lojas sem acesso; veja [como resolver](/docs/guides/merchant/order/fluxo-de-integracao/consultar-novos-pedidos.md#filtros). ```text theme={null} x-polling-merchants: 0a0000aa-0aa0-00aa-aa00-0000aa000001 x-polling-merchants: 0a0000aa-0aa0-00aa-aa00-0000aa000002 ``` > [accordion] Por quanto tempo os eventos ficam disponíveis? > > Por **24 horas a partir da criação do evento**. Depois disso, ele não volta mais no polling, mesmo sem acknowledgment. > [accordion] Qual é o intervalo mínimo entre chamadas? > > Uma chamada a cada **30 segundos** por token. Acima disso a API pode responder `429` e bloquear o cliente temporariamente. A única exceção é drenar uma fila acumulada (lote com 100 eventos). > [accordion] Recebo eventos de várias lojas misturados > > Sem `x-polling-merchants`, o lote traz eventos de todas as lojas do token. Use o header, ou separe os eventos pelo `merchantId` de cada um. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.