> ## 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 pedidos > Como fazer o polling de eventos, drenar a fila e filtrar por tipo de evento, tipo de pedido e loja. Para receber pedidos novos, chame o endpoint de polling **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] > > Precisa de eventos em tempo real? Use o [webhook](/docs/guides/merchant/webhooks.md): a plataforma envia cada evento para a sua URL no momento em que ele acontece, sem fila para drenar, sem limite de 100 e sem intervalo de consulta. Uma integração robusta usa o webhook como canal principal e o polling como reconciliação. ## Requisição ```bash cURL theme={null} curl 'https://api.deliveryvip.com.br/merchant/v3/events:polling' \ --header 'Authorization: Bearer {token}' \ --header 'x-polling-merchants: {merchantId}' ``` ```js Node.js theme={null} const response = await fetch('https://api.deliveryvip.com.br/merchant/v3/events:polling', { 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", 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": "9a24ea9e-5743-4957-9b83-7a4b4f2a4597", "eventType": "CREATED", "orderId": "64939842-b9d7-44d1-a0fd-f68d18d410a6", "orderURL": "https://api.deliveryvip.com.br/merchant/v3/orders/64939842-b9d7-44d1-a0fd-f68d18d410a6", "orderType": "DELIVERY", "merchantId": "8158198a-4bb7-430e-9746-87cd02dfedda", "createdAt": "2022-08-16T16:01:21-03:00" } ] ``` ## A fila de eventos Eventos sem acknowledgment continuam voltando nas próximas chamadas até serem confirmados ou completarem 24 horas. O consumo é sempre o mesmo ciclo: **1. Polling** Chame o polling e processe os eventos recebidos. **2. Acknowledgment** Envie o [acknowledgment](/docs/guides/merchant/order/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. > [accordion] Por quanto tempo os eventos ficam disponíveis? > > O polling retorna eventos criados nas **últimas 24 horas**. Um evento sem acknowledgment que passe desse prazo deixa de ser retornado, então não deixe a fila acumular. > [accordion] Qual é o intervalo mínimo entre chamadas? > > Uma chamada a cada **30 segundos** por token. Acima disso a API responde `429` e pode bloquear o cliente temporariamente. A única exceção é drenar uma fila acumulada (lote com 100 eventos). ## Filtros Os filtros fazem o lote de 100 trazer só o que a sua integração usa. Eles podem ser combinados, e 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`). `CREATED`, `CONFIRMED`, `PREPARING`, `DISPATCHED`, `READY_FOR_PICKUP`, `PICKUP_AREA_ASSIGNED`, `PICKED_UP`, `DELIVERED`, `CONCLUDED`, `CANCELLATION_REQUESTED`, `CANCELLATION_REQUEST_DENIED`, `CANCELLED`, `ORDER_CANCELLATION_REQUEST`, `CALL_WAITER`, `CLOSE_ACCOUNT` ```text theme={null} /merchant/v3/events:polling?eventType=CREATED&eventType=CANCELLED ``` **orderType** `string[]` Tipos de pedido a receber: `DELIVERY`, `TAKEOUT` ou `INDOOR`. Também repetido uma vez por valor. ```text theme={null} /merchant/v3/events:polling?orderType=DELIVERY&orderType=TAKEOUT ``` **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. ```text theme={null} x-polling-merchants: 0a0000aa-0aa0-00aa-aa00-0000aa000001 x-polling-merchants: 0a0000aa-0aa0-00aa-aa00-0000aa000002 ``` > [!WARNING] > > Se o mesmo token tem acesso a mais de uma loja e o seu sistema trata cada loja separadamente, use `x-polling-merchants`. Sem ele, os eventos de todas as lojas chegam misturados no mesmo lote. > [accordion] Recebi 403 usando x-polling-merchants > > Com o header, a API confere se o token tem permissão em **todas** as lojas informadas. Se faltar permissão em alguma, a resposta é `403` e o corpo lista as lojas sem acesso. > > **Para continuar recebendo:** remova essas lojas do header e chame o polling de novo. As demais seguem funcionando. > > **Para achar a causa:** > > * A loja pode ter revogado o acesso do seu app. Fale com o responsável e peça para autorizar de novo. > * Confira se a instalação foi concluída na Delivery Store. O acesso do token é calculado a cada chamada: uma loja que acabou de instalar o app já vale para o token atual, sem gerar outro. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.