> ## 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. # Primeiros passos > Crie o app com o scope dv.loyalty, declare a extensão de fidelidade e obtenha o token com os dois scopes necessários. Ao final desta página você tem um app operador de fidelidade instalado em uma loja e um token capaz de ativar o programa e ler os pedidos. São quatro passos, metade no painel e metade na API. **1. Crie o app com os scopes dv.loyalty e od.all** Crie sua aplicação no [painel do desenvolvedor](/docs/inicio/primeiros-passos.md) normalmente. Um app operador de fidelidade precisa de **dois scopes**: | Scope | Para quê | | - | - | | `dv.loyalty` | Os endpoints de configuração de fidelidade (`PUT`/`DELETE /merchant/v3/{merchantId}/loyalty/config`). | | `od.all` | Ler os pedidos (`GET /merchant/v3/orders/{orderId}`). É assim que o [acúmulo](/docs/guides/merchant/loyalty/acumulo.md) funciona, já que o bloco `loyalty` vive no pedido. | Guarde o `client_id` e o `client_secret`. O secret também é a chave que a DeliveryVip usa para [assinar as chamadas do contrato](/docs/guides/merchant/loyalty/contrato-do-operador.md#autenticação-das-chamadas). **2. Declare a extensão de fidelidade** Na seção **Extensões** do app, declare a extensão **loyalty** informando a **`api_base_url`**: a base HTTPS onde o seu sistema implementa o [contrato do operador](/docs/guides/merchant/loyalty/contrato-do-operador.md). A URL pode incluir um prefixo de caminho (ex.: `https://operador.example.com/dv`); a DeliveryVip acrescenta `/v1/loyalty/...` a ela. > [!WARNING] > > A `api_base_url` deve ser **HTTPS**. `http://` é aceito apenas em loopback (`localhost`, `127.x.x.x`, `::1`), para desenvolvimento local. > [!CAUTION] > > **Remover a extensão do app cascateia**: apaga as configurações de programa de todas as lojas, os vínculos de clientes e o histórico de resgates. Isso é diferente do [`DELETE` da configuração de uma loja](/docs/guides/merchant/loyalty/ativando-o-programa#desativando-o-programa), que desativa o programa naquela loja **sem** tocar em vínculos nem histórico. **3. O lojista instala o app** O lojista instala o seu app pela **Delivery Store**, como qualquer outro app. Veja [Instalando o app na loja](/docs/inicio/primeiros-passos/instalando-app-na-loja.md). O grant é derivado no servidor (interseção dos scopes do app com os que o dono da loja pode conceder), e a página de consentimento destaca o item de **fidelidade/LGPD** para o lojista. **4. Obtenha o token com os dois scopes** Use o fluxo **client credentials** pedindo os dois scopes no mesmo token. O token vale **24 horas** e atende todas as lojas que instalaram o app. ```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=$DV_CLIENT_ID" \ --data-urlencode "client_secret=$DV_CLIENT_SECRET" \ --data-urlencode 'scope=od.all dv.loyalty' ``` ```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 dv.loyalty', }), }) const { access_token } = 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 dv.loyalty", }, ) access_token = response.json()["access_token"] ``` > [!NOTE] > > O parâmetro é `scope` (**singular**), com os valores **separados por espaço**. Um token só com `dv.loyalty` consegue configurar o programa, mas recebe `403` ao ler pedidos; um token só com `od.all` recebe `403` nos endpoints de configuração. Veja mais detalhes do fluxo OAuth em [Autenticação](/docs/inicio/conceitos/autenticacao.md). > [!TIP] > > Com o app instalado e o token em mãos, você já pode [ativar o programa da loja](/docs/guides/merchant/loyalty/ativando-o-programa.md). Antes, deixe a rota `GET /v1/loyalty/ping` do seu servidor respondendo `204` com a assinatura validada: o config push depende dela. ## Duas credenciais, dois sentidos | Sentido | Autenticação | Credencial | | - | - | - | | Você chama a DeliveryVip (config push, pedidos) | `Authorization: Bearer {token}` | Token OAuth obtido no passo 4. | | A DeliveryVip chama você (contrato) | `X-App-Signature` (HMAC-SHA256 do corpo) | O `client_secret` do app como chave. | > [!WARNING] > > Não assine o config push com HMAC nem espere um Bearer token nas rotas do contrato. Cada sentido usa só a sua autenticação. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.