> ## 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 de pedidos

> A estrutura de um evento e todos os tipos que um pedido pode gerar.

Um evento é um aviso de que algo mudou num pedido. Ele não traz os dados do pedido: para isso, faça um `GET` na `orderURL`.

## Estrutura do evento

**eventId** `uuid` *required*

Identificador único do evento. Use-o para descartar eventos repetidos e no [acknowledgment](/docs/guides/merchant/order/fluxo-de-integracao/acknowledgment-de-eventos.md).

**eventType** `string` *required*

O que aconteceu. Veja os [tipos de evento](#tipos-de-evento).

**orderId** `uuid` *required*

O pedido ao qual o evento pertence.

**orderURL** `string` *required*

URL para buscar os detalhes do pedido.

**orderType** `string` *required*

`DELIVERY`, `TAKEOUT` ou `INDOOR`.

**merchantId** `uuid` *required*

A loja do pedido.

**createdAt** `datetime` *required*

Quando o evento foi criado.

**metadata** `object`

Dados extras de alguns eventos, como o motivo de um cancelamento. Só vem quando há conteúdo.

```json CREATED 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"
}
```

```json CANCELLED theme={null}
{
  "eventId": "1c2f6a4e-0d5b-4f7e-9a51-3b8e2f6c9d10",
  "eventType": "CANCELLED",
  "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:20:02-03:00",
  "metadata": {
    "reason": "Reason for the cancellation",
    "code": "CONSUMER_CANCELLATION_REQUESTED"
  }
}
```

## Tipos de evento

### Ciclo do pedido

| Evento | Significado |
| - | - |
| `CREATED` | Pedido criado. É o gatilho para buscar o pedido e confirmá-lo. |
| `CONFIRMED` | Pedido confirmado. |
| `PREPARING` | Pedido em preparo. |
| `READY_FOR_PICKUP` | Pedido pronto para retirada. |
| `PICKED_UP` | Pedido retirado. |
| `DISPATCHED` | Pedido despachado para entrega. |
| `DELIVERED` | Pedido entregue. |
| `CONCLUDED` | Pedido concluído. Fim do ciclo. |

### Cancelamento

| Evento | Significado |
| - | - |
| `CANCELLED` | Pedido cancelado, pela loja, pelo seu sistema ou pela plataforma. O motivo vem em `metadata.reason` e `metadata.code`. |

### Previstos na especificação

Estes tipos existem na especificação e são aceitos no filtro `eventType`, mas **a DeliveryVip ainda não os emite**. Trate-os como desconhecidos: confirme o recebimento e siga em frente.

| Evento | Significado na especificação |
| - | - |
| `PICKUP_AREA_ASSIGNED` | Área de retirada atribuída (`TAKEOUT` no modo `PICKUP_AREA`). |
| `CANCELLATION_REQUESTED` | Cancelamento solicitado pelo sistema do PDV. |
| `CANCELLATION_REQUEST_DENIED` | Solicitação de cancelamento negada. |
| `ORDER_CANCELLATION_REQUEST` | Cancelamento solicitado pela plataforma de pedidos. |

### Indoor

`CALL_WAITER` e `CLOSE_ACCOUNT` são eventos de comanda e mesa, não de pedido. Veja [eventos de indoor](/docs/guides/merchant/indoor/fluxo-de-integracao/eventos-de-indoor.md).

## Eventos repetidos

> [!WARNING]
>
> A API pode entregar o mesmo evento mais de uma vez. Trate a unicidade pelo `eventId`:
>
> 1. Antes de processar, verifique se aquele `eventId` já foi processado. Se foi, descarte.
> 2. **Mesmo assim, envie o acknowledgment dele.** Sempre confirme todos os eventos que recebeu, repetidos ou não.


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