Pesquisa e Disponibilidade de Voos

A etapa de pesquisa consulta dezenas de provedores (GDSs Sabre e Amadeus, conexões diretas Gol, Latam NDC, Azul e companhias internacionais) em paralelo para retornar voos, conexões, horários, classes e opções de tarifas.

---

1. Recuperar Sistemas de Pesquisa (/RecuperarSistemasPesquisa)

Identifica quais conexões e fornecedores aéreos estão habilitados para a agência no par Origem/Destino solicitado.

• Método: POST
• Rota: /api/V2/Voos/RecuperarSistemasPesquisa

1.1 Parâmetros da Requisição (Request)

Campo	Tipo	Obrigatório	Descrição e Regras
Login	String	Sim	Login operacional da agência no Travellink.
Senha	String	Sim	Senha da credencial da agência.
Origem	String	Sim	Código IATA de 3 letras do aeroporto ou cidade de origem (ex: SAO, GRU).
Destino	String	Sim	Código IATA de 3 letras do aeroporto ou cidade de destino (ex: RIO, GIG).
ClienteId	Integer	Não	ID do cliente corporativo (subagência/empresa). Nulo se padrão.
transacaoId	String	Não	GUID exclusivo para rastreabilidade de telemetria nos logs.

Exemplo de Request

{
  "Login": "AGENCIA_LOGIN",
  "Senha": "AGENCIA_PASSWORD",
  "Origem": "SAO",
  "Destino": "RIO",
  "transacaoId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

1.2 Estrutura da Resposta (Response)

Campo	Tipo	Descrição
Sistemas	Array	Lista de sistemas habilitados para a rota.
Sistemas[].Id	Integer	ID numérico do sistema. Pode ser utilizado no campo Sistema ou Sistemas da disponibilidade para filtrar fornecedores específicos.
Sistemas[].Nome	String	Nome comercial do fornecedor (ex: Sabre, Gol Linhas Aereas, Latam NDC).
Exception	Objeto	Nulo em caso de sucesso; preenchido se houver falha de validação.

Exemplo de Response

{
  "Data": "2026-10-15T10:00:00",
  "SessaoExpirada": false,
  "Sistemas": [
    { "Id": 1, "Nome": "Sabre" },
    { "Id": 2, "Nome": "Gol Linhas Aereas" },
    { "Id": 5, "Nome": "Latam NDC" },
    { "Id": 8, "Nome": "Azul Linhas Aereas" }
  ],
  "Exception": null
}

---

2. Disponibilidade de Voos (/Disponibilidade)

Executa a pesquisa massiva de voos de acordo com os critérios de rota, datas, passageiros e filtros de conveniência.

• Método: POST
• Rota: /api/V2/Voos/Disponibilidade
• Timeout Recomendado: 60 a 90 segundos (a chamada interroga múltiplos sistemas externos de forma assíncrona).

2.1 Especificação Completa dos Campos de Requisição (Request)

Campo	Tipo	Obrigatório	Descrição Detalhada e Regras de Negócio
Login	String	Sim	Login operacional da agência.
Senha	String	Sim	Senha da credencial.
Origem	String	Sim*	Código IATA da origem (ex: GIG). *Opcional apenas se MultiplosTrechos for utilizado.
Destino	String	Sim*	Código IATA do destino (ex: GRU). *Opcional apenas se MultiplosTrechos for utilizado.
DataIda	DateTime	Sim*	Data e hora de partida (padrão ISO 8601: YYYY-MM-DDTHH:mm:ss).
DataVolta	DateTime	Não	Data e hora de retorno (padrão ISO 8601). Obrigatório para buscas de ida e volta convencionais.
QuantidadeAdultos	Integer	Sim	Quantidade de passageiros adultos (ADT). Mínimo: 1, Máximo: 9 por reserva.
QuantidadeCriancas	Integer	Não	Quantidade de crianças de 2 a 11 anos (CHD). Padrão: 0.
QuantidadeBebes	Integer	Não	Quantidade de bebês de colo de até 23 meses (INF). Padrão: 0. Máximo: 1 bebê por adulto.
Flex	Boolean	Não	Modo de combinação de itinerário: • true: Retorna itinerários casados (ida + volta) em ViagensTrecho1. Ideal para voos internacionais com tarifas combinadas. • false: Retorna listas independentes de ida (ViagensTrecho1) e volta (ViagensTrecho2) para combinação livre. Padrão: false.
CompanhiasPreferenciais	Array<String>	Não	Lista de códigos IATA de companhias aéreas para priorizar quando Flex: true (ex: ["G3", "LA", "TP"]).
Cabine	String	Não	Filtro de classe de cabine desejada: "Economica", "PremiumEconomy", "Executiva", "Primeira".
BuscarVoosComBagagem	Boolean	Não	true para incluir no resultado tarifas que possuem franquia de bagagem despachada inclusa.
BuscarVoosSemBagagem	Boolean	Não	true para incluir tarifas básicas sem bagagem despachada.
ApenasVoosComBagagem	Boolean	Não	true para restringir estritamente a busca e descartar qualquer tarifa sem bagagem.
ApenasVoosDiretos	Boolean	Não	true para filtrar apenas voos sem escalas ou conexões.
ApenasSemTrocaDeAeroporto	Boolean	Não	true para eliminar conexões que exigem deslocamento terrestre entre aeroportos diferentes na mesma cidade (ex: pousar em SDU e decolar de GIG).
QuantidadeDeVoos	Integer	Não	Limite máximo de opções na resposta. Enviar 0 para retornar todas as opções encontradas.
Sistema	Integer	Não	0 para pesquisar em todos os fornecedores da agência, ou o ID numérico específico obtido em RecuperarSistemasPesquisa.
Sistemas	Array<Integer>	Não	Lista de IDs numéricos para pesquisar em múltiplos fornecedores selecionados (ex: [1, 2]).
TipoDeTarifa	Integer	Não	1: Apenas tarifas privadas/acordadas (inclui tarifas de operadora). 2: Apenas tarifas públicas de prateleira.
Recomendacao	Boolean	Não	true para calcular e retornar o bloco de recomendações de melhor tarifa por fornecedor.
Timeout	Integer	Não	Tempo limite máximo de espera em segundos para o motor aguardar os provedores mais lentos.
MultiplosTrechos	Array	Não	Lista de trechos para busca com múltiplos destinos (Open-Jaw / Multi-City). Detalhado abaixo.
MultiplosTrechos[].Origem	String	Se MultiTrecho	Código IATA de decolagem do trecho.
MultiplosTrechos[].Destino	String	Se MultiTrecho	Código IATA de pouso do trecho.
MultiplosTrechos[].Data	DateTime	Se MultiTrecho	Data da viagem do trecho em ISO 8601.

---

2.2 Estrutura da Resposta (Response)

Campo	Tipo	Descrição
Data	DateTime	Carimbo de data/hora do processamento da busca.
TempoPesquisa	String	Duração total da busca junto aos provedores (ex: "00:00:03.140").
Rota	String	"D" para rota puramente doméstica, "I" para rota internacional.
Cia	Array	Relação de companhias aéreas retornadas (CodigoIata, Descricao).
ViagensTrecho1	Array	Lista de opções de voo para o trecho de ida (ou opções casadas quando Flex: true).
ViagensTrecho2	Array	Lista de opções de voo para o trecho de volta (preenchida quando Flex: false).
ViagensMultiplosTrechos	Array	Matriz de trechos retornados quando a busca utilizou MultiplosTrechos.
Recomendacoes	Array	Opções recomendadas de menor preço por fornecedor.
Exception	Objeto	Nulo em caso de sucesso; preenchido se houver recusa ou falha geral de negócio.
ExceptionPorSistema	Array	Lista com o diagnóstico e mensagens individuais de fornecedores específicos.

Detalhamento de cada Viagem (Itens dentro de ViagensTrecho1 / ViagensTrecho2)

Propriedade	Tipo	Descrição
IdentificacaoDaViagem	String	Chave criptografada do voo (tripKey). Identificador obrigatório para as etapas de /Tarifar e /Reservar. Validade: 15 a 20 minutos.
Combinada	Boolean	true se a opção já representa ida e volta integradas em um único bilhete.
Duracao	Integer	Duração total da viagem em minutos (somando tempos de voo e conexões).
PrecoTotal	Decimal	Valor bruto total consolidado (tarifa + taxas de embarque + serviços) para todos os passageiros da pesquisa.
CiaMandatoria	Objeto	Companhia aérea responsável pela placa e regras tarifárias (CodigoIata, Descricao).
Fornecedor	Objeto	Sistema de onde o voo foi originado (Id, Nome).
Bagagens	Array	Descrição da franquia de bagagem inclusa na tarifa (ex: "1 peça de 23kg", "Sem bagagem").
Segmentos	Array	Trechos de voo que compõem o itinerário (escalas e conexões).
Segmentos[].NumeroDoVoo	String	Número do voo comercial (ex: "1234").
Segmentos[].Cia	Objeto	Companhia aérea operadora do segmento (CodigoIata, Descricao).
Segmentos[].Origem	Objeto	Aeroporto de decolagem (CodigoIata, Descricao).
Segmentos[].Destino	Objeto	Aeroporto de pouso (CodigoIata, Descricao).
Segmentos[].DataSaida	DateTime	Data e horário de decolagem no fuso local.
Segmentos[].DataChegada	DateTime	Data e horário de pouso no fuso local.
Segmentos[].Classe	String	Código da classe tarifária (ex: "Y", "W", "B", "O").
Segmentos[].Cabine	String	Cabine de serviço ("Economica", "Executiva").
Segmentos[].Equipamento	String	Tipo/modelo de aeronave (ex: "Boeing 737-800").
Segmentos[].Duracao	Integer	Duração do segmento em minutos.

---

3. Exemplos Práticos de Pesquisa por Cenário

Cenário A: Busca Ida e Volta com Combinação Dinâmica (Flex: false)

Permite ao passageiro escolher a ida na companhia A e a volta na companhia B.

Request

{
  "Login": "AGENCIA_LOGIN",
  "Senha": "AGENCIA_PASSWORD",
  "Origem": "GIG",
  "Destino": "GRU",
  "DataIda": "2026-10-15T00:00:00",
  "DataVolta": "2026-10-22T00:00:00",
  "QuantidadeAdultos": 1,
  "QuantidadeCriancas": 0,
  "QuantidadeBebes": 0,
  "BuscarVoosComBagagem": true,
  "BuscarVoosSemBagagem": true,
  "Flex": false,
  "Sistema": 0
}

Comportamento no Response:

• ViagensTrecho1: Contém as opções disponíveis de Ida.
• ViagensTrecho2: Contém as opções disponíveis de Volta.
• Impacto no /Tarifar e /Reservar: O cliente deverá enviar IdentificacaoDaViagem (da ida) E IdentificacaoDaViagemVolta (da volta).

---

Cenário B: Busca com Itinerário Casado pelo Menor Preço (Flex: true)

Ideal para voos internacionais e conexões onde a tarifa de ida depende do voo de volta (tarifas casadas de round-trip).

Request

{
  "Login": "AGENCIA_LOGIN",
  "Senha": "AGENCIA_PASSWORD",
  "Origem": "GRU",
  "Destino": "LIS",
  "DataIda": "2026-10-15T00:00:00",
  "DataVolta": "2026-10-25T00:00:00",
  "QuantidadeAdultos": 1,
  "QuantidadeCriancas": 0,
  "QuantidadeBebes": 0,
  "BuscarVoosComBagagem": true,
  "BuscarVoosSemBagagem": false,
  "Flex": true,
  "CompanhiasPreferenciais": ["TP", "LA"],
  "Cabine": "Economica",
  "Sistema": 0
}

Comportamento no Response:

• ViagensTrecho1: Já contém o itinerário completo (os segmentos de ida e os segmentos de volta combinados).
• ViagensTrecho2: Vem vazia ([]).
• Impacto no /Tarifar e /Reservar: O cliente envia apenas IdentificacaoDaViagem.

---

Cenário C: Busca de Múltiplos Trechos / Multi-Cidades (MultiplosTrechos)

Para viagens complexas (ex: São Paulo ➔ Paris, Londres ➔ São Paulo).

Request

{
  "Login": "AGENCIA_LOGIN",
  "Senha": "AGENCIA_PASSWORD",
  "QuantidadeAdultos": 2,
  "QuantidadeCriancas": 0,
  "QuantidadeBebes": 0,
  "MultiplosTrechos": [
    {
      "Origem": "GRU",
      "Destino": "CDG",
      "Data": "2026-11-05T00:00:00"
    },
    {
      "Origem": "LHR",
      "Destino": "GRU",
      "Data": "2026-11-20T00:00:00"
    }
  ],
  "Cabine": "Economica",
  "Sistema": 0
}

Comportamento no Response:

• Os voos retornam agrupados dentro de ViagensMultiplosTrechos.
• Cada opção possui seu respectivo IdentificacaoDaViagem por percurso.