API de Voos
API

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

CampoTipoObrigatórioDescrição
typestringSimTipo de viagem: one_way, round_trip ou multi_city
slicesarraySimTrechos da viagem (veja detalhes abaixo)
passengersarraySimLista de passageiros por tipo
cabinClassstringNãoClasse da cabine (padrão: economy)
maxConnectionsnumberNãoMáximo de conexões permitidas (padrão: sem limite)
suppliersarrayNãoLista de fornecedores específicos (opcional)
enableDeduplicationbooleanNãoRemover voos duplicados (padrão: true)

Objeto Slice

CampoTipoObrigatórioDescrição
originstringSimCódigo IATA do aeroporto/cidade de origem (ex: GRU, SAO)
destinationstringSimCódigo IATA do aeroporto/cidade de destino (ex: MIA, NYC)
departureDatestringSimData 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

CampoTipoObrigatórioDescrição
typestringSimTipo: adult, child, infant_without_seat
countnumberSimQuantidade de passageiros deste tipo

Regras de Passageiros:

  • adult: 12+ anos na data do voo
  • child: 2-11 anos na data do voo
  • infant_without_seat: 0-1 ano (viaja no colo de um adulto)

Classes de Cabine

ValorDescrição
economyClasse Econômica
premium_economyEconômica Premium
businessClasse Executiva
firstPrimeira 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

CampoTipoDescrição
idstringID único do grupo de voos
totalPriceobjectPreço total (amount + currency)
slicesarrayTrechos da viagem com segmentos
offersarrayOfertas de diferentes fornecedores

Segment

CampoTipoDescrição
departureAirportobjectAeroporto de partida (iata, name, city)
arrivalAirportobjectAeroporto de chegada (iata, name, city)
departureTimestringData/hora de partida (ISO 8601)
arrivalTimestringData/hora de chegada (ISO 8601)
durationstringDuração do voo
airlineobjectCompanhia aérea (code, name)
flightNumberstringNúmero do voo
aircraftstringTipo 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ódigoAeroporto/Cidade
GRUSão Paulo - Guarulhos
CGHSão Paulo - Congonhas
SAOSão Paulo (todos aeroportos)
GIGRio de Janeiro - Galeão
SDURio de Janeiro - Santos Dumont
RIORio de Janeiro (todos aeroportos)
BSBBrasília
CNFBelo Horizonte - Confins
SSASalvador
RECRecife
FORFortaleza
POAPorto Alegre
CWBCuritiba
FLNFlorianópolis

Erros Comuns

CódigoErroSolução
400Invalid request parametersVerifique os campos obrigatórios
400Invalid airport codeUse códigos IATA válidos
400Invalid date formatUse formato YYYY-MM-DD
400Departure date in the pastData deve ser futura
401UnauthorizedVerifique sua API key
429Rate limit exceededAguarde ou upgrade seu plano

Dicas de Performance

  1. Use SSE para melhor UX: Exiba resultados progressivamente
  2. Cache local: Resultados podem ser cacheados por 5-10 minutos
  3. Limite fornecedores: Use suppliers para buscar apenas em fornecedores específicos
  4. 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.

On this page