Autenticação

Todas as APIs da DeliveryVip usam OAuth2. O seu app troca as credenciais por um token de acesso e envia esse token no header Authorization de cada chamada.

Endpoint	Para quê
`POST /authentication/v1/oauth/token`	Obter um token (`client_credentials`, `authorization_code` ou `refresh_token`).
`GET /authentication/v1/oauth/token/info`	Ver app, scopes e tempo restante do token atual.
`POST /authentication/v1/oauth/introspect`	Verificar se um token está ativo (RFC 7662).
`POST /authentication/v1/oauth/revoke`	Revogar um token antes de expirar (RFC 7009).

Todos ficam em https://api.deliveryvip.com.br. O endpoint de token só aceita Content-Type: application/x-www-form-urlencoded.

O Open Delivery tem endpoint de token próprio, em https://od.deliveryvip.com.br/oauth/token, com um client_secret por loja. Veja Primeiros passos do Open Delivery.

Obtendo o token

O fluxo depende do tipo de distribuição do app.

Client credentials (direta)
Authorization code (interativa)

Usado por apps de distribuição direta. Um token atende todas as lojas que instalaram o app.

string

obrigatório

client_credentials

string

obrigatório

Client ID do app.

string

obrigatório

Client Secret do app.

string

padrão:"od.all"

Scopes separados por espaço, entre os que o app tem.

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 token = await response.json()

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",
    },
)
token = response.json()

Tokens de client credentials não têm refresh_token. Quando expirarem, peça outro com as mesmas credenciais.

Usado por apps de distribuição interativa, depois que a loja aprova a tela de consentimento e você recebe o code na Redirect URI.

string

obrigatório

authorization_code

string

obrigatório

Client ID do app.

string

obrigatório

Client Secret do app.

string

obrigatório

O code recebido na Redirect URI. Uso único.

string

obrigatório

A mesma Redirect URI usada na autorização.

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 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"],
    },
)
token = response.json()

Resposta

200 OK

{
  "access_token": "{token}",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "{refreshToken}",
  "scope": "od.all",
  "created_at": 1761750000
}

string

O token para o header Authorization. É uma string opaca: não tente decodificá-la.

string

Sempre Bearer.

integer

Segundos até o token expirar. Um token novo vale 86400 (24 horas); um token reaproveitado volta com o tempo que ainda resta.

string

Só no fluxo authorization_code (e nas renovações dele). Ausente em client_credentials.

string

Scopes concedidos, separados por espaço.

integer

Emissão do token, em Unix timestamp (segundos).

Scopes

Scope	Acesso
`od.all`	Merchant API V3 (eventos, pedidos, catálogo, indoor, descontos, tools) e Open Delivery. É o scope padrão quando `scope` é omitido.
`dv.loyalty`	Configuração do programa de fidelidade (`/merchant/v3/{merchantId}/loyalty/config`). Peça junto com `od.all`.
`dv.partner`	Partner API V2: lojas, revendas, assinaturas, recursos e faturas.
`dv.marketplace`	API de marketplace.

Você só pode pedir scopes marcados nas permissões do app. Um token sem o scope que o endpoint exige recebe 403 Forbidden.

Usando o token

Envie o token no header Authorization em todas as chamadas:

curl 'https://api.deliveryvip.com.br/merchant/v3/{merchantId}/orders' \
  --header 'Authorization: Bearer {token}'

const response = await fetch(`https://api.deliveryvip.com.br/merchant/v3/${merchantId}/orders`, {
  headers: { Authorization: `Bearer ${token}` },
})

response = requests.get(
    f"https://api.deliveryvip.com.br/merchant/v3/{merchant_id}/orders",
    headers={"Authorization": f"Bearer {token}"},
)

Expiração e reaproveitamento

O token de acesso expira em 24 horas. Depois disso, as chamadas retornam 401 Unauthorized.

Guarde o token e reaproveite. Peça um token novo só quando ele estiver perto de expirar ou quando receber 401. Pedir um token por chamada é desnecessário e só gera carga.

Enquanto o token vigente tiver usado menos de 80% da validade (cerca de 19 horas), um novo pedido com as mesmas credenciais e scopes devolve o mesmo token, com o expires_in restante. Passado esse ponto, a API emite um token novo.

Renovando com refresh_token

Tokens do fluxo authorization_code vêm com refresh_token. Use-o para obter um novo token sem pedir nova autorização à loja:

curl --request POST 'https://api.deliveryvip.com.br/authentication/v1/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=<refreshToken>' \
  --data-urlencode 'client_id=<clientId>' \
  --data-urlencode 'client_secret=<clientSecret>'

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: 'refresh_token',
    refresh_token: refreshToken,
    client_id: process.env.DV_CLIENT_ID,
    client_secret: process.env.DV_CLIENT_SECRET,
  }),
})
const token = await response.json()

response = requests.post(
    "https://api.deliveryvip.com.br/authentication/v1/oauth/token",
    data={
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
        "client_id": os.environ["DV_CLIENT_ID"],
        "client_secret": os.environ["DV_CLIENT_SECRET"],
    },
)
token = response.json()

A resposta traz um access_token e um refresh_token novos. Substitua os dois no seu armazenamento.

Verificando o token

GET /authentication/v1/oauth/token/info descreve o token enviado no header. Útil como primeira chamada e para depurar 401 e 403.

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}` },
})
const info = await response.json()

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

200 OK

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

string[]

Scopes do token, como lista.

integer

Segundos restantes até expirar.

string

O Client ID do app dono do token.

string | null

Dono que autorizou o token no fluxo authorization_code, com o tipo em resource_owner_type. null em client_credentials.

Para checar um token sem usá-lo como Bearer, há também o introspect, que responde { "active": false } para tokens inválidos ou expirados.

Revogando o token

Revogue um token (de acesso ou de refresh) quando ele não for mais usado, por exemplo ao desconectar uma loja do seu sistema. A resposta é sempre 200, mesmo para tokens já inválidos.

curl --request POST 'https://api.deliveryvip.com.br/authentication/v1/oauth/revoke' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token={token}' \
  --data-urlencode 'client_id=<clientId>' \
  --data-urlencode 'client_secret=<clientSecret>'

await fetch('https://api.deliveryvip.com.br/authentication/v1/oauth/revoke', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    token,
    client_id: process.env.DV_CLIENT_ID,
    client_secret: process.env.DV_CLIENT_SECRET,
  }),
})

requests.post(
    "https://api.deliveryvip.com.br/authentication/v1/oauth/revoke",
    data={
        "token": token,
        "client_id": os.environ["DV_CLIENT_ID"],
        "client_secret": os.environ["DV_CLIENT_SECRET"],
    },
)

Erros de autenticação

Os erros do endpoint de token seguem o padrão OAuth2 (error e error_description), diferente do formato de erros das demais rotas.

401 Unauthorized

{
  "error": "invalid_client",
  "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."
}

Status	`error`	Causa e solução
`400`	`invalid_scope`	Pediu um scope que o app não tem. Ajuste `scope` ou as permissões do app.
`400`	`invalid_grant`	`code` ou `refresh_token` inválido, expirado ou já usado, ou `redirect_uri` diferente. Refaça a autorização.
`400`	`unsupported_grant_type`	`grant_type` diferente de `client_credentials`, `authorization_code` ou `refresh_token`.
`401`	`invalid_client`	`client_id` ou `client_secret` errado. Confira as credenciais no painel.

Nas demais rotas:

Status	Quando	O que fazer
`401`	Token ausente, expirado ou revogado.	Peça um novo token (ou renove com `refresh_token`) e repita a chamada uma vez.
`403`	Token válido sem o scope que a rota exige. A resposta vem sem corpo.	Peça o token com o scope certo; se o app não tiver a permissão, ajuste-a no painel.

401 Unauthorized

{ "title": "Unauthorized", "status": 401 }

Início

Primeiros passos

Conceitos

Produção

Referência

Obtendo o token

Resposta

Scopes

Usando o token

Expiração e reaproveitamento

Renovando com refresh_token

Verificando o token

Revogando o token

Erros de autenticação

​Obtendo o token

​Resposta

​Scopes

​Usando o token

​Expiração e reaproveitamento

​Renovando com refresh_token

​Verificando o token

​Revogando o token

​Erros de autenticação

Obtendo o token

Resposta

Scopes

Usando o token

Expiração e reaproveitamento

Renovando com refresh_token

Verificando o token

Revogando o token

Erros de autenticação