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

# Referência rápida

> Endpoints, credenciais, limites e códigos de resposta da integração Open Delivery em uma página.

Host: `https://od.deliveryvip.com.br`

## Você chama: API OD da DeliveryVip

| Método | Endpoint | Descrição |
| - | - | - |
| `POST` | `/oauth/token` | Token OAuth2 (client credentials, scope `od.all`) com o `client_id` do app e o `client_secret` **da loja**. Fica na **raiz** do host, fora do `/v1`. |
| `GET` | `/v1/versions/orderingApp` | Versões das specs suportadas e métodos de eventos disponíveis. Público. |
| `GET` | `/v1/versions/merchant` | Versão do endpoint Merchant. Público. |
| `PUT` | `/v1/merchantOnboarding?merchantId={id}` | Registrar/substituir a configuração da loja: `ordersWebhookURL` e `getMerchantURL` (`baseURL`, `apiKey`). |
| `POST` | `/v1/merchantUpdate` | Corpo vazio: reimportar a loja. `merchantStatus`: abrir/fechar a loja, sem reimportar. |
| `GET` | `/v1/merchantStatus?merchantId={id}` | Resultado do último processamento: `lastRead`, `status` (`SUCCESS`/`PROCESSING`/`FAIL`) e `moreInfo`. |
| `GET` | `/v1/events:polling` | Eventos pendentes (últimas 24 h, máx. 100 por chamada, mais antigos primeiro). Filtros `eventType` e `orderType` repetidos na query. |
| `POST` | `/v1/events/acknowledgment` | Confirmar eventos processados (`202`, idempotente). |
| `GET` | `/v1/orders/{orderId}` | Detalhes de um pedido. |
| `POST` | `/v1/orders/{orderId}/{ação}` | Transicionar o status: `confirm`, `preparing`, `readyForPickup`, `pickedUp`, `dispatch`, `delivered`, `requestCancellation`, `acceptCancellation`, `denyCancellation`, `tracking`. |

## A DeliveryVip chama: seu sistema

| Método | URL | Descrição |
| - | - | - |
| `POST` | `ordersWebhookURL` da loja | Um evento por requisição, assinado em `X-App-Signature`. |
| `GET` | `getMerchantURL.baseURL` da loja | Snapshot da loja no formato da spec Merchant. Chamada **exatamente** nesta URL, com a `apiKey` no header `X-API-KEY`. |

## Versões das specs

| Spec | Versão |
| - | - |
| Order | `1.3.0` |
| Merchant | `1.0.0` |

Métodos de eventos: `WEBHOOK` e `POLLING`.

## Credenciais

| Credencial | Escopo |
| - | - |
| `client_id` | Do **app**: o mesmo para todas as lojas. |
| `client_secret` | Da **loja**: um por loja instalada, no formato `ods_<hint>_<random>`. Define qual loja o token enxerga. |
| Assinatura do webhook | `X-App-Signature` é HMAC-SHA256 hex do corpo bruto com o `client_secret` **da loja**. |
| `X-App-Id` do webhook | Fixo da plataforma: `019efa90-dcd1-7846-983d-6bab871b2f6b`. |

## Limites e janelas

| Item | Valor |
| - | - |
| Datas | **UTC** (RFC 3339, sufixo `Z`), conforme a spec OD, no polling e no webhook. |
| Polling | **100 eventos** por chamada; se vierem 100, confirme e consulte de novo imediatamente |
| Janela de eventos | **24 horas** |
| Token OAuth | Expira em **24 horas**; o token vigente é reutilizado até expirar |
| Webhook | Responder **2xx** em até 5 s (3 s para conectar) |
| Retentativas do webhook | Só para `408`, `429`, timeout e erro de conexão: **3 tentativas** no total. `5xx` não é retentado. |
| Suspensão do webhook | **Por loja**, após 10 falhas consecutivas (retentativas contam). Reativação: reenviar o onboarding, o formulário do painel ou o botão "Reativar envio de webhooks". |
| Importação do catálogo | Assíncrona; avisos em sequência agrupados em 10 s |

## Códigos de resposta comuns

| Código | Quando ocorre |
| - | - |
| `200` | `requestCancellation`, `acceptCancellation`, `denyCancellation`; `merchantStatus`. |
| `201` / `204` | `merchantOnboarding`: criação / atualização da configuração (com credencial por loja, espere `204`). |
| `202` | Transições de status, `tracking` e acknowledgment. |
| `204` | `events:polling` sem eventos pendentes; `merchantUpdate` aceito. |
| `400` | `merchantOnboarding` / `merchantStatus` sem `merchantId`, ou URL inválida no onboarding. |
| `401` | Token ausente, inválido ou expirado. |
| `403` | Token sem o scope `od.all`; ou valor inválido em filtro do polling. |
| `404` | Pedido inexistente ou ainda aguardando pagamento; `merchantStatus` de loja desconhecida, fora do alcance do token, ou sem processamento registrado. |
| `422` | Transição que o estado do pedido não aceita; `merchantUpdate` com corpo inválido ou loja sem `getMerchantURL`; `merchantOnboarding` sem a extensão Open Delivery (`open_delivery_extension_not_declared`). |


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