> ## 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 interativa > Crie um app com tela própria, que abre dentro ou fora do painel da loja e recebe a autorização pela Redirect URI. A instalação começa como na [distribuição direta](/docs/inicio/primeiros-passos/distribuicao-direta.md): o lojista (ou o parceiro, ou o marketplace) cola o **token de autorização** do seu app na Delivery Store. A diferença vem depois: * A loja é levada para a **URL do app**, que pode abrir **incorporada ao painel** da loja ou fora dele. * O acesso é liberado pelo OAuth2 **authorization code**: a loja aprova as permissões e o seu sistema recebe um `code` na **Redirect URI**, que troca por um token de acesso. ## Como funciona ![O lojista cola o token, é levado para o seu app, aprova as permissões e o seu app troca o code da Redirect URI pelo token](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/distribuicao-interativa.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=4ee7e5a94a5a62868603cbd964faefc3) Distribuição interativa ## Criando o app No painel de developers, clique em **Novo Aplicativo**, escolha **Distribuição interativa** e preencha o formulário. ![Formulário de criação de app com distribuição interativa](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/distribuicao-automatica-formulario.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=758f852e21c85b64a12c2d660d06e000) Formulário de novo aplicativo com distribuição interativa > [accordion] Dados básicos > > | Campo | Descrição | > | - | - | > | **Nome** | Nome do app, exibido para o lojista. | > | **Sobre** | Descrição breve do que o app faz. | > | **Logomarca** | PNG ou JPG com menos de 1 MB. Prefira imagem quadrada (1:1). | > [accordion] URLs > > | Campo | Descrição | > | - | - | > | **URL do app** | Para onde a Delivery Store leva o lojista ao abrir o seu app. Obrigatória na distribuição interativa. | > | **Redirect URI** | Para onde a DeliveryVip redireciona depois da autorização, com o `code` na query. Precisa usar `https://`. | > [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. | > [accordion] Permissões > > | 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. | > [accordion] Incorporação e visibilidade > > | Opção | Descrição | > | - | - | > | **Incorporar o app ao painel** | O app abre dentro do painel do lojista, em um iframe. | > | **Não incorporar** (padrão) | O app abre fora do painel, numa página própria. | > [!WARNING] > > Cadastre a **Redirect URI** antes de tornar o app público. Sem ela, o lojista autoriza mas o seu sistema nunca recebe o `code`. ## Credenciais Ao salvar, o painel gera o **token de autorização** (que você envia para a loja instalar, como na distribuição direta), o **Client ID** (identifica o app) e o **Client Secret** (prova que a chamada vem do seu app). Abra o app para vê-los. ![Tela do app com 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) Credenciais do app > [!CAUTION] > > Use o **Client Secret** só no seu servidor. Nunca o coloque no front-end, em app mobile ou no repositório. Se ele vazar, gere um novo no painel. ## Fluxo de autorização **1. A loja abre o seu app** Depois de colar o token de autorização na Delivery Store, o lojista é levado para a **URL do app**, incorporada ao painel ou não, com estes parâmetros na query: **merchant\_id** `uuid` ID da loja (ou do parceiro, ou do marketplace) que está abrindo o app. **site\_url** `string` URL do painel daquela loja, codificada em **Base64**. É a base da tela de autorização. **embedded** `0 | 1` `1` quando o app abre incorporado ao painel. **embedded\_url** `string` URL do app dentro do painel, em Base64. Enviado na instalação. **2. Redirecione para a tela de autorização** Decodifique o `site_url` e leve o lojista para `{site_url}/oauth/authorize` com os parâmetros OAuth2 padrão: ```text theme={null} {site_url}/oauth/authorize?response_type=code&client_id=&redirect_uri=&scope=od.all&state= ``` O `redirect_uri` precisa ser exatamente uma das Redirect URIs cadastradas no app. Use `state` para amarrar a volta à sessão que iniciou o fluxo. **3. Receba o code** Depois que o lojista aprova, a DeliveryVip redireciona para a sua Redirect URI com `code` (e o `state` que você enviou) na query. **4. Troque o code pelo token** ```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=authorization_code' \ --data-urlencode 'client_id=' \ --data-urlencode 'client_secret=' \ --data-urlencode 'code=' \ --data-urlencode 'redirect_uri=' ``` ```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: 'authorization_code', client_id: process.env.DV_CLIENT_ID, client_secret: process.env.DV_CLIENT_SECRET, code, redirect_uri: process.env.DV_REDIRECT_URI, }), }) const { access_token, refresh_token } = await response.json() ``` ```python Python theme={null} response = requests.post( "https://api.deliveryvip.com.br/authentication/v1/oauth/token", data={ "grant_type": "authorization_code", "client_id": os.environ["DV_CLIENT_ID"], "client_secret": os.environ["DV_CLIENT_SECRET"], "code": code, "redirect_uri": os.environ["DV_REDIRECT_URI"], }, ) tokens = response.json() ``` ```json Resposta (200) theme={null} { "access_token": "{token}", "token_type": "Bearer", "expires_in": 86400, "refresh_token": "{refreshToken}", "scope": "od.all", "created_at": 1761750000 } ``` O `code` é de uso único. Guarde o `access_token` e o `refresh_token` associados à loja que autorizou. > [!NOTE] > > O token de acesso vale **24 horas**. Para renovar sem pedir nova autorização ao lojista, use o `refresh_token`. Veja [Autenticação](/docs/inicio/conceitos/autenticacao.md#renovando-com-refresh_token). > [accordion] Recebi invalid\_grant > > O `code` já foi usado, expirou, ou o `redirect_uri` enviado na troca é diferente do usado na autorização. Reinicie o fluxo de autorização. > [accordion] A tela de autorização mostra erro de redirect\_uri > > O `redirect_uri` não bate exatamente com nenhuma Redirect URI cadastrada no app (protocolo, host, caminho e barra final contam). Corrija no painel ou na URL. > [accordion] Qual a diferença para a distribuição direta? > > Os dois tipos começam pelo token de autorização na Delivery Store. Na direta, a loja clica em **Instalar** e o seu sistema usa `client_credentials`, sem tela. Na interativa, a loja é levada para o seu app (dentro ou fora do painel) e o acesso vem pelo `authorization_code` na Redirect URI. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.