Jornada do Developer

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.

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 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 — Jornada do developer: conta, app, token, primeira chamada e o produto do seu caso de uso

O caminho

Crie sua conta

Cadastre-se na plataforma e, no painel de developers, 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.

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.

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.

Distribuição direta

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.

Distribuição interativa

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.

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

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 e siga Instalando o app na loja. Ao final, guarde o merchantId da loja.

Obtenha o token de acesso

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

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'

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()

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"]

Resposta (200)

{
  "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 para renovação e erros.

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.

curl 'https://api.deliveryvip.com.br/authentication/v1/oauth/token/info' \
  --header 'Authorization: Bearer {token}'

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

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

Resposta (200)

{
  "resource_owner_id": null,
  "resource_owner_type": null,
  "scope": ["od.all"],
  "expires_in": 86321,
  "application": { "uid": "<clientId>" },
  "created_at": 1761750000
}

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.

Merchant API

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.

Open Delivery

Seu PDV já fala Open Delivery. Host od.deliveryvip.com.br, um client_secret por loja. Scope od.all.

Fidelidade

Programa de cashback ou CRM no checkout das lojas. Scopes od.all e dv.loyalty, mais a extensão de fidelidade no app.

Partner API

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.

Autenticação

Fluxos OAuth2, scopes, expiração e renovação.

Erros

Formato do corpo de erro e o que fazer com cada status.

Paginação

Cursores next e previous, per_page e header Link.

Datas e horários

RFC 3339 com offset: UTC-3 na API própria, UTC no Open Delivery.

Rate limiting

Limite de requisições e como reagir ao 429.

Postman

Importe as specs e explore a API sem escrever código.

Suporte

Discord

Canal de desenvolvedores: dúvidas, loja de teste e acompanhamento da integração.

Reunião com o time

Agende uma conversa para revisar a sua integração.

Início

Primeiros passos

Conceitos

Produção

Referência

O caminho

Distribuição direta

Distribuição interativa

Escolha o seu caminho

Merchant API

Open Delivery

Fidelidade

Partner API

Antes de escrever código

Autenticação

Erros

Paginação

Datas e horários

Rate limiting

Postman

Suporte

Discord

Reunião com o time

​O caminho

Distribuição direta

Distribuição interativa

​Escolha o seu caminho

Merchant API

Open Delivery

Fidelidade

Partner API

​Antes de escrever código

Autenticação

Erros

Paginação

Datas e horários

Rate limiting

Postman

​Suporte

Discord

Reunião com o time

O caminho

Escolha o seu caminho

Antes de escrever código

Suporte