Distribuição interativa

A instalação começa como na distribuição direta: 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 — 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 — Formulário de novo aplicativo com distribuição interativa

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

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://`.

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.

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.

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.

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 — Credenciais do app

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

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:

uuid

ID da loja (ou do parceiro, ou do marketplace) que está abrindo o app.

string

URL do painel daquela loja, codificada em Base64. É a base da tela de autorização.

0 | 1

1 quando o app abre incorporado ao painel.

string

URL do app dentro do painel, em Base64. Enviado na instalação.

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:

{site_url}/oauth/authorize?response_type=code&client_id=<clientId>&redirect_uri=<redirectUri>&scope=od.all&state=<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.

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.

Troque o code pelo token

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=<clientId>' \
  --data-urlencode 'client_secret=<clientSecret>' \
  --data-urlencode 'code=<authorizationCode>' \
  --data-urlencode 'redirect_uri=<redirectUri>'

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

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

Resposta (200)

{
  "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.

O token de acesso vale 24 horas. Para renovar sem pedir nova autorização ao lojista, use o refresh_token. Veja Autenticação.

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.

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.

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.

Início

Primeiros passos

Conceitos

Produção

Referência

Como funciona

Criando o app

Credenciais

Fluxo de autorização

​Como funciona

​Criando o app

​Credenciais

​Fluxo de autorização

Como funciona

Criando o app

Credenciais

Fluxo de autorização