> ## 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": ""}] (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. # Distribuição direta > Crie um app de distribuição direta, envie o token de autorização para a loja e obtenha o token de acesso via client credentials. Na distribuição direta, você envia um **token de autorização** para o lojista (ou parceiro), ele instala o seu app pela Delivery Store e, a partir daí, o seu sistema obtém o token de acesso com o fluxo OAuth2 **client credentials**. Um único token atende todas as lojas que instalaram o app. O app **não tem tela** para o lojista: ele conversa só com a API. É o caminho de PDVs, ERPs e integrações de servidor. Se o lojista vai usar uma interface do seu app, dentro ou fora do painel, veja a [distribuição interativa](/docs/inicio/primeiros-passos/distribuicao-interativa.md). ![Você cria o app e envia o token de autorização; o lojista instala e envia o merchantId; você obtém o token com client credentials](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/distribuicao-direta.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=c0c094805ac162ee265045908767a5ed) Distribuição direta ## Criando o app No painel de developers, clique em **Novo Aplicativo**, escolha **Distribuição direta** e preencha o formulário. ![Formulário de criação de app com distribuição direta](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/distribuicao-manual-formulario.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=408f753372941bb05545db0e8b3e6a64) Formulário de novo aplicativo com distribuição direta > [accordion] Dados básicos > > | Campo | Descrição | > | - | - | > | **Nome** | Nome do app, exibido para o lojista na instalação. | > | **Sobre** | Descrição breve do que o app faz. | > | **Logomarca** | PNG ou JPG com menos de 1 MB. Prefira imagem quadrada (1:1). | > [accordion] Dados do desenvolvedor > > | Campo | Descrição | > | - | - | > | **URL do site** | Site da sua empresa. | > | **URL de suporte** | Página de suporte do app. | > | **E-mail de contato** | Para a DeliveryVip falar com você sobre o app e a API. Também recebe o aviso de cada nova instalação. | > [accordion] Permissões > > Marque só as APIs que a integração usa. Elas viram os scopes que a loja autoriza na instalação. > > | Permissão | Scope | Acesso | > | - | - | - | > | Merchant API | `od.all` | Eventos, pedidos, catálogo, indoor, descontos e tools. | > | Fidelidade | `dv.loyalty` | Configuração do programa de fidelidade. Use junto com `od.all`. | > | Partner API | `dv.partner` | Lojas, revendas, assinaturas, recursos e faturas. | > | Marketplace API | `dv.marketplace` | API de marketplace. | ## Credenciais Ao salvar, o painel gera as credenciais. Abra o app para vê-las. ![Tela do app com token de autorização, Client ID e Client Secret](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/app-credenciais.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=e05a9012a84aba5ef883c0843228dd51) Token de autorização e credenciais do app | Credencial | Para quê | Quem vê | | - | - | - | | **Token de autorização** | O lojista cola esse valor na Delivery Store para encontrar e instalar o seu app. | Você envia para o lojista. | | **Client ID** | Identifica o seu app. | Só o seu sistema. | | **Client Secret** | Prova que a chamada vem do seu app ao pedir o token de acesso. | Só o seu sistema. | > [!CAUTION] > > Nunca exponha o **Client Secret** em código de front-end, app mobile, repositório ou mensagem. Se ele vazar, gere um novo no painel: o anterior deixa de funcionar. ## Instalando o app na loja Envie o **token de autorização** para o lojista. Ele instala o app pela Delivery Store e, ao final, envia o **`merchantId`** da loja, que você usa nas chamadas por loja (`/merchant/v3/{merchantId}/...`). > [card] [Instalando o app na loja](/docs/inicio/primeiros-passos/instalando-app-na-loja.md) > > O passo a passo que o lojista segue, com as telas. ## Obtendo o token de acesso Com o app instalado, peça o token com as credenciais do app. Envie em `scope` os scopes do app de que você precisa, separados por espaço; sem `scope`, a API usa `od.all`. ```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=' \ --data-urlencode 'client_secret=' \ --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 } ``` > [!NOTE] > > O token vale **24 horas** e **não vem com `refresh_token`**: o fluxo client credentials não usa refresh. Quando ele expirar, peça um novo da mesma forma. Detalhes em [Autenticação](/docs/inicio/conceitos/autenticacao.md). > [accordion] Recebi invalid\_scope > > O `scope` pedido inclui uma permissão que o app não tem. Peça só os scopes marcados no app, ou edite as permissões no painel. > [accordion] O token funciona, mas não vejo a loja > > O token só alcança lojas que **instalaram** o app. Confira com o lojista se a instalação foi concluída na Delivery Store. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.