> ## 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.

# Ciclo de vida do pedido

> Busque os detalhes do pedido pela orderURL e transicione o status do preparo à entrega, ou cancele.

O fluxo típico: você recebe um evento `CREATED` (via [webhook ou polling](/docs/guides/open-delivery/recebendo-eventos.md)), busca os detalhes do pedido pela `orderURL` do evento e vai transicionando o status conforme o pedido avança no seu PDV. Cada transição gera um evento, que chega pelo mesmo canal.

![Evento CREATED, busca do pedido, confirmação e as demais ações, cada uma respondida com 202 e o evento correspondente](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/od-ciclo-do-pedido.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=047295d22315b2f0ca78c0f3e87a5142)

O pedido do evento CREATED à entrega

## Obter detalhes do pedido

```bash cURL theme={null}
curl --request GET 'https://od.deliveryvip.com.br/v1/orders/{orderId}' \
  --header 'Authorization: Bearer {token}'
```

```js Node.js theme={null}
const response = await fetch(event.orderURL, {
  headers: { Authorization: `Bearer ${token}` },
})
const order = await response.json()
```

```python Python theme={null}
response = requests.get(event["orderURL"], headers={"Authorization": f"Bearer {token}"})
order = response.json()
```

O formato do objeto de pedido segue a spec **Order `1.3.0`** do [Open Delivery](https://www.opendelivery.com.br); consulte a spec oficial para o schema completo. As datas vêm em UTC.

> [!NOTE]
>
> Prefira usar a `orderURL` que chega no evento em vez de montar a URL manualmente. Pedidos ainda aguardando pagamento online (ou que expiraram sem pagamento) não são expostos: a API responde `404` para eles.

## Transicionar o status

As transições são feitas via `POST /v1/orders/{orderId}/{ação}`, sem corpo (exceto o rastreio):

```bash cURL theme={null}
curl --request POST 'https://od.deliveryvip.com.br/v1/orders/{orderId}/confirm' \
  --header 'Authorization: Bearer {token}'
```

```js Node.js theme={null}
const response = await fetch(`https://od.deliveryvip.com.br/v1/orders/${orderId}/confirm`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
})
console.log(response.status) // 202; 422 se o pedido não aceita a ação
```

```python Python theme={null}
response = requests.post(
    f"https://od.deliveryvip.com.br/v1/orders/{order_id}/confirm",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.status_code)  # 202; 422 se o pedido não aceita a ação
```

| Ação | Descrição | Resposta | Evento gerado |
| - | - | - | - |
| `confirm` | Confirma o pedido. | `202` | `CONFIRMED` |
| `preparing` | Pedido em preparo. | `202` | `PREPARING` |
| `readyForPickup` | Pedido pronto para retirada. | `202` | `READY_FOR_PICKUP` |
| `dispatch` | Pedido saiu para entrega. | `202` | `DISPATCHED` em pedidos de entrega; `CONCLUDED` nos demais |
| `pickedUp` | Pedido retirado. | `202` | `PICKED_UP` |
| `delivered` | Pedido entregue. | `202` | `DELIVERED` e `CONCLUDED` |
| `requestCancellation` | Cancela o pedido. | `200` | `CANCELLED` |
| `acceptCancellation` | Compatibilidade com a spec. | `200` | - |
| `denyCancellation` | Compatibilidade com a spec. | `200` | - |
| `tracking` | Envia dados de rastreio da entrega. | `202` | - |

As respostas de sucesso trazem o `id` do pedido: `{"id": "64939842-..."}`. Uma ação que o estado atual do pedido não aceita (por exemplo, despachar um pedido já cancelado) responde `422`.

## Fluxo de cancelamento

* **Você quer cancelar**: envie `requestCancellation`. O pedido é **cancelado na hora**, a resposta é `200` e o evento `CANCELLED` é emitido. Não há etapa de aprovação.
* **Cancelamento do lado da plataforma**: quando a loja ou a plataforma cancela, você recebe direto o evento `CANCELLED`.

> [!NOTE]
>
> `acceptCancellation` e `denyCancellation` existem por compatibilidade com a spec e respondem `200` sem alterar o pedido. Hoje a DeliveryVip não emite `ORDER_CANCELLATION_REQUEST`, então você não precisa chamá-los.

## Rastreio da entrega

O `tracking` recebe os dados de rastreio no formato da spec: último evento da entrega, problemas, veículo, previsão de chegada, entregador e localização. É o mesmo formato da API Merchant V3; veja os campos em [Tracking](/docs/guides/merchant/order/fluxo-de-integracao/acoes-de-pedidos.md#tracking). Um corpo fora do schema responde `422`.

## Eventos emitidos pela plataforma

Além dos eventos que refletem as suas ações, a plataforma emite eventos originados do lado dela, como `CREATED` (novo pedido), `CONCLUDED` e `CANCELLED`. A lista completa de tipos está em [Recebendo eventos](/docs/guides/open-delivery/recebendo-eventos.md#tipos-de-evento). Confirme cada um com o [acknowledgment](/docs/guides/open-delivery/recebendo-eventos.md#acknowledgment) se você também usa o polling.


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