Voos

Busque ofertas de voos em tempo real. A API Reservei oferece acesso a mais de 300 companhias aéreas com preços calculados automaticamente incluindo markup e taxas da sua agência.

Preços Calculados

Todos os preços retornados já incluem: tarifa base, taxas de embarque, markup configurado e taxa fixa da sua agência. O campo client_amount é o valor final em BRL para cobrar do cliente.

POST /api/v1/flights/search

Busca ofertas de voos disponíveis para o itinerário especificado.

Request

{
  "type": "round_trip",
  "slices": [
    {
      "origin": "GRU",
      "destination": "MIA",
      "departureDate": "2025-03-15"
    },
    {
      "origin": "MIA",
      "destination": "GRU",
      "departureDate": "2025-03-22"
    }
  ],
  "passengers": [
    { "type": "adult", "count": 2 },
    { "type": "child", "count": 1 },
    { "type": "infant_without_seat", "count": 1 }
  ],
  "cabinClass": "economy"
}

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`)

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 voo
child: 2-11 anos na data do voo
infant_without_seat: 0-1 ano (viaja no colo de um adulto)
Cada infant_without_seat precisa de um adult associado

Classes de Cabine

Valor	Descrição
`economy`	Classe Econômica
`premium_economy`	Econômica Premium
`business`	Classe Executiva
`first`	Primeira Classe

Response

{
  "id": "orq_0000AbCdEf123456",
  "offers": [
    {
      "id": "off_0000GhIjKl789012",
      "total_amount": "1250.50",
      "total_currency": "USD",
      "client_amount": "7825.60",
      "client_currency": "BRL",
      "original_amount": 1250.50,
      "original_currency": "USD",
      "exchange_rate_used": 5.46,
      "base_cost_brl": "6825.73",
      "agency_markup_percent": 12,
      "agency_markup_amount": "819.09",
      "agency_fee_amount": "50.00",
      "total_agency_commission": "869.09",
      "markup_applied": "819.09",
      "fee_applied": "50.00",
      "expires_at": "2025-01-15T16:30:00Z",
      "owner": {
        "iata_code": "LA",
        "name": "LATAM Airlines"
      },
      "slices": [
        {
          "id": "sli_0000MnOpQr345678",
          "origin": {
            "iata_code": "GRU",
            "name": "São Paulo-Guarulhos International Airport",
            "city_name": "São Paulo",
            "iata_city_code": "SAO",
            "time_zone": "America/Sao_Paulo"
          },
          "destination": {
            "iata_code": "MIA",
            "name": "Miami International Airport",
            "city_name": "Miami",
            "iata_city_code": "MIA",
            "time_zone": "America/New_York"
          },
          "duration": "PT9H30M",
          "segments": [
            {
              "id": "seg_0000StUvWx901234",
              "origin": {
                "iata_code": "GRU",
                "name": "São Paulo-Guarulhos International Airport",
                "terminal": "3"
              },
              "destination": {
                "iata_code": "MIA",
                "name": "Miami International Airport",
                "terminal": "J"
              },
              "departing_at": "2025-03-15T08:00:00",
              "arriving_at": "2025-03-15T16:30:00",
              "operating_carrier": {
                "iata_code": "LA",
                "name": "LATAM Airlines",
                "logo_symbol_url": "https://assets.reservei.co/airlines/LA.svg"
              },
              "marketing_carrier": {
                "iata_code": "LA",
                "name": "LATAM Airlines"
              },
              "operating_carrier_flight_number": "8084",
              "marketing_carrier_flight_number": "8084",
              "aircraft": {
                "iata_code": "789",
                "name": "Boeing 787-9"
              },
              "duration": "PT9H30M",
              "distance": "6912.00",
              "passengers": [
                {
                  "passenger_id": "pas_0000YzAbCd567890",
                  "cabin_class": "economy",
                  "cabin_class_marketing_name": "Economy",
                  "fare_basis_code": "YOWBR",
                  "baggages": [
                    {
                      "type": "checked",
                      "quantity": 1
                    },
                    {
                      "type": "carry_on",
                      "quantity": 1
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "passengers": [
        {
          "id": "pas_0000YzAbCd567890",
          "type": "adult",
          "fare_brand_name": "Light",
          "loyalty_programme_accounts": []
        }
      ],
      "conditions": {
        "refund_before_departure": {
          "allowed": false,
          "penalty_amount": null,
          "penalty_currency": null
        },
        "change_before_departure": {
          "allowed": true,
          "penalty_amount": "150.00",
          "penalty_currency": "USD"
        }
      },
      "payment_requirements": {
        "requires_instant_payment": false,
        "price_guarantee_expires_at": "2025-01-15T23:59:00Z",
        "payment_required_by": "2025-01-16T23:59:00Z"
      }
    }
  ],
  "slices": [...],
  "passengers": [...]
}

Campos da Resposta

Offer (Oferta)

Campo	Tipo	Descrição
`id`	string	ID único da oferta (usar para criar reserva)
`total_amount`	string	Valor original na moeda da companhia
`total_currency`	string	Moeda original (USD, EUR, BRL)
`client_amount`	string	Valor final em BRL para cobrar do cliente
`client_currency`	string	Sempre `BRL`
`exchange_rate_used`	number	Taxa de câmbio aplicada
`agency_markup_percent`	number	Markup configurado da sua agência
`agency_markup_amount`	string	Valor do markup em BRL
`agency_fee_amount`	string	Taxa fixa da agência em BRL
`total_agency_commission`	string	Total de comissão da agência
`expires_at`	string	Data/hora de expiração da oferta
`owner`	object	Companhia aérea principal
`slices`	array	Trechos da viagem
`passengers`	array	Passageiros com IDs (usar na reserva)
`conditions`	object	Condições de alteração e reembolso

Slice (Trecho)

Campo	Tipo	Descrição
`id`	string	ID único do slice
`origin`	object	Aeroporto de origem
`destination`	object	Aeroporto de destino
`duration`	string	Duração total (formato ISO 8601, ex: `PT9H30M`)
`segments`	array	Voos que compõem o trecho

Segment (Voo)

Campo	Tipo	Descrição
`id`	string	ID único do segmento
`operating_carrier`	object	Companhia que opera o voo
`marketing_carrier`	object	Companhia que vende o voo
`operating_carrier_flight_number`	string	Número do voo operado
`departing_at`	string	Data/hora de partida (local)
`arriving_at`	string	Data/hora de chegada (local)
`aircraft`	object	Tipo de aeronave
`duration`	string	Duração do voo
`passengers`	array	Detalhes por passageiro (bagagem, classe)

Baggage (Bagagem)

Campo	Tipo	Descrição
`type`	string	`checked` (despachada) ou `carry_on` (mão)
`quantity`	number	Quantidade incluída

Conditions (Condições)

Campo	Tipo	Descrição
`refund_before_departure.allowed`	boolean	Se reembolso é permitido
`refund_before_departure.penalty_amount`	string	Valor da multa para reembolso
`change_before_departure.allowed`	boolean	Se alteração é permitida
`change_before_departure.penalty_amount`	string	Valor da multa para alteração

Exemplos de Busca

{
  "type": "one_way",
  "slices": [
    {
      "origin": "GRU",
      "destination": "LIS",
      "departureDate": "2025-06-15"
    }
  ],
  "passengers": [
    { "type": "adult", "count": 1 }
  ],
  "cabinClass": "economy"
}

{
  "type": "round_trip",
  "slices": [
    {
      "origin": "GRU",
      "destination": "CDG",
      "departureDate": "2025-07-10"
    },
    {
      "origin": "CDG",
      "destination": "GRU",
      "departureDate": "2025-07-25"
    }
  ],
  "passengers": [
    { "type": "adult", "count": 2 }
  ],
  "cabinClass": "economy"
}

{
  "type": "multi_city",
  "slices": [
    {
      "origin": "GRU",
      "destination": "FCO",
      "departureDate": "2025-09-01"
    },
    {
      "origin": "FCO",
      "destination": "BCN",
      "departureDate": "2025-09-08"
    },
    {
      "origin": "BCN",
      "destination": "GRU",
      "departureDate": "2025-09-15"
    }
  ],
  "passengers": [
    { "type": "adult", "count": 2 }
  ],
  "cabinClass": "economy"
}

{
  "type": "round_trip",
  "slices": [
    {
      "origin": "GRU",
      "destination": "JFK",
      "departureDate": "2025-04-20"
    },
    {
      "origin": "JFK",
      "destination": "GRU",
      "departureDate": "2025-04-27"
    }
  ],
  "passengers": [
    { "type": "adult", "count": 1 }
  ],
  "cabinClass": "business"
}

Exemplos de Código

async function searchFlights(searchParams) {
  const response = await fetch('https://app.reservei.co/api/v1/flights/search', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.RESERVEI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(searchParams)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Erro na busca');
  }

  const data = await response.json();
  return data;
}

// Exemplo de uso
const result = await searchFlights({
  type: 'round_trip',
  slices: [
    { origin: 'GRU', destination: 'MIA', departureDate: '2025-03-15' },
    { origin: 'MIA', destination: 'GRU', departureDate: '2025-03-22' }
  ],
  passengers: [{ type: 'adult', count: 2 }],
  cabinClass: 'economy'
});

// Processar ofertas
result.offers.forEach(offer => {
  console.log(`${offer.owner.name}: R$ ${offer.client_amount}`);
  console.log(`  Duração: ${offer.slices[0].duration}`);
  console.log(`  Bagagem: ${offer.slices[0].segments[0].passengers[0].baggages[0].quantity} mala(s)`);
});

import requests
import os

def search_flights(search_params):
    response = requests.post(
        'https://app.reservei.co/api/v1/flights/search',
        headers={
            'Authorization': f'Bearer {os.environ["RESERVEI_API_KEY"]}',
            'Content-Type': 'application/json'
        },
        json=search_params
    )
    
    response.raise_for_status()
    return response.json()

# Exemplo de uso
result = search_flights({
    'type': 'round_trip',
    'slices': [
        {'origin': 'GRU', 'destination': 'MIA', 'departureDate': '2025-03-15'},
        {'origin': 'MIA', 'destination': 'GRU', 'departureDate': '2025-03-22'}
    ],
    'passengers': [{'type': 'adult', 'count': 2}],
    'cabinClass': 'economy'
})

# Processar ofertas
for offer in result['offers']:
    print(f"{offer['owner']['name']}: R$ {offer['client_amount']}")
    print(f"  Duração: {offer['slices'][0]['duration']}")

<?php

function searchFlights($searchParams) {
    $ch = curl_init();
    
    curl_setopt_array($ch, [
        CURLOPT_URL => 'https://app.reservei.co/api/v1/flights/search',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('RESERVEI_API_KEY'),
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode($searchParams)
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        throw new Exception('Erro na busca de voos');
    }
    
    return json_decode($response, true);
}

// Exemplo de uso
$result = searchFlights([
    'type' => 'round_trip',
    'slices' => [
        ['origin' => 'GRU', 'destination' => 'MIA', 'departureDate' => '2025-03-15'],
        ['origin' => 'MIA', 'destination' => 'GRU', 'departureDate' => '2025-03-22']
    ],
    'passengers' => [['type' => 'adult', 'count' => 2]],
    'cabinClass' => 'economy'
]);

// Processar ofertas
foreach ($result['offers'] as $offer) {
    echo "{$offer['owner']['name']}: R$ {$offer['client_amount']}\n";
}

Entendendo os Preços

A API calcula automaticamente os preços finais aplicando:

┌─────────────────────────────────────────────────────────────┐
│  Tarifa Base (USD/EUR)                                      │
│  Ex: $1,250.50                                              │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼ × Taxa de Câmbio (5.46)
┌─────────────────────────────────────────────────────────────┐
│  Custo Base em BRL                                          │
│  Ex: R$ 6,827.73                                            │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼ + Markup da Agência (12%)
┌─────────────────────────────────────────────────────────────┐
│  + Markup                                                   │
│  Ex: R$ 819.33                                              │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼ + Taxa Fixa
┌─────────────────────────────────────────────────────────────┐
│  + Taxa Fixa                                                │
│  Ex: R$ 50.00                                               │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  VALOR FINAL (client_amount)                                │
│  Ex: R$ 7,697.06                                            │
└─────────────────────────────────────────────────────────────┘

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 antes de nova requisição

Dicas de Performance

Seja específico: Use códigos de aeroporto quando possível (mais rápido que códigos de cidade)
Limite passageiros: Busque apenas os passageiros necessários
Cache local: Resultados podem ser cacheados por 5-10 minutos
Requisições paralelas: Evite múltiplas buscas simultâneas

As ofertas expiram rapidamente (15-30 minutos). Sempre busque novamente antes de criar uma reserva se muito tempo passou.

Voos

On this page