> ## 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 Partner API V2, o alcance do token e o header x-partners.

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

Peça o token com `client_credentials` e `scope=dv.partner`, depois que o parceiro ou a revenda autorizou o seu app, e envie-o em toda chamada:

```bash cURL theme={null}
curl --request POST 'https://api.deliveryvip.com.br/authentication/v1/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<clientId>' \
  --data-urlencode 'client_secret=<clientSecret>' \
  --data-urlencode 'scope=dv.partner'

curl 'https://api.deliveryvip.com.br/partner/v2/merchants' \
  --header 'Authorization: Bearer {token}'
```

```js Node.js theme={null}
const tokenResponse = await fetch('https://api.deliveryvip.com.br/authentication/v1/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.DV_CLIENT_ID,
    client_secret: process.env.DV_CLIENT_SECRET,
    scope: 'dv.partner',
  }),
})
const { access_token } = await tokenResponse.json()

const response = await fetch('https://api.deliveryvip.com.br/partner/v2/merchants', {
  headers: { Authorization: `Bearer ${access_token}` },
})
```

```python Python theme={null}
import os
import requests

token_response = requests.post(
    "https://api.deliveryvip.com.br/authentication/v1/oauth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["DV_CLIENT_ID"],
        "client_secret": os.environ["DV_CLIENT_SECRET"],
        "scope": "dv.partner",
    },
)
access_token = token_response.json()["access_token"]

response = requests.get(
    "https://api.deliveryvip.com.br/partner/v2/merchants",
    headers={"Authorization": f"Bearer {access_token}"},
)
```

## Alcance do token

O token enxerga os parceiros e as revendas que autorizaram o seu app, e tudo o que está abaixo deles.

| Quem autorizou | Lojas | Revendas | `partnerId` aceito nas rotas `/{partnerId}/...` |
| - | - | - | - |
| Parceiro | Todas, diretas e de revendas | Todas do parceiro | O do parceiro e o de qualquer revenda dele |
| Revenda | Só as da revenda | Nenhuma | Só o da revenda |

`POST /{partnerId}/resales` e `GET /{partnerId}/resales/invoices` são exclusivos de parceiro: com o ID de uma revenda, respondem `403`.

## Header x-partners

Nas rotas pelo recurso (`/merchants`, `/merchants/sales`, `/resales` e afins), o header `x-partners` restringe a resposta a parceiros ou revendas específicos. Aceita IDs separados por vírgula ou headers repetidos. Se algum ID estiver fora do alcance do token, a resposta é `403` com os IDs no `title`. Veja [Filtrar por Partners](/docs/guides/partner/merchant/utilizando-a-api/listar-merchants.md#filtrar-por-partners).

## Erros

Os erros seguem o formato `{"status": "<código>", "title": "<mensagem ou erros por campo>"}`.

| Status | Quando |
| - | - |
| `401 Unauthorized` | Token ausente, inválido ou expirado. |
| `403 Forbidden` | Token sem o scope `dv.partner`; `x-partners` ou `partnerId` fora do alcance; `subscriptionStatus` inválido; parceiro sem domínio de painel (membros, magic link e cadastro). |
| `404 Not Found` | Loja, revenda, membro, plano ou app inexistente ou fora do alcance do token. |
| `406 Not Acceptable` | Contratação ou cancelamento de recurso recusado. |
| `422 Unprocessable Content` | Dados inválidos ou transição de assinatura não permitida. |


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