Referência

Documentação da API

Tudo o que você precisa para integrar: autenticação, endpoints de cada programa, cabeçalhos, saldo e erros.

Resposta rápida

A APIVOOS é uma API REST em HTTPS. Toda busca usa o método POST com corpo JSON no domínio busca.apivoos.com.br e o cabeçalho Authorization: Bearer com a sua chave, gerada no painel app.apivoos.com.br. As respostas são JSON com o campo ok, e todo retorno traz o cabeçalho X-Request-Id.

URL base e autenticação

URL base: https://busca.apivoos.com.br. Crie sua conta em app.apivoos.com.br, copie a chave no painel e envie no cabeçalho Authorization: Bearer SUA_CHAVE, com o corpo em application/json (máx. 100 KB).

Autenticação

curl -X POST https://busca.apivoos.com.br/v1/aa/availability \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"origin":"GRU","destination":"MIA","date":"2026-12-10","return_date":"2026-12-20"}'

Endpoints

Método	Rota	Programa	Parâmetros
POST	`/v1/smiles/availability`	Smiles	origin, destination, date, adults?, children?, infants?, upsell?
POST	`/v1/latam/search`	LATAM Pass	origin, destination, date, return_date?, adults?, children?, infants?
POST	`/v1/azul-fidelidade/search`	Azul Fidelidade	origin, destination, date, return_date?, adults?, children?, infants?
POST	`/v1/azul/availability`	Azul pelo Mundo	origin, destination, date, return_date?, adults?
POST	`/v1/aa/availability`	American Airlines	origin, destination, date, return_date?, adults?, children?
POST	`/v1/aa/calendar`	American Airlines	origin, destination, from, to (até 120 dias)
GET	`/v1/status`	Todos	Situação de cada programa (online/offline)
GET	`/health`	Todos	Saúde do serviço (sem autenticação)

Datas em AAAA-MM-DD e aeroportos em código IATA de 3 letras. O campo ok indica sucesso; o formato de cada voo segue o programa consultado.

Saldo e cobrança

Cada busca bem-sucedida em um programa desconta 1 consulta (R$ 0,05). Se a companhia não responder, a consulta volta ao saldo. O cabeçalho X-Credits-Remaining traz o saldo após a busca; com saldo zerado a API responde 402 sem_saldo. Compre pacotes por Pix no painel.

Cabeçalhos de resposta

`X-Request-Id`	UUID único da requisição. Informe ao suporte em caso de dúvida.
`X-RateLimit-Limit`	Requisições por minuto permitidas para a sua chave.
`X-RateLimit-Remaining`	Quantas ainda restam na janela atual.
`X-Credits-Remaining`	Saldo de consultas após a busca.
`Retry-After`	Segundos para tentar de novo (apenas em 429).

Erros

Erros retornam {"ok": false, "error": "codigo", "request_id": "..."}.

HTTP	error	Significado
400	`json_invalido`	Corpo da requisição não é um JSON válido
401	`nao_autorizado`	Chave ausente ou inválida
402	`sem_saldo`	Saldo de consultas zerado — compre um pacote no painel
403	`provedor_nao_liberado`	O programa não está liberado para a sua chave
403	`portal_desativado / ip_bloqueado`	Chave desativada ou IP bloqueado
404	`rota_inexistente`	Endpoint ou ação inexistente
429	`rate_limit_portal / rate_limit_ip`	Limite por minuto atingido — respeite Retry-After
502 / 504	`—`	A companhia não respondeu; tente novamente (não é cobrado)

Boas práticas

Use timeout de pelo menos 60 segundos no cliente HTTP: buscas com parceiras e muitas conexões podem levar mais que a média.
Dispare os programas em paralelo e mostre os resultados conforme chegam.
Guarde o X-Request-Id nos seus logs.
Em 429, aguarde o Retry-After antes de repetir.

Guias por programa

API Smiles GOL e parceiras API LATAM Pass LATAM nacional e internacional API Azul Fidelidade Voos Azul com pontos API Azul pelo Mundo Companhias parceiras API American Airlines AAdvantage + calendário