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

# Autenticação

> Como autenticar as chamadas da Merchant API V3 e quais scopes cada grupo de endpoints exige.

Todo endpoint da Merchant API V3 exige um token OAuth2 no header `Authorization`. O passo a passo para obter e renovar o token está em [Autenticação](/docs/inicio/conceitos/autenticacao.md).

| Endpoint | Para quê |
| - | - |
| `POST /authentication/v1/oauth/token` | Obter o token: `client_credentials` (distribuição direta), `authorization_code` (interativa) ou `refresh_token`. |
| `GET /authentication/v1/oauth/token/info` | Ver o app, os scopes e o tempo restante do token enviado. |
| `POST /authentication/v1/oauth/introspect` | Verificar se um token está ativo. |
| `POST /authentication/v1/oauth/revoke` | Revogar um token antes de expirar. |

Com o token em mãos, envie-o em toda chamada:

```bash cURL theme={null}
curl 'https://api.deliveryvip.com.br/merchant/v3/events:polling' \
  --header 'Authorization: Bearer {token}'
```

```js Node.js theme={null}
const response = await fetch('https://api.deliveryvip.com.br/merchant/v3/events:polling', {
  headers: { Authorization: `Bearer ${token}` },
})
```

```python Python theme={null}
response = requests.get(
    "https://api.deliveryvip.com.br/merchant/v3/events:polling",
    headers={"Authorization": f"Bearer {token}"},
)
```

| Endpoints | Scope exigido |
| - | - |
| Pedidos, eventos, catálogo, indoor, descontos e ferramentas | `od.all` |
| Configuração de fidelidade (`/loyalty/config`) | `dv.loyalty` |

| Status | Quando |
| - | - |
| `401 Unauthorized` | Token ausente, inválido ou expirado. |
| `403 Forbidden` | Token válido, mas sem o scope exigido pelo endpoint. |
| `404 Not Found` | A loja ou o recurso não existe, ou o token não tem acesso a essa loja. |


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