Como Integrar uma API de Voos em Seu Projeto em 5 Minutos

Você precisa adicionar busca de passagens aéreas no seu app ou site? Neste tutorial, vou mostrar como fazer isso de forma simples e rápida usando uma API moderna de voos.

O Que Você Vai Aprender

• ✅ Como fazer sua primeira requisição de busca de voos
• ✅ Estrutura de dados e parâmetros principais
• ✅ Tratamento de erros e boas práticas
• ✅ Exemplos em Node.js, Python e PHP
• ✅ Como exibir resultados no frontend

Tempo estimado: 15 minutos do início ao fim.

Por Que Usar uma API de Voos?

Construir integração direta com companhias aéreas é complexo e caro:

❌ Sem API:

• Negociar com cada companhia aérea separadamente
• Implementar múltiplos protocolos (GDS, NDC, APIs proprietárias)
• Manter integrações quando protocolos mudam
• Gerenciar credenciais e certificações
• Custo total: R$ 50.000+ e 6+ meses de desenvolvimento

✅ Com API de Voos:

• Uma única integração REST
• Acesso a múltiplas companhias aéreas
• Documentação clara e atualizada
• Setup em minutos
• Custo: R$ 0,25 por requisição + 50 grátis/mês

Passo 1: Obtenha Sua Chave de API

Antes de começar, vale saber que você pode testar gratuitamente! Veja quanto custa usar uma API de voos e descubra que é possível começar com R$ 0.

Cadastro Gratuito

1. Acesse app.apidevoos.dev/login
2. Crie sua conta (apenas email e senha)
3. Sua chave de API é gerada instantaneamente

API_KEY: voos_test_abc123xyz456

💡 Dica: Use a chave voos_test_ para desenvolvimento (modo sandbox) e voos_live_ para produção.

Passo 2: Primeira Requisição

Vamos buscar voos de São Paulo (GRU) para Rio de Janeiro (GIG):

cURL (teste rápido no terminal)

curl -X POST https://api.api-de-voos.com/v1/search \
  -H "Authorization: Bearer voos_test_abc123xyz456" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "GRU",
    "destination": "GIG",
    "departure": "2026-03-15",
    "adults": 1
  }'

Node.js / JavaScript

const axios = require('axios');

async function searchFlights() {
  try {
    const response = await axios.post(
      'https://api.api-de-voos.com/v1/search',
      {
        origin: 'GRU',
        destination: 'GIG',
        departure: '2026-03-15',
        adults: 1
      },
      {
        headers: {
          'Authorization': 'Bearer voos_test_abc123xyz456',
          'Content-Type': 'application/json'
        }
      }
    );

    console.log(`Encontrados ${response.data.flights.length} voos`);
    
    // Exibe os 3 primeiros resultados
    response.data.flights.slice(0, 3).forEach(flight => {
      console.log(`${flight.airline} - R$ ${flight.price.amount}`);
    });
    
    return response.data;
    
  } catch (error) {
    console.error('Erro na busca:', error.response?.data || error.message);
  }
}

searchFlights();

Python

import requests
import json

def search_flights():
    url = "https://api.api-de-voos.com/v1/search"
    
    headers = {
        "Authorization": "Bearer voos_test_abc123xyz456",
        "Content-Type": "application/json"
    }
    
    payload = {
        "origin": "GRU",
        "destination": "GIG",
        "departure": "2026-03-15",
        "adults": 1
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        
        data = response.json()
        
        print(f"Encontrados {len(data['flights'])} voos")
        
        # Exibe os 3 primeiros resultados
        for flight in data['flights'][:3]:
            print(f"{flight['airline']} - R$ {flight['price']['amount']}")
        
        return data
        
    except requests.exceptions.RequestException as e:
        print(f"Erro na busca: {e}")
        return None

search_flights()

PHP

<?php

function searchFlights() {
    $url = 'https://api.api-de-voos.com/v1/search';
    
    $data = [
        'origin' => 'GRU',
        'destination' => 'GIG',
        'departure' => '2026-03-15',
        'adults' => 1
    ];
    
    $options = [
        'http' => [
            'method' => 'POST',
            'header' => [
                'Authorization: Bearer voos_test_abc123xyz456',
                'Content-Type: application/json'
            ],
            'content' => json_encode($data)
        ]
    ];
    
    $context = stream_context_create($options);
    $response = file_get_contents($url, false, $context);
    
    if ($response === false) {
        echo "Erro na requisição";
        return null;
    }
    
    $result = json_decode($response, true);
    
    echo "Encontrados " . count($result['flights']) . " voos\n";
    
    // Exibe os 3 primeiros resultados
    foreach (array_slice($result['flights'], 0, 3) as $flight) {
        echo $flight['airline'] . " - R$ " . $flight['price']['amount'] . "\n";
    }
    
    return $result;
}

searchFlights();

Passo 3: Entendendo a Resposta

Estrutura JSON Retornada

{
  "success": true,
  "request_id": "req_abc123xyz",
  "search_key": "search_xyz789",
  "flights": [
    {
      "id": "flight_001",
      "type": "conventional",
      "airline": "LATAM",
      "airline_code": "LA",
      "price": {
        "amount": 450.00,
        "currency": "BRL",
        "formatted": "R$ 450,00"
      },
      "departure": {
        "airport": "GRU",
        "airport_name": "Guarulhos",
        "city": "São Paulo",
        "time": "2026-03-15T08:30:00-03:00",
        "terminal": "2"
      },
      "arrival": {
        "airport": "GIG",
        "airport_name": "Galeão",
        "city": "Rio de Janeiro",
        "time": "2026-03-15T09:45:00-03:00",
        "terminal": "2"
      },
      "duration": 75,
      "stops": 0,
      "aircraft": "Airbus A320",
      "baggage": {
        "checked": "23kg",
        "cabin": "10kg"
      },
      "fare_class": "Economy",
      "available_seats": 8,
      "refundable": false
    }
  ],
  "meta": {
    "total_results": 24,
    "search_time_ms": 847,
    "cached": false
  }
}

Campos Principais

Passo 4: Parâmetros Avançados

Busca Completa com Filtros

const searchParams = {
  // Obrigatórios
  origin: 'GRU',
  destination: 'GIG',
  departure: '2026-03-15',
  
  // Opcionais - Passageiros
  adults: 2,
  children: 1,
  infants: 0,
  
  // Opcionais - Viagem
  return: '2026-03-22',  // Data de volta (ida e volta)
  cabin_class: 'economy', // economy, premium_economy, business, first
  
  // Opcionais - Filtros
  max_stops: 0,           // Apenas voos diretos
  airlines: ['LA', 'G3'], // Apenas LATAM e Gol
  max_duration: 120,      // Máximo 2 horas
  max_price: 500,         // Máximo R$ 500
  
  // Opcionais - Resultados
  sort_by: 'price',       // price, duration, departure_time
  limit: 20,              // Número máximo de resultados
  
  // Opcionais - Features
  include_miles: true,    // Incluir opções com milhas
  flexible_dates: false   // Buscar +/- 3 dias
};

Busca com Milhas

A API de Voos é a única do mercado com busca de milhas integrada nativamente. Para entender todos os detalhes e recursos avançados, veja nosso guia completo de API de Voos com Milhas.

// Buscar APENAS voos com milhas
const milesSearch = {
  origin: 'GRU',
  destination: 'JFK',
  departure: '2026-06-10',
  adults: 1,
  only_miles: true,        // Apenas milhas
  miles_programs: ['smiles', 'latampass', 'tudo_azul']
};

Passo 5: Tratamento de Erros

Códigos de Erro Comuns

async function searchWithErrorHandling() {
  try {
    const response = await axios.post(url, params, { headers });
    return response.data;
    
  } catch (error) {
    const status = error.response?.status;
    const data = error.response?.data;
    
    switch (status) {
      case 400:
        console.error('Parâmetros inválidos:', data.message);
        // Exemplo: "O parâmetro 'origin' é obrigatório"
        break;
        
      case 401:
        console.error('Chave de API inválida');
        // Verifique sua API key
        break;
        
      case 429:
        console.error('Limite de requisições atingido');
        // Aguarde ou adicione créditos
        break;
        
      case 500:
        console.error('Erro no servidor');
        // Tente novamente em alguns segundos
        break;
        
      default:
        console.error('Erro desconhecido:', error.message);
    }
    
    return null;
  }
}

Mensagens de Erro Amigáveis

A API retorna erros descritivos:

{
  "success": false,
  "error": {
    "code": "INVALID_AIRPORT",
    "message": "O código de aeroporto 'ABC' não é válido",
    "field": "origin",
    "suggestion": "Use códigos IATA de 3 letras (ex: GRU, GIG, JFK)",
    "docs": "https://docs.api-de-voos.com/reference/airports"
  }
}

Passo 6: Exibindo Resultados no Frontend

Exemplo React

import React, { useState } from 'react';

function FlightSearch() {
  const [flights, setFlights] = useState([]);
  const [loading, setLoading] = useState(false);
  
  const searchFlights = async (origin, destination, date) => {
    setLoading(true);
    
    try {
      const response = await fetch('https://api.api-de-voos.com/v1/search', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer voos_test_abc123xyz456',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ origin, destination, departure: date, adults: 1 })
      });
      
      const data = await response.json();
      setFlights(data.flights);
      
    } catch (error) {
      console.error('Erro:', error);
    } finally {
      setLoading(false);
    }
  };
  
  return (
    <div>
      {loading && <p>Buscando voos...</p>}
      
      {flights.map(flight => (
        <div key={flight.id} className="flight-card">
          <div className="airline">{flight.airline}</div>
          <div className="route">
            {flight.departure.time} → {flight.arrival.time}
          </div>
          <div className="price">R$ {flight.price.amount}</div>
          <button>Selecionar</button>
        </div>
      ))}
    </div>
  );
}

Boas Práticas

1. Cache Inteligente

// Cachear buscas idênticas por 5 minutos
const cache = new Map();

async function searchWithCache(params) {
  const cacheKey = JSON.stringify(params);
  
  if (cache.has(cacheKey)) {
    const cached = cache.get(cacheKey);
    if (Date.now() - cached.timestamp < 5 * 60 * 1000) {
      return cached.data;
    }
  }
  
  const data = await searchFlights(params);
  cache.set(cacheKey, { data, timestamp: Date.now() });
  
  return data;
}

2. Rate Limiting no Cliente

// Prevenir múltiplas requisições simultâneas
let searchPromise = null;

function debouncedSearch(params) {
  if (searchPromise) {
    return searchPromise;
  }
  
  searchPromise = searchFlights(params)
    .finally(() => {
      searchPromise = null;
    });
  
  return searchPromise;
}

3. Ambiente de Desenvolvimento

// .env
VOOS_API_KEY=voos_test_abc123xyz456
VOOS_API_URL=https://api.api-de-voos.com/v1

// .env.production
VOOS_API_KEY=voos_live_xyz789abc456
VOOS_API_URL=https://api.api-de-voos.com/v1

Próximos Passos

Agora que você domina a integração básica, explore mais:

• Construindo um produto? Veja 7 formas de monetizar com API de voos
• Comparando APIs? Confira nosso comparativo completo de APIs de voos 2026
• Montando uma startup? Leia o guia para MVPs de travel tech

Funcionalidades Avançadas

1. Reserva de Passagens

   • Endpoint POST /v1/bookings
   • Requer dados dos passageiros
   • Retorna bilhete confirmado

2. Alertas de Preço

   • Endpoint POST /v1/alerts
   • Receba webhook quando preço mudar
   • Configure thresholds personalizados

3. Detalhes do Voo

   • Endpoint GET /v1/flights/{id}
   • Regras tarifárias completas
   • Políticas de bagagem detalhadas

SDKs Oficiais

Facilite ainda mais com nossas bibliotecas:

# Node.js
npm install @api-de-voos/node

# Python
pip install api-de-voos

# PHP
composer require api-de-voos/php

Recursos Úteis

• 📚 Documentação Completa
• 🎮 Playground Interativo
• 📦 Postman Collection
• 💬 Comunidade no Discord
• 🎓 Tutoriais em Vídeo

Conclusão

Integrar busca de voos no seu projeto é mais simples do que você imagina:

1. ✅ Cadastro em 1 minuto
2. ✅ Primeira requisição em 5 minutos
3. ✅ Produção em 1 dia

A API de Voos foi construída pensando em desenvolvedores, com:

• 💰 Preço justo (R$ 0,25/req + 50 grátis/mês)
• 📖 Documentação clara e atualizada
• ⚡ Performance consistente (<1s de resposta)
• 🎯 Suporte técnico que entende de código

Comece grátis hoje: app.apidevoos.dev/login

Perguntas Frequentes

Preciso de cartão de crédito para testar? Não. As 50 requisições gratuitas mensais não exigem cartão.

A API funciona em produção no tier gratuito? Sim. O limite é apenas de volume (50 req/mês).

Como funciona o billing? Você adiciona créditos (mínimo R$ 50) e paga R$ 0,25 por requisição.

Existe limite de requisições por minuto? Tier gratuito: 10 req/min. Pago: 60 req/min. Enterprise: customizado.

A API retorna voos de quais companhias? Todas as principais: LATAM, Gol, Azul, Avianca, além de centenas de companhias internacionais.

Gostou do tutorial? Compartilhe com outros devs!

🐦 Twitter · 💼 LinkedIn · 📧 [Email](mailto:?subject=Tutorial API de Voos)