Pular para o conteúdo
Blog

API de preços de voos: o número que você vê ainda não é uma tarifa

Redação Tekravel
Escrito com a ajuda de IA

A demonstração funciona. Um desenvolvedor liga uma API de preços de voos a um calendário dos dias mais baratos para voar, a grade se enche de números e todos na sala ficam satisfeitos. Aí o primeiro cliente de verdade escolhe uma data, vê na página de resultados um valor menor que o da página de pagamento e escreve para o suporte com uma captura de tela. Nada está quebrado. A API fez o que lhe pediram: respondeu a uma pergunta sobre preço, e o site tomou a resposta por uma promessa.

Preço é uma oferta de memória curta

Uma tarifa aérea não é uma etiqueta fixa colada num assento. É uma classe que abre e fecha conforme os assentos são vendidos, e o seu valor muda com a composição dos passageiros, os voos exatos, as taxas dos aeroportos envolvidos e a moeda da cotação. Uma resposta de preço é um retrato tirado num momento, para um conjunto de entradas. Trate-a como um fato do passado e você construirá a coisa certa; trate-a como um fato do presente e passará um mês com reembolsos.

Por isso a pergunta útil para o desenvolvedor nunca é só qual é o preço. É que tipo de preço é esse, qual a idade dele e o que o sistema fará se ele estiver errado.

Três números que todo mundo chama de preço

A maioria dos fornecedores devolve os três em algum ponto da documentação, muitas vezes sob o mesmo nome de campo. Separe-os no seu modelo de dados desde o primeiro dia.

EstadoDe onde vemFrescorPode vender?O que mostrar
Preço de navegaçãoBusca em cache ou agregada, feita para velocidade e abrangênciaPossivelmente defasado e não calculado para os seus passageirosNãoTexto «a partir de» e aviso de que pode mudar
Oferta precificadaConsulta ao vivo do itinerário, dos tipos de passageiro e da tarifa exatosFresca no momento da chamada, com validade ou sinal de reprecificaçãoSim, até expirarO total, taxas discriminadas, regras da tarifa
Valor emitidoO que a companhia aérea ou o sistema emissor realmente cobrou no pedidoDefinitivoJá vendidoO recibo, conciliado com a oferta

O preço de navegação é o que viabiliza calendários e selos «a partir de», e é ótimo construí-lo. Mas não é o mesmo objeto da segunda linha. O erro é um único campo price para o qual os três escoam.

Na prática, são três tipos ou três tabelas no código, não um com uma flag. O preço de navegação pode errar um pouco, porque é só um convite ao clique. A oferta precificada é um compromisso que você está prestes a assumir em seu nome, então é guardada com a hora da consulta, as entradas que a produziram e o identificador que o fornecedor vai exigir no pedido. O valor emitido é contabilidade. Quando o suporte pergunta por que o cliente pagou um número diferente do que estava no e-mail, a resposta está na lacuna entre as linhas, e você só a lê se guardou os três.

O que uma resposta de preço precisa trazer

Um número solto não basta para montar um checkout. Ao ler a resposta de exemplo de um fornecedor, procure o seguinte e desconfie do que vier como texto livre.

  • A moeda, informada na resposta e não presumida a partir da sua conta.
  • Tarifa base e impostos separados, para mostrar o detalhamento e para que uma mudança de imposto não pareça mudança de tarifa.
  • Os tipos de passageiro para os quais o preço foi calculado. O preço de um adulto vezes três não é tarifa familiar.
  • Regras da tarifa e bagagem como dados estruturados, pois decidem se a opção barata é mesmo mais barata para o seu cliente.
  • Uma validade ou sinal de reprecificação: um carimbo de data e hora, ou a declaração explícita de que é preciso reprecificar antes de pedir.

O último item é o que as pessoas pulam. Se nada na resposta diz quanto tempo a oferta vive, você está adivinhando, e o palpite acontece em produção.

Reprecifique antes do pedido, não depois

O ritmo mais seguro tem uma regra dentro. Busca-se para navegar. Quando o cliente escolhe um itinerário, pede-se uma oferta precificada ao vivo para exatamente esse itinerário e esses passageiros. Mostra-se esse total ao cliente. Só então se cria o pedido. Se o preço ao vivo difere do da página de resultados, você avisa o cliente antes de ele pagar, com palavras claras, e não depois.

Se pular a etapa do meio, você herda a diferença. Ou cobra mais do que o cliente viu e perde a venda na página de pagamento, ou honra o número menor e a diferença sai da sua própria margem. Uma agência pequena consegue absorver isso algumas vezes; não consegue absorver como regra de projeto.

Pergunte por escrito antes de integrar

A documentação descreve o caminho feliz. O comportamento que custa dinheiro está nas respostas a uma lista curta de perguntas, e é melhor tê-las num e-mail do que numa ligação.

  1. O preço na resposta da busca é ao vivo ou em cache, e isso consta na própria resposta?
  2. Existe uma chamada de precificação separada para o itinerário exato, e ela é obrigatória antes de um pedido?
  3. O que acontece no pedido se o preço mudou: uma recusa, um novo preço na resposta ou uma emissão silenciosa pelo novo valor?
  4. Como são discriminados impostos e sobretaxas da companhia, e eles podem mudar entre a precificação e a emissão?
  5. Em que moeda o preço é calculado, e onde ocorre a conversão se o cliente vê outra?
  6. Por quanto tempo uma oferta precificada permanece válida, e como você saberá?

Um fornecedor que responde com precisão pensou no checkout. Quem responde «está sempre atualizado» não lhe deu nada que você possa testar. Se você não consegue experimentar o comportamento por conta própria, é motivo para olhar o conjunto de outro jeito antes de construir em cima dele.

O custo de errar

Raramente falha com barulho. Falha como uma pequena queda na etapa de pagamento que ninguém atribui ao preço, como tickets de suporte que começam com «o preço mudou», como um cliente que confiou na página de resultados e agora não confia mais. A equipe acaba reconfirmando tarifas à mão antes de emitir. Alguém propõe, por fim, uma regra que arredonda os preços para cima por precaução, e o site fica caro justamente na tela em que as pessoas comparam. Cada um desses custos é um imposto sobre uma decisão que era barata de tomar certo no começo.

Onde esta plataforma se situa

A plataforma expõe APIs de voos e hotéis, ativadas por inquilino. O acesso começa com uma conversa, e não com uma chave de autoatendimento; não há formulário que lhe entregue um token e uma tabela de limites. Não publicamos aqui latência, cobertura nem número de tarifas, porque um número que não conseguimos mostrar como testar não merece ser impresso. O que você pode fazer é levar as perguntas acima a essa conversa e pedir para ver a resposta de uma oferta precificada, não só a de uma busca. Se você está nessa etapa, a página de APIs de viagem é por onde começa.

Redação Tekravel

Mesa de tecnologia de viagens

A mesa de tecnologia de viagens da Tekravel escreve para o setor: donos de agências, consolidadores e os programadores que os integram. Cada artigo é verificado na plataforma que descreve antes de ser publicado.