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

# Ações de pedidos

> Atualize o status do pedido do preparo à entrega, cancele e envie dados de rastreio.

Cada ação é um `POST` sem corpo em `/merchant/v3/orders/{orderId}/<ação>`, com exceção do cancelamento e do rastreio. Todas exigem o token no header `Authorization`.

| Ação | Endpoint | Quando usar |
| - | - | - |
| [Confirmar](#confirmar-um-pedido) | `confirm` | A loja aceitou o pedido. |
| [Preparando](#preparando-um-pedido) | `preparing` | A loja começou o preparo. Opcional. |
| [Pronto para retirada](#pronto-para-pegar-um-pedido) | `readyForPickup` | O pedido está pronto. **Obrigatório** em `TAKEOUT` e `INDOOR`. |
| [Retirado](#pedido-retirado-pelo-cliente) | `pickedUp` | O cliente retirou o pedido (`TAKEOUT`). |
| [Despachar](#despachar-um-pedido) | `dispatch` | O pedido saiu para entrega. **Obrigatório** em `DELIVERY`. |
| [Entregue](#pedido-entregue) | `delivered` | O pedido chegou ao cliente. Fecha o ciclo. |
| [Cancelar](#requisitar-cancelamento-de-um-pedido) | `requestCancellation` | A loja não vai atender o pedido. |
| [Rastreio](#tracking) | `tracking` | Informar entregador, veículo, ETA e localização. |

## Respostas

| Status | Quando |
| - | - |
| `202 Accepted` | A ação foi aceita. O corpo traz o `id` do pedido. |
| `422 Unprocessable Content` | O pedido não está num estado que aceita a ação, por exemplo despachar um pedido já cancelado. Veja o [ciclo de vida](/docs/guides/merchant/order/definicoes.md#ciclo-de-vida-do-pedido). |

```json 202 Accepted theme={null}
{ "id": "67983761-a469-422c-af8e-b168f1e5ce19" }
```

## Confirmar um pedido

Depois de buscar um pedido com evento `CREATED`, confirme-o quando a loja aceitar.

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

```js Node.js theme={null}
await fetch(`https://api.deliveryvip.com.br/merchant/v3/orders/${orderId}/confirm`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
})
```

```python Python theme={null}
requests.post(
    f"https://api.deliveryvip.com.br/merchant/v3/orders/{order_id}/confirm",
    headers={"Authorization": f"Bearer {token}"},
)
```

As demais ações sem corpo seguem exatamente o mesmo formato: troque `confirm` pelo endpoint da ação.

## Preparando um pedido

Depois de confirmar, sinalize que a loja começou a preparar o pedido.

```bash theme={null}
curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/orders/{orderId}/preparing' \
  --header 'Authorization: Bearer {token}'
```

## Pronto para pegar um pedido

O pedido está pronto para o cliente retirar ou para o entregador buscar. **Obrigatório** para pedidos `TAKEOUT` e `INDOOR`.

```bash theme={null}
curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/orders/{orderId}/readyForPickup' \
  --header 'Authorization: Bearer {token}'
```

## Pedido retirado pelo cliente

Em pedidos `TAKEOUT`, informe quando o cliente retirar o pedido no estabelecimento.

```bash theme={null}
curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/orders/{orderId}/pickedUp' \
  --header 'Authorization: Bearer {token}'
```

## Despachar um pedido

O pedido saiu para entrega. **Obrigatório** para pedidos `DELIVERY`.

```bash theme={null}
curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/orders/{orderId}/dispatch' \
  --header 'Authorization: Bearer {token}'
```

## Pedido entregue

O pedido chegou ao cliente. Use esta ação para fechar o ciclo de vida do pedido.

```bash theme={null}
curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/orders/{orderId}/delivered' \
  --header 'Authorization: Bearer {token}'
```

## Requisitar cancelamento de um pedido

Quando a loja não vai atender o pedido, por exemplo por falta de item ou fora da área de entrega. O pedido é **cancelado na hora** e gera o evento `CANCELLED`. A resposta é `200 OK` com o `id` do pedido.

**code** `string`

Motivo padronizado: `SYSTEMIC_ISSUES`, `DUPLICATE_APPLICATION`, `UNAVAILABLE_ITEM`, `RESTAURANT_WITHOUT_DELIVERY_MAN`, `OUTDATED_MENU`, `ORDER_OUTSIDE_THE_DELIVERY_AREA`, `BLOCKED_CUSTOMER`, `OUTSIDE_DELIVERY_HOURS`, `INTERNAL_DIFFICULTIES_OF_THE_RESTAURANT` ou `RISK_AREA`.

**reason** `string`

Descrição livre do motivo.

**mode** `string`

`AUTO` ou `MANUAL`.

**outOfStockItems** `string[]`

Itens em falta.

**invalidItems** `string[]`

Itens inválidos.

```bash theme={null}
curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/orders/{orderId}/requestCancellation' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "UNAVAILABLE_ITEM",
    "reason": "Produto esgotado",
    "mode": "MANUAL"
  }'
```

## Aceitar cancelamento de um pedido

`POST /merchant/v3/orders/{orderId}/acceptCancellation` e `POST /merchant/v3/orders/{orderId}/denyCancellation` existem por compatibilidade com a especificação Open Delivery e respondem `200 OK`. Hoje a DeliveryVip não emite pedidos de cancelamento para o seu sistema responder (veja os [eventos previstos na especificação](/docs/guides/merchant/order/fluxo-de-integracao/eventos-de-pedidos.md#previstos-na-especificação)), então você não precisa chamá-los.

## Tracking

Envie dados de rastreio da entrega: o último status, problemas, veículo, previsão de chegada, entregador e localização. No acompanhamento do pedido, o cliente vê o link de rastreio e o painel da loja mostra cada atualização em tempo real.

Os campos vão na raiz do corpo, como na especificação Open Delivery. Um corpo com campo desconhecido ou `type` fora da lista é recusado com `422`.

> [!NOTE]
>
> O formato antigo, com os campos dentro de `deliveryTrackingInfo`, continua aceito por compatibilidade. Prefira os campos na raiz.

**event** `object`

Último evento conhecido da entrega. Obrigatório quando não houver `problem`.

**propriedades**

**type** `string` *required*

`PICKUP_ONGOING`, `ARRIVED_AT_MERCHANT`, `ORDER_PICKED`, `DELIVERY_ONGOING`, `ARRIVED_AT_CUSTOMER`, `ORDER_DELIVERED` ou `CANCELLED`.

**message** `string`

Mensagem sobre o evento.

**datetime** `datetime` *required*

Data e hora do evento.

**problem** `object`

Último problema conhecido da entrega.

**propriedades**

**reason** `string` *required*

`DELIVERYPERSON_OCCURRENCE`, `PAYMENT_PROBLEMS`, `WRONG_PRODUCT_OR_ITEM`, `ORDER_DELAYED`, `ORDER_DAMAGED_OR_VIOLATED`, `CUSTOMER_DID_NOT_PLACE_ORDER`, `CUSTOMER_ADDRESS_UNKNOWN`, `ORDER_MISSING_ITEMS`, `NOBODY_TO_RECEIVE`, `DELIVERYPERSON_WAITING_PAYMENT_FOR_ALREADY_PAID_ORDER`, `ORDER_DELIVERED_WITHOUT_PAYMENT` ou `FRAUD_OR_THEFT`.

**message** `string`

Mensagem sobre o problema.

**datetime** `datetime` *required*

Data e hora do problema.

**vehicle** `object`

**propriedades**

**type** `string` *required*

`MOTORBIKE_BAG`, `MOTORBIKE_BOX`, `CAR`, `BICYCLE`, `SCOOTER` ou `VUC`.

**licencePlate** `string`

Placa do veículo.

**eta** `object`

**propriedades**

**pickupEtaInMinutes** `integer`

Minutos até buscar o pedido.

**pickupEtaDatetime** `datetime`

Data e hora previstas para buscar o pedido.

**deliveryEtaInMinutes** `integer`

Minutos até entregar o pedido.

**deliveryEtaDatetime** `datetime`

Data e hora previstas para a entrega.

**maxDeliveryTime** `datetime`

Prazo máximo da entrega.

**deliveryPerson** `object`

**propriedades**

**id** `uuid`

Identificação do entregador.

**name** `string`

Nome do entregador.

**pictureURL** `uri`

Foto do entregador.

**geoLocalization** `object`

Latitude, longitude e último endereço conhecido do entregador (`lastAddress`). Quando enviar `lastAddress`, inclua `distanceToPickup`, `distanceToDelivery` e `timestamp`.

**externalTrackingURL** `string`

Link de rastreio que o cliente vê no acompanhamento do pedido.

> [accordion] Exemplo completo
>
> ```bash theme={null}
> curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/orders/{orderId}/tracking' \
>   --header 'Authorization: Bearer {token}' \
>   --header 'Content-Type: application/json' \
>   --data '{
>   "event": {
>     "type": "DELIVERY_ONGOING",
>     "message": "Entregador a caminho",
>     "datetime": "2019-08-24T14:15:22Z"
>   },
>   "vehicle": {
>     "type": "MOTORBIKE_BAG",
>     "licencePlate": "ABC1D23"
>   },
>   "eta": {
>     "deliveryEtaInMinutes": 15,
>     "deliveryEtaDatetime": "2019-08-24T14:30:22Z"
>   },
>   "deliveryPerson": {
>     "name": "João",
>     "pictureURL": "https://exemplo.com/joao.png"
>   },
>   "geoLocalization": {
>     "latitude": -23.54809,
>     "longitude": -46.63638,
>     "lastAddress": {
>       "country": "BR",
>       "state": "BR-SP",
>       "city": "São Paulo",
>       "district": "Moema",
>       "street": "Plaza Avenue",
>       "postalCode": "20111-000",
>       "distanceToPickup": "1200",
>       "distanceToDelivery": "3400",
>       "timestamp": "2019-08-24T14:15:22Z"
>     }
>   },
>   "externalTrackingURL": "https://exemplo.com/rastreio/123"
> }'
> ```

![Status da entrega no painel](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/screenshot-2023-08-01-at-16.11.29.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=75e8b5dc9614d169d5ced9cc6b141028)

O status da entrega no painel da loja


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