Autenticação

Toda requisição precisa enviar três cabeçalhos:

Cabeçalho	Valor
`X-Api-Token`	A sua API key
`X-Api-Version`	`v1`, a versão atual
`User-Agent`	Um nome não vazio para a sua integração, como `minha-integracao/1.0`

Obtendo a sua API key

Gere a sua chave no painel, em API de Analytics. A chave identifica a sua empresa: cada consulta só enxerga os players e os dados dessa empresa.

Trate a chave como uma senha. Mantenha-a no seu servidor, leia-a de uma variável de ambiente e nunca a versione nem a envie para o navegador. Se ela vazar, gere uma nova no painel.

Testando as suas credenciais

O GET /quota/usage não recebe parâmetros, o que faz dele uma boa primeira chamada:

curl 'https://analytics.vturb.com/quota/usage' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: minha-integracao/1.0'

Um 200 significa que a chave funciona. O exemplo em JavaScript roda no Node.js 18 ou mais recente, no seu servidor.

Enviando uma consulta

As consultas são requisições POST com um corpo JSON, enviadas com os mesmos três cabeçalhos e o Content-Type:

curl -X POST 'https://analytics.vturb.com/conversions/active_platforms' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: minha-integracao/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "start_date": "2026-09-01 00:00:00",
    "timezone": "America/Sao_Paulo"
  }'

Erros de autenticação

Status	Resposta	Causa
`401`	`{"error":"missing token"}`	`X-Api-Token` ausente ou vazio
`401`	`{"error":"invalid credentials"}`	A chave não existe, ou a conta não pode usar a API
`401`	`{"error":"...","code":516}`	A empresa não tem acesso à API de Analytics
`401`	`{"error":"...","code":241}`	O plano da chave não permite esta consulta
`403`	Página HTML	`User-Agent` ausente ou vazio
`404`	`{"error_msg":"404 Route Not Found"}`	`X-Api-Version` ausente ou diferente de `v1`

O 403 e o 404 vêm da borda, antes de a requisição chegar à API, por isso os corpos deles não são erros JSON da API.

Boas práticas

Envie o mesmo User-Agent descritivo de todas as partes da sua integração; é assim que distinguimos o seu tráfego quando você pede suporte.
Tente de novo um 429 depois de resets_at, e um 503 depois de uma espera curta, com backoff exponencial. Não repita 400, 401, 403 ou 404: eles vão falhar do mesmo jeito até a requisição mudar.
Registre o status e o corpo das requisições que falharem. É isso que o suporte vai pedir.

Se ainda assim não conseguir se autenticar, fale com o nosso suporte em help.vturb.com.