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

# Jornada do Developer

> Da criação da conta até a primeira chamada à API, com o caminho certo para o seu tipo de integração.

Este guia leva você da conta recém-criada até a primeira chamada autenticada. Os passos de conta, app e token são os mesmos para qualquer integração; no fim, você escolhe o produto que vai integrar.

> [!WARNING]
>
> **Não existe sandbox self-service.** A DeliveryVip não tem um ambiente de testes separado: as chamadas vão para a API de produção. Para testar, peça uma **loja de teste** pelo [Discord](https://discord.gg/AJF8Yha4) e instale o seu app nela. Faça isso logo no início: sem uma loja com o app instalado, o token funciona mas não há dados para consultar.

![Fluxo da jornada: criar conta, criar app, obter token, primeira chamada e integrar com Merchant API, Open Delivery, Fidelidade ou Partner API](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/jornada-do-developer.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=3670f7f763e631fd8ae6f8f0bb376e8d)

Jornada do developer: conta, app, token, primeira chamada e o produto do seu caso de uso

## O caminho

**1. Crie sua conta**

Cadastre-se na [plataforma](https://developer.deliveryvip.com.br/users/sign_up) e, no [painel de developers](https://developer.deliveryvip.com.br), clique em **Criar nova conta de Desenvolvedor**. Se você já tem um usuário na DeliveryVip, entre com ele e pule o cadastro.

Detalhes em [Primeiros passos](/docs/inicio/primeiros-passos.md).

**2. Crie um app**

No painel, clique em **Novo Aplicativo**. O app é a identidade da sua integração: ele tem o `client_id`, o `client_secret` e as permissões (scopes) que as lojas vão autorizar.

Marque só as permissões que a sua integração usa:

| Permissão | Scope | Para quê |
| - | - | - |
| Merchant API | `od.all` | Pedidos, eventos, catálogo, indoor, descontos e tools. Também é o scope do Open Delivery. |
| Fidelidade | `dv.loyalty` | Configuração do programa de fidelidade da loja. Usado junto com `od.all`. |
| Partner API | `dv.partner` | Lojas, revendas, assinaturas, recursos e faturas de um parceiro. |
| Marketplace API | `dv.marketplace` | API de marketplace. |

**3. Escolha a distribuição**

A distribuição define como a loja autoriza o seu app e qual fluxo OAuth você usa para obter o token. A escolha é feita na criação do app.

> [card] [Distribuição direta](/docs/inicio/primeiros-passos/distribuicao-direta.md)
>
> A loja cola o **token de autorização** na Delivery Store e instala. Seu sistema pega o token via `client_credentials`. Ideal para PDVs e integrações de servidor.

> [card] [Distribuição interativa](/docs/inicio/primeiros-passos/distribuicao-interativa.md)
>
> A loja cola o **token de autorização** e é levada para o seu app, dentro do painel ou fora dele, onde autoriza o acesso. Token via `authorization_code`. Ideal para apps com tela própria.

> [!TIP]
>
> Na dúvida, comece pela **direta**: é o fluxo mais simples, e é o que os guias de pedidos, Open Delivery e fidelidade usam nos exemplos.

**4. Instale o app na loja de teste**

O token só alcança as lojas que autorizaram o seu app. Peça a loja de teste no [Discord](https://discord.gg/AJF8Yha4) e siga [Instalando o app na loja](/docs/inicio/primeiros-passos/instalando-app-na-loja.md). Ao final, guarde o `merchantId` da loja.

**5. Obtenha o token de acesso**

Troque as credenciais do app por um token. Na distribuição direta:

```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=od.all'
```

```js Node.js theme={null}
const response = 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: 'od.all',
  }),
})
const { access_token, expires_in } = await response.json()
```

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

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": "od.all",
    },
)
access_token = response.json()["access_token"]
```

```json Resposta (200) theme={null}
{
  "access_token": "{token}",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "od.all",
  "created_at": 1761750000
}
```

Peça em `scope` os scopes que o app tem, separados por espaço (`od.all dv.loyalty`). Sem `scope`, a API usa `od.all`. O token vale **24 horas**: guarde-o e reaproveite em todas as chamadas. Veja [Autenticação](/docs/inicio/conceitos/autenticacao.md) para renovação e erros.

**6. Faça a primeira chamada**

Confira o token em `GET /authentication/v1/oauth/token/info`. A chamada funciona com qualquer scope e mostra a qual app o token pertence e quanto tempo ainda resta.

```bash cURL theme={null}
curl 'https://api.deliveryvip.com.br/authentication/v1/oauth/token/info' \
  --header 'Authorization: Bearer {token}'
```

```js Node.js theme={null}
const response = await fetch('https://api.deliveryvip.com.br/authentication/v1/oauth/token/info', {
  headers: { Authorization: `Bearer ${token}` },
})
console.log(await response.json())
```

```python Python theme={null}
response = requests.get(
    "https://api.deliveryvip.com.br/authentication/v1/oauth/token/info",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json())
```

```json Resposta (200) theme={null}
{
  "resource_owner_id": null,
  "resource_owner_type": null,
  "scope": ["od.all"],
  "expires_in": 86321,
  "application": { "uid": "<clientId>" },
  "created_at": 1761750000
}
```

> [!TIP]
>
> Recebeu `200` com o `uid` do seu app? A autenticação está funcionando. Um `401` indica token ausente, expirado ou revogado.

## Escolha o seu caminho

Com o token em mãos, siga o guia do produto que você vai integrar.

> [card] [Merchant API](/docs/guides/merchant.md)
>
> PDV ou ERP: receba pedidos por webhook ou polling, sincronize o catálogo e gerencie comandas e descontos. Scope `od.all`. Comece por [Receba seu primeiro pedido](/docs/guides/merchant/order/fluxo-de-integracao/recepcao-de-pedidos.md).

> [card] [Open Delivery](/docs/guides/open-delivery.md)
>
> Seu PDV já fala Open Delivery. Host `od.deliveryvip.com.br`, um `client_secret` por loja. Scope `od.all`.

> [card] [Fidelidade](/docs/guides/merchant/loyalty.md)
>
> Programa de cashback ou CRM no checkout das lojas. Scopes `od.all` e `dv.loyalty`, mais a extensão de fidelidade no app.

> [card] [Partner API](/docs/guides/partner.md)
>
> Parceiro ou revenda: cadastre lojas e gerencie assinaturas, recursos e faturas. Scope `dv.partner`.

## Antes de escrever código

Estes conceitos valem para todas as APIs e evitam os erros mais comuns de integração.

> [card] [Autenticação](/docs/inicio/conceitos/autenticacao.md)
>
> Fluxos OAuth2, scopes, expiração e renovação.

> [card] [Erros](/docs/inicio/conceitos/erros.md)
>
> Formato do corpo de erro e o que fazer com cada status.

> [card] [Paginação](/docs/inicio/conceitos/paginacao.md)
>
> Cursores `next` e `previous`, `per_page` e header `Link`.

> [card] [Datas e horários](/docs/inicio/conceitos/datas-e-horarios.md)
>
> RFC 3339 com offset: UTC-3 na API própria, UTC no Open Delivery.

> [card] [Rate limiting](/docs/inicio/conceitos/rate-limiting.md)
>
> Limite de requisições e como reagir ao `429`.

> [card] [Postman](/docs/inicio/conceitos/postman.md)
>
> Importe as specs e explore a API sem escrever código.

## Suporte

> [card] [Discord](https://discord.gg/AJF8Yha4)
>
> Canal de desenvolvedores: dúvidas, loja de teste e acompanhamento da integração.

> [card] [Reunião com o time](https://calendar.app.google/EchaXk57y7xp8Hyx6)
>
> Agende uma conversa para revisar a sua integração.


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