Voos (Flights)

Busque passagens aéreas com preços e disponibilidade em tempo real, e crie reservas com pagamento integrado e confirmação automática no fornecedor (Rextur/CVC).

Fluxo Completo

Para realizar uma reserva de voo via API, siga este fluxo de 4 etapas:

Buscar aeroportos — Use o autocomplete para encontrar códigos IATA
Buscar voos — Pesquise voos disponíveis com origem, destino e datas
Pré-reservar (Prebook) — Trave a oferta selecionada por 20 minutos
Confirmar reserva (Book) — Envie passageiros e pagamento para criar a reserva e emitir o bilhete

GET  /api/public/airports/search   →  códigos IATA (público, sem auth)
POST /api/v1/flights/search        →  flightGroups[] com offers
POST /api/v1/flights/rate          →  breakdown de preço (opcional)
POST /api/v1/flights/prebook       →  prebook_token (20 min)
POST /api/v1/flights/book          →  booking + pagamento

Os rateToken retornados na busca têm validade limitada (tipicamente 15–30 minutos). Complete o fluxo de prebook e book dentro desse período para garantir preço e disponibilidade.

1. Buscar Aeroportos (Autocomplete)

GET /api/public/airports/search

Busca aeroportos por nome da cidade, nome do aeroporto ou código IATA. Este endpoint é público e não requer autenticação.

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`q`	string	Sim	Termo de busca (mínimo 2 caracteres). Ex: `sao paulo`, `GRU`, `rio`
`limit`	number	Não	Máximo de resultados (padrão: 10)

Exemplo de Requisição

curl -X GET "https://app.moblix.net/api/public/airports/search?q=sao+paulo&limit=5"

const response = await fetch(
  'https://app.moblix.net/api/public/airports/search?q=sao+paulo&limit=5'
);
const data = await response.json();
console.log(data.airports);

import requests

response = requests.get(
    'https://app.moblix.net/api/public/airports/search',
    params={'q': 'sao paulo', 'limit': 5}
)
print(response.json()['airports'])

Resposta

{
  "airports": [
    {
      "iata_code": "GRU",
      "name": "Aeroporto Internacional de Guarulhos",
      "city": "São Paulo",
      "state": "SP",
      "country_code": "BR",
      "is_international": true,
      "priority": 100
    }
  ]
}

2. Buscar Voos

POST /api/v1/flights/search

Realiza uma busca de voos em tempo real nos fornecedores integrados.

Autenticação obrigatória: Requer API key no header Authorization.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`origin`	string	Sim	Código IATA do aeroporto de origem (ex: `GRU`, `CGH`, `GIG`)
`destination`	string	Sim	Código IATA do aeroporto de destino
`departureDate`	string	Sim	Data de ida no formato `YYYY-MM-DD`
`returnDate`	string	Não	Data de volta (omita para só ida)
`adults`	number	Sim	Número de adultos (1–9)
`children`	number	Não	Crianças 2–11 anos (padrão: 0)
`infants`	number	Não	Bebês 0–2 anos (padrão: 0)
`cabinClass`	string	Não	`economy`, `premium_economy`, `business`, `first`
`directOnly`	boolean	Não	Apenas voos diretos (padrão: false)
`maxStops`	number	Não	Número máximo de escalas (0–3)
`provider`	string	Não	`rextur` (padrão, com emissão automática) ou `moblix` (emissão offline)

Exemplo de Requisição

curl -X POST https://app.moblix.net/api/v1/flights/search \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "GRU",
    "destination": "GIG",
    "departureDate": "2026-03-15",
    "returnDate": "2026-03-20",
    "adults": 2
  }'

const response = await fetch('https://app.moblix.net/api/v1/flights/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mbx_live_sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    origin: 'GRU',
    destination: 'GIG',
    departureDate: '2026-03-15',
    returnDate: '2026-03-20',
    adults: 2
  })
});
const data = await response.json();
console.log(data.data.flightGroups);

import requests

response = requests.post(
    'https://app.moblix.net/api/v1/flights/search',
    headers={'Authorization': 'Bearer mbx_live_sua_chave_aqui'},
    json={
        'origin': 'GRU',
        'destination': 'GIG',
        'departureDate': '2026-03-15',
        'returnDate': '2026-03-20',
        'adults': 2
    }
)
print(response.json()['data']['flightGroups'])

Resposta (resumida)

{
  "data": {
    "flightGroups": [
      {
        "id": "price-1250.00-abc...",
        "provider": "rextur",
        "offers": [
          {
            "id": "...",
            "rateToken": "PHJhdGU+PHB...",
            "price": {
              "total": 1250.00,
              "base": 980.00,
              "taxes": 270.00,
              "currency": "BRL",
              "commission": 50.00
            },
            "fareClass": "economy"
          }
        ],
        "flightInfo": {
          "itineraries": [
            {
              "segments": [
                {
                  "airline": { "code": "G3", "name": "GOL" },
                  "flightNumber": "1234",
                  "departure": { "airportCode": "GRU", "dateTime": "2026-03-15T08:00:00" },
                  "arrival": { "airportCode": "GIG", "dateTime": "2026-03-15T09:05:00" },
                  "duration": 65
                }
              ],
              "stops": 0
            }
          ]
        }
      }
    ]
  }
}

Guarde o rateToken da oferta escolhida — ele é obrigatório nas próximas etapas (rate, prebook e book).

3. Revalidar Preço (Rate) (opcional)

POST /api/v1/flights/rate

Decodifica o rateToken para retornar o breakdown de preço (tarifa base, comissão DU/RAV, taxas, total). Útil para mostrar ao cliente exatamente o que está pagando antes de confirmar.

Esta etapa é offline (não chama o fornecedor) — a disponibilidade final só é validada quando você chama /api/v1/flights/book. Se o rateToken expirou, refaça a busca.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`rateToken`	string	Sim	Token da oferta retornado pela busca
`currency`	string	Não	Código ISO da moeda (padrão: `BRL`)

Exemplo

curl -X POST https://app.moblix.net/api/v1/flights/rate \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "rateToken": "PHJhdGU+PHB..." }'

const response = await fetch('https://app.moblix.net/api/v1/flights/rate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mbx_live_sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ rateToken: 'PHJhdGU+PHB...' })
});
const data = await response.json();
console.log(data.data.pricing);

Resposta

{
  "data": {
    "rateToken": "PHJhdGU+PHB...",
    "pricing": {
      "total": 1250.00,
      "base_fare": 980.00,
      "du": 50.00,
      "taxes": 220.00,
      "fees": 0,
      "currency": "BRL"
    },
    "note": "Availability is finalized when /api/v1/flights/book is called. Rate tokens typically expire 15-30 minutes after search."
  }
}

4. Pré-reservar Voo (Prebook)

POST /api/v1/flights/prebook

Trava a oferta selecionada em um carrinho temporário e retorna um prebook_token válido por 20 minutos para uso no /api/v1/flights/book.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`rate_token`	string	Sim	Token da oferta retornado pela busca
`provider`	string	Não	`rextur` (padrão) ou `moblix`
`origin`	string	Sim	Código IATA da origem
`destination`	string	Sim	Código IATA do destino
`departure_date`	string	Sim	Data de ida (`YYYY-MM-DD`)
`return_date`	string	Não	Data de volta (`YYYY-MM-DD`)
`cabin_class`	string	Não	`economy`, `premium_economy`, `business`, `first`
`adults`	number	Sim	Adultos (1–9)
`children`	number	Não	Crianças 2–11 anos (padrão: 0)
`infants`	number	Não	Bebês 0–2 anos (padrão: 0)
`total_price`	number	Sim	Preço total da oferta (`offers[].price.total` da busca)
`currency`	string	Não	Padrão: `BRL`
`airline`	object	Não	`{ code, name }` para exibição
`segments`	array	Não	Detalhes dos segmentos para auditoria

Exemplo

curl -X POST https://app.moblix.net/api/v1/flights/prebook \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_token": "PHJhdGU+PHB...",
    "provider": "rextur",
    "origin": "GRU",
    "destination": "GIG",
    "departure_date": "2026-03-15",
    "return_date": "2026-03-20",
    "adults": 1,
    "total_price": 625.00,
    "currency": "BRL",
    "airline": { "code": "G3", "name": "GOL" }
  }'

const response = await fetch('https://app.moblix.net/api/v1/flights/prebook', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mbx_live_sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    rate_token: 'PHJhdGU+PHB...',
    provider: 'rextur',
    origin: 'GRU',
    destination: 'GIG',
    departure_date: '2026-03-15',
    return_date: '2026-03-20',
    adults: 1,
    total_price: 625.00,
    airline: { code: 'G3', name: 'GOL' }
  })
});
const data = await response.json();
console.log(data.data.prebook_token);

Resposta de Sucesso (201 Created)

{
  "data": {
    "prebook_token": "fpbk_8c7d6e5f-...",
    "provider": "rextur",
    "origin": "GRU",
    "destination": "GIG",
    "departure_date": "2026-03-15",
    "return_date": "2026-03-20",
    "passengers": { "adults": 1, "children": 0, "infants": 0 },
    "total_price": 625.00,
    "currency": "BRL",
    "pricing": {
      "base_fare": 490.00,
      "du": 25.00,
      "taxes": 110.00,
      "total": 625.00,
      "currency": "BRL"
    },
    "expires_at": "2026-03-01T18:20:00.000Z"
  }
}

Erros Possíveis

Status	Causa
400	`rate_token` inválido ou `total_price` não bate com o decodificado
400	`departure_date` no passado ou `return_date` antes de `departure_date`
500	Falha ao criar a sessão de prebook

5. Confirmar Reserva (Book)

POST /api/v1/flights/book

Consome o prebook_token, chama o fornecedor (Rextur online ou Moblix offline) para criar a reserva e processa o pagamento.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`prebook_token`	string	Sim	Token retornado por `/prebook`
`customer_id`	string (UUID)	Sim	ID do cliente cadastrado na sua equipe
`passengers`	array	Sim	Lista de passageiros (1 ou mais)
`contact_email`	string	Sim	E-mail de contato da reserva
`contact_phone`	string	Sim	Telefone de contato da reserva
`payment`	object	Sim	Dados de pagamento (ver abaixo)
`notes`	string	Não	Observações internas
`special_requests`	string	Não	Solicitações especiais

Passageiros

O número total de passageiros enviado em passengers[] deve ser exatamente igual a adults + children + infants do /prebook. Caso contrário, retornamos 400 Passenger count mismatch.

Campo	Tipo	Obrigatório	Descrição
`type`	string	Não	`adult`, `child` ou `infant` (padrão: `adult`)
`first_name`	string	Sim	Primeiro nome
`last_name`	string	Sim	Sobrenome
`gender`	string	Não	`M` ou `F`
`birth_date`	string	Sim	Nascimento (`YYYY-MM-DD`)
`document_type`	string	Não	`cpf`, `passport` ou `rg` (padrão: `cpf`)
`document_number`	string	Sim	Número do documento
`document_country`	string	Não	ISO 2 (padrão: `BR`)
`email`	string	Não	E-mail do passageiro
`phone`	string	Não	Telefone do passageiro

Pagamento

Campo	Tipo	Obrigatório	Descrição
`method`	string	Sim	`pix`, `credit_card` ou `boleto`
`installments`	number	Não	Parcelas (1–12) para cartão
`credit_card`	object	Condicional	Obrigatório quando `method = credit_card`
`credit_card_holder_info`	object	Não	Dados do titular para gateway (alguns providers exigem)

Para credit_card: holder_name, number, expiry_month (MM), expiry_year (YYYY), ccv.

Exemplo

curl -X POST https://app.moblix.net/api/v1/flights/book \
  -H "Authorization: Bearer mbx_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "prebook_token": "fpbk_8c7d6e5f-...",
    "customer_id": "uuid-do-cliente",
    "contact_email": "joao@example.com",
    "contact_phone": "+5511999999999",
    "passengers": [
      {
        "type": "adult",
        "first_name": "Joao",
        "last_name": "Silva",
        "gender": "M",
        "birth_date": "1985-03-15",
        "document_type": "cpf",
        "document_number": "12345678900",
        "email": "joao@example.com"
      }
    ],
    "payment": { "method": "pix" }
  }'

const response = await fetch('https://app.moblix.net/api/v1/flights/book', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mbx_live_sua_chave_aqui',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prebook_token: 'fpbk_8c7d6e5f-...',
    customer_id: 'uuid-do-cliente',
    contact_email: 'joao@example.com',
    contact_phone: '+5511999999999',
    passengers: [{
      type: 'adult',
      first_name: 'Joao',
      last_name: 'Silva',
      gender: 'M',
      birth_date: '1985-03-15',
      document_type: 'cpf',
      document_number: '12345678900'
    }],
    payment: { method: 'pix' }
  })
});
const data = await response.json();
console.log(data.data.booking);

Resposta de Sucesso (201 Created)

{
  "data": {
    "booking": {
      "id": "uuid-da-reserva",
      "booking_number": "BK-1234567890",
      "locator": "ABC123",
      "external_locator": "XYZ789",
      "status": "pending",
      "total_amount": 625.00,
      "currency": "BRL"
    },
    "flight": {
      "provider": "rextur",
      "origin": "GRU",
      "destination": "GIG",
      "departure_date": "2026-03-15",
      "return_date": "2026-03-20"
    },
    "payment": {
      "id": "uuid-do-pagamento",
      "method": "pix",
      "amount": 625.00,
      "status": "pending",
      "pix_qr_code": "data:image/png;base64,...",
      "pix_code": "00020126360014BR.GOV.BCB.PIX...",
      "expires_at": "2026-03-01T18:30:00.000Z"
    }
  }
}

Quando o pagamento é por PIX ou boleto, o status inicial é pending e a reserva passa a confirmed automaticamente via webhook quando o pagamento é compensado. Para cartão de crédito, a confirmação é instantânea e o booking já volta com status: "confirmed".

Erros Possíveis

Status	Causa
400	Validação de payload (passageiros, pagamento, etc.)
400	Nenhum provedor de pagamento ativo aceita o método solicitado
404	`prebook_token` não encontrado ou cliente não pertence à equipe
410	`prebook_token` expirado — refaça a busca e o prebook
502	Falha na criação da reserva no fornecedor (Rextur) — o booking é marcado como `cancelled` para auditoria

Provider Moblix (Offline) vs Rextur (Online)

	Rextur	Moblix
Emissão	Automática via API	Manual pelo painel
Localizador externo	Retornado no `external_locator`	Preenchido manualmente após emissão
Preço	Inclui DU/RAV (comissão)	Sem DU (apenas tarifa + taxas)
Disponibilidade	Validada no `/book`	Sempre aceita
Credenciais	Por agência	Fixas da Moblix

Use provider: "moblix" quando quiser registrar a venda agora e emitir o bilhete manualmente depois (útil em consolidadoras com tarifas privadas).

Códigos IATA Comuns (Brasil)

Código	Cidade	Aeroporto
`GRU`	São Paulo	Guarulhos
`CGH`	São Paulo	Congonhas
`GIG`	Rio de Janeiro	Galeão
`SDU`	Rio de Janeiro	Santos Dumont
`BSB`	Brasília	Internacional
`CNF`	Belo Horizonte	Confins
`SSA`	Salvador	Deputado Luís Eduardo
`REC`	Recife	Guararapes
`FOR`	Fortaleza	Pinto Martins
`POA`	Porto Alegre	Salgado Filho
`CWB`	Curitiba	Afonso Pena
`FLN`	Florianópolis	Hercílio Luz

Rate Limit

Endpoint	Limite
`/api/v1/flights/search`	30 req/min
`/api/v1/flights/rate`	60 req/min
`/api/v1/flights/prebook`	30 req/min
`/api/v1/flights/book`	10 req/min

Voos

On this page