Buscar voos

Busca voos em um programa de fidelidade ou companhia aérea, em tempo real.


POST /flights/search

Headers obrigatórios

Header	Valor
`x-api-key`	`sua-api-key`
`Content-Type`	`application/json`

Request Body

Campo	Tipo	Obrigatório	Descrição
`airlineLoyalty`	`string[]`	✅	O programa de fidelidade (milhas) ou companhia aérea (dinheiro) da busca, como um array de um único valor: `["SMILES"]`. Valores aceitos dependem de `priceType`.
`priceType`	`string`	Não	Tipo da busca: `MILES` (milhas, padrão) ou `CASH` (dinheiro)
`tripType`	`string`	✅	Tipo de viagem: `ONE_WAY` ou `ROUND_TRIP`
`cabinType`	`string`	✅	Classe da cabine: `ECONOMY` ou `BUSINESS`
`origin`	`string`	✅	Código IATA do aeroporto de origem (3 letras maiúsculas, ex: `GRU`)
`destination`	`string`	✅	Código IATA do aeroporto de destino (3 letras maiúsculas, ex: `MIA`)
`departureDate`	`string`	✅	Data de ida no formato `YYYY-MM-DD`
`returnDate`	`string`	Condicional	Data de volta (`YYYY-MM-DD`). Obrigatório se `tripType` = `ROUND_TRIP`
`passengers`	`object`	✅	Objeto com a quantidade de passageiros (ver abaixo)
`responseFormat`	`string`	Não	`RAW` (bruto, padrão) ou `PARSED` (normalizado). Ver Formato da resposta.

Valores aceitos em `airlineLoyalty` por `priceType`

`priceType`	Valores aceitos em `airlineLoyalty`
`MILES`	`SMILES`, `LATAM`, `AZUL`, `AZUL_INTERLINE`, `COPA`, `DELTA`, `TURKISH`, `AADVANTAGE`
`CASH`	`LATAM`, `AZUL`, `GOL`

Para comparar programas, dispare uma requisição por programa, em paralelo, e renderize cada resposta assim que ela chegar. Ver Comparando vários programas.

Objeto `passengers`

Campo	Tipo	Obrigatório	Validação	Descrição
`adults`	`int`	✅	1–9	Número de adultos
`children`	`int`	Não	0–8 (padrão: 0)	Número de crianças
`infants`	`int`	Não	0–4 (padrão: 0)	Número de bebês

Regras de validação

airlineLoyalty deve conter um único valor — o programa desta busca.
O valor de airlineLoyalty deve ser válido para o priceType escolhido. Caso contrário, a API retorna 422 Unprocessable Entity.
adults + children não pode exceder 9.
infants não pode exceder o número de adults.
origin e destination devem ser diferentes.
returnDate deve ser posterior a departureDate.
returnDate é obrigatório quando tripType = ROUND_TRIP.
responseFormat, quando enviado, deve ser exatamente RAW ou PARSED. Qualquer outro valor retorna 422 Unprocessable Entity.

Response `200 OK` (formato `RAW` — padrão)


{
  "results": [
    {
      "airline": "SMILES",
      "success": true,
      "data": { ... }
    }
  ],
  "summary": {
    "totalAirlinesRequested": 1,
    "successfulSearches": 1,
    "failedSearches": 0
  }
}

Quando a companhia falha, a requisição continua sendo 200 OK — a falha é reportada dentro do item:


{
  "results": [
    {
      "airline": "AZUL",
      "success": false,
      "error": {
        "message": "Failed to fetch data from AZUL",
        "providerStatusCode": 503
      },
      "data": null
    }
  ],
  "summary": {
    "totalAirlinesRequested": 1,
    "successfulSearches": 0,
    "failedSearches": 1
  }
}

No formato RAW (padrão) o campo data contém a resposta original e bruta da API da companhia, sem normalização — a estrutura varia entre programas e entre buscas em milhas e em dinheiro. Se preferir dados já tratados e num formato único, use responseFormat: "PARSED".

Estrutura de cada item em `results` (formato `RAW`)

Campo	Tipo	Descrição
`airline`	`string`	Programa/companhia (`SMILES`, `LATAM`, `AZUL`, `AZUL_INTERLINE`, `COPA`, `DELTA`, `TURKISH`, `AADVANTAGE`, `GOL`)
`success`	`boolean`	`true` se a busca foi bem-sucedida
`data`	`object`	Resposta original e bruta da API da companhia. `null` em caso de erro
`error`	`object`	Presente apenas em caso de falha (ver abaixo)

Objeto `error` (por companhia)

Campo	Tipo	Descrição
`message`	`string`	Mensagem de erro legível
`providerStatusCode`	`int`	Status HTTP retornado pelo provedor da companhia

Tempo limite. Uma busca que não responder em 29 segundos volta como falha do programa, com providerStatusCode: 504. Ou seja: uma companhia travada nunca deixa a sua requisição sem resposta — você sempre recebe um 200 OK bem-formado.

Objeto `summary`

Campo	Tipo	Descrição
`totalAirlinesRequested`	`int`	Quantidade de companhias solicitadas
`successfulSearches`	`int`	Quantidade de buscas com sucesso
`failedSearches`	`int`	Quantidade de buscas que falharam

Buscar voos

Headers obrigatórios

Request Body

Valores aceitos em airlineLoyalty por priceType

Objeto passengers

Regras de validação

Response 200 OK (formato RAW — padrão)

Estrutura de cada item em results (formato RAW)

Objeto error (por companhia)

Objeto summary