Busca de Voos
Buscar voos em tempo real através da API
Busca de Voos
Busque voos em tempo real em múltiplos fornecedores. A API oferece dois modos de busca: REST (resposta única) e SSE (streaming em tempo real).
Dois Modos de Busca
Use REST (/search) para obter resultado completo de uma vez, ou SSE (/stream) para receber resultados progressivamente em tempo real.
POST /api/v1/flights/search
Busca voos com resposta única contendo todos os resultados.
Request
{
"type": "round_trip",
"slices": [
{
"origin": "GRU",
"destination": "MIA",
"departureDate": "2026-03-15"
},
{
"origin": "MIA",
"destination": "GRU",
"departureDate": "2026-03-22"
}
],
"passengers": [
{ "type": "adult", "count": 2 },
{ "type": "child", "count": 1 }
],
"cabinClass": "economy",
"maxConnections": 2,
"suppliers": ["latam", "gol", "azul"],
"enableDeduplication": true
}Parâmetros do Request
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string | Sim | Tipo de viagem: one_way, round_trip ou multi_city |
slices | array | Sim | Trechos da viagem (veja detalhes abaixo) |
passengers | array | Sim | Lista de passageiros por tipo |
cabinClass | string | Não | Classe da cabine (padrão: economy) |
maxConnections | number | Não | Máximo de conexões permitidas (padrão: sem limite) |
suppliers | array | Não | Lista de fornecedores específicos (opcional) |
enableDeduplication | boolean | Não | Remover voos duplicados (padrão: true) |
Objeto Slice
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
origin | string | Sim | Código IATA do aeroporto/cidade de origem (ex: GRU, SAO) |
destination | string | Sim | Código IATA do aeroporto/cidade de destino (ex: MIA, NYC) |
departureDate | string | Sim | Data de partida no formato YYYY-MM-DD |
Você pode usar códigos de aeroporto (ex: GRU, JFK) ou códigos de cidade (ex: SAO, NYC). Códigos de cidade retornam voos de todos os aeroportos da cidade.
Objeto Passenger
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string | Sim | Tipo: adult, child, infant_without_seat |
count | number | Sim | Quantidade de passageiros deste tipo |
Regras de Passageiros:
adult: 12+ anos na data do voochild: 2-11 anos na data do vooinfant_without_seat: 0-1 ano (viaja no colo de um adulto)
Classes de Cabine
| Valor | Descrição |
|---|---|
economy | Classe Econômica |
premium_economy | Econômica Premium |
business | Classe Executiva |
first | Primeira Classe |
Response
{
"success": true,
"requestId": "req_123abc",
"flightGroups": [
{
"id": "group_1",
"totalPrice": {
"amount": 2500.00,
"currency": "BRL"
},
"slices": [
{
"segments": [
{
"departureAirport": {
"iata": "GRU",
"name": "Aeroporto Internacional de São Paulo/Guarulhos",
"city": "São Paulo"
},
"arrivalAirport": {
"iata": "MIA",
"name": "Miami International Airport",
"city": "Miami"
},
"departureTime": "2026-03-15T08:00:00",
"arrivalTime": "2026-03-15T16:30:00",
"duration": "9h 30m",
"airline": {
"code": "LA",
"name": "LATAM Airlines"
},
"flightNumber": "LA8084",
"aircraft": "Boeing 787-9"
}
]
}
],
"offers": [
{
"provider": "latam",
"price": {
"amount": 2500.00,
"currency": "BRL"
},
"deepLink": "https://..."
}
]
}
],
"totalResults": 45,
"providers": [
{
"id": "latam",
"name": "LATAM",
"status": "completed",
"offersCount": 15
},
{
"id": "gol",
"name": "GOL",
"status": "completed",
"offersCount": 18
}
]
}Campos da Resposta
FlightGroup
| Campo | Tipo | Descrição |
|---|---|---|
id | string | ID único do grupo de voos |
totalPrice | object | Preço total (amount + currency) |
slices | array | Trechos da viagem com segmentos |
offers | array | Ofertas de diferentes fornecedores |
Segment
| Campo | Tipo | Descrição |
|---|---|---|
departureAirport | object | Aeroporto de partida (iata, name, city) |
arrivalAirport | object | Aeroporto de chegada (iata, name, city) |
departureTime | string | Data/hora de partida (ISO 8601) |
arrivalTime | string | Data/hora de chegada (ISO 8601) |
duration | string | Duração do voo |
airline | object | Companhia aérea (code, name) |
flightNumber | string | Número do voo |
aircraft | string | Tipo de aeronave |
POST /api/v1/flights/stream
Busca voos com streaming de resultados via Server-Sent Events (SSE).
Resultados em Tempo Real
Com SSE, você recebe os voos conforme são encontrados, sem aguardar a busca completa. Ideal para melhor UX.
Request
O request é idêntico ao endpoint /search.
Response (Server-Sent Events)
A resposta é um stream de eventos. Cada evento tem um tipo (event:) e dados (data:).
Evento: search-initialized
Enviado quando a busca inicia:
event: search-initialized
data: {"requestId":"req_123abc","providers":["latam","gol","azul"]}Evento: provider-progress
Enviado quando um fornecedor atualiza seu status:
event: provider-progress
data: {"provider":"latam","status":"searching","progress":50}Evento: flight-update
Enviado quando novos voos são encontrados:
event: flight-update
data: {
"newGroups": [
{
"id": "group_1",
"totalPrice": {"amount": 2500.00, "currency": "BRL"},
"slices": [...]
}
],
"updatedGroups": []
}Evento: search-complete
Enviado quando a busca termina:
event: search-complete
data: {
"requestId": "req_123abc",
"totalGroups": 45,
"totalOffers": 120,
"duration": "8.5s"
}Evento: search-error
Enviado em caso de erro:
event: search-error
data: {
"error": {
"code": "SEARCH_ERROR",
"message": "Failed to search flights",
"timestamp": "2026-01-10T12:00:00Z"
}
}Exemplo de Uso (JavaScript)
const response = await fetch('/api/v1/flights/stream', {
method: 'POST',
headers: {
'Authorization': 'Bearer sua_chave_aqui',
'Content-Type': 'application/json'
},
body: JSON.stringify({
type: 'round_trip',
slices: [
{ origin: 'GRU', destination: 'MIA', departureDate: '2026-03-15' },
{ origin: 'MIA', destination: 'GRU', departureDate: '2026-03-22' }
],
passengers: [{ type: 'adult', count: 1 }],
cabinClass: 'economy'
})
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const text = decoder.decode(value);
const lines = text.split('\n');
for (const line of lines) {
if (line.startsWith('event:')) {
const eventType = line.slice(7).trim();
} else if (line.startsWith('data:')) {
const data = JSON.parse(line.slice(6));
if (eventType === 'flight-update') {
console.log('Novos voos:', data.newGroups.length);
// Atualizar UI com novos voos
} else if (eventType === 'search-complete') {
console.log('Busca completa!');
break;
}
}
}
}Exemplos de Busca
{
"type": "one_way",
"slices": [
{
"origin": "GRU",
"destination": "LIS",
"departureDate": "2026-06-15"
}
],
"passengers": [
{ "type": "adult", "count": 1 }
],
"cabinClass": "economy"
}{
"type": "round_trip",
"slices": [
{
"origin": "GRU",
"destination": "CDG",
"departureDate": "2026-07-10"
},
{
"origin": "CDG",
"destination": "GRU",
"departureDate": "2026-07-25"
}
],
"passengers": [
{ "type": "adult", "count": 2 }
],
"cabinClass": "economy"
}{
"type": "multi_city",
"slices": [
{
"origin": "GRU",
"destination": "FCO",
"departureDate": "2026-09-01"
},
{
"origin": "FCO",
"destination": "BCN",
"departureDate": "2026-09-08"
},
{
"origin": "BCN",
"destination": "GRU",
"departureDate": "2026-09-15"
}
],
"passengers": [
{ "type": "adult", "count": 2 }
],
"cabinClass": "economy"
}{
"type": "round_trip",
"slices": [
{
"origin": "GRU",
"destination": "JFK",
"departureDate": "2026-04-20"
},
{
"origin": "JFK",
"destination": "GRU",
"departureDate": "2026-04-27"
}
],
"passengers": [
{ "type": "adult", "count": 1 }
],
"cabinClass": "business",
"maxConnections": 0,
"suppliers": ["latam", "united"],
"enableDeduplication": true
}Códigos IATA Comuns (Brasil)
| Código | Aeroporto/Cidade |
|---|---|
GRU | São Paulo - Guarulhos |
CGH | São Paulo - Congonhas |
SAO | São Paulo (todos aeroportos) |
GIG | Rio de Janeiro - Galeão |
SDU | Rio de Janeiro - Santos Dumont |
RIO | Rio de Janeiro (todos aeroportos) |
BSB | Brasília |
CNF | Belo Horizonte - Confins |
SSA | Salvador |
REC | Recife |
FOR | Fortaleza |
POA | Porto Alegre |
CWB | Curitiba |
FLN | Florianópolis |
Erros Comuns
| Código | Erro | Solução |
|---|---|---|
400 | Invalid request parameters | Verifique os campos obrigatórios |
400 | Invalid airport code | Use códigos IATA válidos |
400 | Invalid date format | Use formato YYYY-MM-DD |
400 | Departure date in the past | Data deve ser futura |
401 | Unauthorized | Verifique sua API key |
429 | Rate limit exceeded | Aguarde ou upgrade seu plano |
Dicas de Performance
- Use SSE para melhor UX: Exiba resultados progressivamente
- Cache local: Resultados podem ser cacheados por 5-10 minutos
- Limite fornecedores: Use
supplierspara buscar apenas em fornecedores específicos - Use códigos específicos: Aeroportos (GRU) são mais rápidos que cidades (SAO)
Os preços e disponibilidade são dinâmicos. Sempre revalide antes de processar uma reserva.