API de Voos

Calendário de tarifas

GET /v1/flights/price-calendar?origin=DXB&destination=LHR&departureFrom=2026-11-01&departureTo=2026-11-30 devolve a tarifa em cache mais barata por dia para a rota, na sua moeda, com a indicação de quão recente é a cache. Adicione returnFrom / returnTo para totais de ida e volta por par de datas, e cabin para restringir a classe. É servido a partir da nossa cache de preços — instantâneo e nunca conta como pesquisa num fornecedor — por isso utilize-o para desenhar um calendário ou uma faixa de “dias mais baratos” antes da pesquisa real.

Pesquisa

POST /v1/flights/search com um trecho para só ida, dois para ida e volta, até seis para vários destinos; número de passageiros por tipo; uma cabine opcional e um número máximo de escalas (maxStops). Com wait=true, a resposta contém todas as ofertas depois de todos os fornecedores responderem; com wait=false, recebe um searchId e consulta GET /v1/flights/search/{searchId} com um cursor até complete ser true.

Cada oferta traz um offerId opaco, o total na sua moeda com a discriminação por passageiro, trechos → segmentos (transportadora, número de voo, horários, aeronave, cabine, bagagem), um resumo das condições tarifárias e uma validade. As ofertas são válidas durante a sessão de pesquisa (cerca de 20 minutos).

Tarifação e regras

POST /v1/flights/offers/{offerId}/price revalida a tarifa junto do fornecedor imediatamente antes de confirmar e devolve o preço confirmado, as taxas e os campos de passageiro que a companhia aérea exige (documentos, datas de nascimento, passageiro frequente). GET .../fare-rules devolve o texto das penalizações; GET .../ancillaries lista a bagagem paga e as opções que pode adicionar à encomenda.

Serviços adicionais (bagagem extra)

GET /v1/flights/offers/{offerId}/ancillaries lista os extras pagos que a companhia aérea oferece nessa tarifa — atualmente franquias adicionais de bagagem de porão, cada uma com uma key, peças / peso e um preço por passageiro. Pagos significa que têm preço acima da tarifa e são faturados com a encomenda, ao contrário da franquia incluída mostrada na própria oferta.

Para os comprar, adicione ancillaries[] a POST /v1/flights/orders: uma entrada por extra com a key e o passengerIndex (índice base 0 em passengers). São tarifados, reservados e emitidos juntamente com a encomenda e aparecem nos totais do bilhete da encomenda. Não é possível adicionar extras a uma encomenda já emitida; a seleção de lugares seguirá o mesmo padrão.

{
  "offerId": "fo_7Gk2Qp9LcKM5aGqrMQOIzJko",
  "passengers": [{ "type": "ADT", "gender": "M", "firstName": "SAM", "lastName": "TRAVELLER", "dateOfBirth": "1990-05-04" }],
  "contact": { "email": "[email protected]", "phone": "+971501234567" },
  "ancillaries": [{ "key": "BAG20-1", "passengerIndex": 0 }]
}

Criar a encomenda

POST /v1/flights/orders com o offerId, os passageiros (nomes como no passaporte, tipo, data de nascimento, documento para itinerários internacionais), um contacto e ancillaries[] opcionais (ver acima); adicione uma Idempotency-Key. Recebe um orderId, o PNR da companhia aérea, o prazo limite de emissão e o estado held. No sandbox, a encomenda é registada no sistema de teste do fornecedor e nada é cobrado; em produção, o depósito é reservado.

Emitir bilhetes

POST /v1/flights/orders/{orderId}/issue (Idempotency-Key obrigatória) emite os bilhetes eletrónicos e devolve os números de bilhete por passageiro. Consulte a encomenda a qualquer momento com GET /v1/flights/orders/{orderId}; o estado passa por held → issued → cancelled/refunded.

Anular, cancelar e reembolsar

GET /v1/flights/orders/{orderId}/refund-quote indica quanto um cancelamento devolve segundo as regras tarifárias (uma anulação no próprio dia é normalmente gratuita). POST /v1/flights/orders/{orderId}/cancel confirma-o; o reembolso é creditado no livro-razão do seu depósito, visível no portal do programador.