Busca de vôos

Uma busca de vôos no TripApi é iniciada chamando o método Search.

Todos os métodos no TripApi obedecem o padrão de envelopes para envio de informações e recebimento de resultados, portanto, tanto no método de busca, como em todos os outros você notará o padrão "Action"RQ e "Action"RS. No exemplo temos na busca de vôo como único paramêtro de entrada o SearchRQ e como resultado o SearchRS.

SearchRQ

É o objeto passado como parâmetro da chamada Rest e contém todas os parâmetros possíveis de busca. Para fins da chamada , analisamos somente o AirParameters.

AirSearchParameters

Representa os parâmetros para uma busca de aéreo como um todo, não especificamente para um CityPair

CityPairRequest

Um CityPair representa um par de cidades, um city pair denota um ponto de saída e chegada final, representando exatamente o que foi buscado pelo usuário. A classe CityPairRequest é apenas um CityPair especializado e resumido para o envio de parâmetros de busca.

Para indicar as origens e destinos de pesquisa, assim como no retorno do resultado de busca são utilizados os códigos IATA de aeroporto, veja mais em Codigo IATA

Note que como filtro de busca o usuário final envia uma lista de CityPairsRequest, que pode representar uma busca somente ida(somente um CPR), uma ida e volta(dois CPRs) ou uma busca multi-trecho (diversos CPRs).

Temos então que em uma busca somente ida, o código de chamada do serviço deve enviar um array, com somente 1 elemento, que representa o trecho(CityPair) que o usuário quer buscar, por exemplo: Quero um voo de São Paulo para Brasilia, no dia 10/05/2024, neste caso teríamos um array de CPR como esse:

var cprs = new List<CityPairRequest> {
	new CityPairRequest()
	{
		OriginIata = "SAO",
		DestinationIata = "BSB",
		DepartureDate = "2024-05-10"
	}
}

Já em uma pesquisa IDA e VOLTA onde o usuário queira representar uma viagem São Paulo para Brasilia, indo dia 10/05/2024 e voltando 15/05/2024, teríamos que:

var cprs = new List<CityPairRequest> {
	new CityPairRequest()
	{
		OriginIata = "SAO",
		DestinationIata = "BSB",
		DepartureDate = "2024-05-10"
	},
	new CityPairRequest()
	{
		OriginIata = "BSB",
		DestinationIata = "SAO",
		DepartureDate = "2024-05-15"
	}
}

Temos então que não existe um tipo específico de busca(somente ida, ida e volta, e multi-trechos), todas as informações necessárias para inferir o tipo de busca esta nos dados do próprio array. No caso acima, podemos concluir que a busca é ida e volta pois o destino do CPR-1 é igual a origem do CPR - 0, ou seja CPR[1].DestinationIata == CPR[0].OriginIata. (SideNote: Na verdade a lógica não é tão simples quanto comparar uma string, dentro das rotinas de tratamento do TripApi, uma vez que a viagem pode partir do aeroporto de congonhas(CHG) e na volta, voltar para o aeroporto de guarulhos(GRU), mas no final das contas é quase igual a isso, mas no nível da cidade)

A distinção do tipo específico de busca é importante pois dentro do core e para alguns SupplierSystems conectados a ferramenta, existem tarifas promocionais ida e volta, e o conceito também é importante assimilar pois os termos “viagens OneWay/Somente Ida/OW” e “RoundTrip/Ida e Volta/RT” são muito usado nos sistemas de turismo.

Finalmente temos uma busca MultiTrecho, que não necessariamente é somente uma busca com mais de 2 CityPairs, mas também pode ser uma busca com 2(dois) CPRs onde o destino do segundo não é igual a origem do primeiro. Por exemplo: Tenho uma reunião em Brasilia no dia 10/05/2024 e na sequência outra em Goiania no dia 11/05/2024 e depois volto para São Paulo:

var cprs = new List<CityPairRequest> {
	new CityPairRequest()
	{
		OriginIata = "SAO",
		DestinationIata = "BSB",
		DepartureDate = "2024-05-10"
	},
  new CityPairRequest()
	{
		OriginIata = "BSB",
		DestinationIata = "GYN",
		DepartureDate = "2024-05-11"
	},
	new CityPairRequest()
	{
		OriginIata = "GYN",
		DestinationIata = "SAO",
		DepartureDate = "2024-05-11"
	}
}

SearchRs

É o objeto root que representa um retorno de busca.

AirResponseData

SearchExecutionInformations

AirSearchResponseData

O objeto AirSearchResponseData contém propriedades para representar um resultado de busca de voos. O preenchimento das propriedades pode variar de acordo com o tipo de busca sendo efetuado.

Com o objetivo de comprimir logicamente os dados da resposta e tornar o resultado menor, antes da compressão algorítmica, dicionários de objetos FlightGroups e AirCompanies são retornados no root do objeto. Desta forma, outros objetos que fazem referencia a objetos FlightGroups e AirCompanies no resultado, são representados apenas pelo número da referência.

Note que, por exemplo, a definição do objeto FlightOption contém uma lista FlightGroupIndex. Na verdade um FlightOption tem uma lista de FlightGroups, no entanto, na preparação do resultado os FlightGroups são convertidos unicamente em um dicionário e as referencias para cada uma das instancias deles são trocadas para um número da lista de FlightGroupIndex.

PriceMatrix

//Código inicializando somente a coluna da Gol
var priceMatrix = new PriceMatrix() {
	AirCompanies = new List<PriceMatrixAirCompany>()
	{
		new PriceMatrixCompany() {
			AirCompanyCode = "G3",
			Cells = new List<PriceMatrixCell>()
			{
				new PriceMatrixcell()
				{
					Price = 618,
					NumberOfStops = NumberOfStops.NonStop
				},
				new PriceMatrixcell()
				{
					Price = 853,
					NumberOfStops = NumberOfStops.TwoOrMore
				}
			}
		}
	}
}

CityPair

Assim como o CityPairRequest enviado no request da busca, o CityPair da resposta representa cada trecho buscado e contém informações dos FlightOptions relacionados com a busca de cada trecho.

Nos objetos CityPair do resultado de busca, a propriedade mais importante preenchida é a lista de FlightOptions.

FlightOption

O FlightOption é talvez a classe mais importante a ser compreendida no modelo de objetos de um resultado de busca, ele representa uma opção de escolha de viagem e pode ser implicitamente “Partial” ou “Full” (Não é necessário ter uma propriedade explicita informando esta característica já que o contexto de onde o objeto esta sendo lido infere esta informação).

FlightOption Partial

É um FlightOption que não contém todos os FlightGroups correspondentes a todos os CityPairRequests buscados. Isso porque, seja pela seleção do usuário(na busca ByCityPair) ou pelo blender(internamente no TripApi), ele será combinado para formar uma viagem completa. Por exemplo: Na busca ByCityPair, cada CityPair de resultado contém uma lista de FlightOptions parciais, somente com um FlightGroup cada um pois será na interface que o usuário selecionará a ida e volta que deseja.

Pode-se dizer que um FlightOption partial sempre deseja se tornar um FlightOption full, em algum ponto da jornada de combinação de FlightOptions ou na jornada de seleção de um usuário.

FlightOption Full

É um FlightOption cujo o número de FlightGroups é igual ao número de CityPairsRequest buscado. Exemplo: A lista de FlightOptions retornada no objeto AirResponseData na propriedade FlightOptions quando uma busca ByFlightOptions é efetuada.

Preço de um FlightOption

Você vai reparar que não existe uma propriedade preço no objeto FlightOption, isso acontece porque um FlightOption, desde o momento da busca tem vários preços possíveis, em classes tarifárias diferentes, preços mais baratos são mais baixos mas por outro lado oferecem tarifas com muita restrição e multas para reembolso e remarcação, preços mais caros são maiores mas são mais atrativos do ponto de vista de flexibilidade e multas menores ou nenhuma para reembolso e remarcação.

O preço padrão de um FlightOption é o BrandedFare com o preço ADT mais baixo.

O core do TripApi antes de retornar uma busca, passa por todas as referências de FlightGroups nos FlightOptions e seta elas para null e preenche esta lista de indices apontando para o dicionário global de FlightGroups que pertence ao escopo do resultado de busca.

BrandedFare

Representa uma tarifa nomeada disponibilizada para um FlightOption. Como citado um FlightOption pode possuir uma lista de BrandedFares, de acordo com a disponibilidade das tarifas do vôo.

Exemplo de BrandedFare:

Na imagem acima do site da Latam, temos um FlightOption(parcial) com um FlightGroup com somente um voo direto entre Gru e Poa. Na imagem vemos 4 BrandedFares: Light, Plus, Top e Plus (Premium Economy).

Fare

BrandedFareAmount

Representa basicamente um valor. No entanto, como quase todos os valores no turismo são acompanhados com taxas, esta classe encapsula todos os campos padrões.