Integração de API de reserva de voos: o que a doc não diz

O card no quadro diz só «adicionar voos». Você já integrou um meio de pagamento, um cálculo de frete, talvez um serviço de mapas, e o modelo mental que traz é o óbvio: busca, resultados, cobrança no cartão, pronto. Aí a primeira reserva de verdade volta com um preço diferente do que estava na página de resultados, a segunda dá timeout e ninguém sabe dizer se o cliente tem assento, e alguém da operação pergunta por que existe uma reserva, mas não um bilhete. Vista de fora, uma integração de API de reserva de voos parece o checkout de um e-commerce. Por baixo, é uma transação distribuída com sistemas projetados muito antes do REST, e quase todas as surpresas vêm dessa diferença.
Este texto é para o desenvolvedor que nunca viu um PNR. Ele não trata dos endpoints de um fornecedor específico: os nomes mudam de um provedor para outro, a estrutura não.
A sequência de chamadas por trás de uma integração de API de reserva de voos
Quase toda API de voos, seja qual for o nome que dá aos seus métodos, percorre as mesmas quatro etapas. Acertar as fronteiras entre elas é a maior parte do trabalho.
| Etapa | O que ela entrega | O que você precisa guardar | O que dá errado |
|---|---|---|---|
| Busca | Itinerários com um preço e uma chave de oferta ou de tarifa opaca | Nada duradouro: os resultados envelhecem rápido | Você trata o preço como definitivo; a chave expira antes do checkout |
| Preço / verificação | O preço confirmado, as regras tarifárias, a bagagem, às vezes campos obrigatórios de passageiro | A oferta verificada e a validade dela | O preço mudou; a classe esgotou; as regras não batem com o que você exibiu |
| Reserva | Uma reserva, o PNR, com um localizador e um prazo de emissão | Sua própria referência, o localizador, o prazo, os dados exatos de passageiro enviados | Timeout sem resposta; PNRs duplicados; nomes recusados |
| Emissão | Os números de e-ticket emitidos: é aqui que o dinheiro é de fato comprometido | Cada número de bilhete, vinculado ao passageiro e ao segmento a que pertence | Emissão parcial; reserva cancelada pela companhia porque o prazo passou |
A linha que gera discussão é a terceira, porque muitas APIs deixam reservar e emitir numa única chamada. Use, se preferir. No mundo da companhia aérea, porém, as duas coisas continuam separadas: um PNR pode existir sem bilhete, e uma emissão pode falhar depois que o PNR foi criado. Um endpoint combinado apenas esconde o momento em que uma deu certo e a outra não, então o seu modelo de dados ainda precisa de um lugar para esse estado.
Repare também no que a busca não devolve: uma promessa. Ela é uma vitrine. A etapa de preço é a cotação, e só a emissão é a venda.
Por que o preço da busca não é o preço da reserva
Quem desenvolve para a web espera um catálogo. O inventário aéreo não é um. Um voo é vendido em classes de reserva, cada uma um lote de assentos a determinada tarifa, e a companhia abre e fecha esses lotes o tempo todo, à medida que o voo enche. Os resultados da busca são montados às pressas a partir de uma disponibilidade que pode já estar um pouco defasada; no tempo que o usuário leva para digitar dois passaportes, a classe mais barata daquele voo pode ter fechado. Quando a etapa de preço roda, ela pergunta de novo, e a resposta honesta às vezes é mais alta.
Os impostos trazem a sua própria variação. Eles são recalculados no pricing para os passageiros e a rota exatos, e uma criança ou um bebê tem preço diferente do adulto que a busca presumiu. A conversão de moeda, se a sua loja mostra uma moeda diferente daquela em que o fornecedor cota, é mais um ponto em que o número se mexe.
A consequência de projeto é simples e muitas vezes ignorada: nunca cobre pelo preço da busca. Rode a etapa de preço antes do pagamento, compare e, se o valor mudou, mostre o novo número e peça confirmação. Qualquer markup que você aplique precisa ser recalculado sobre a tarifa reprecificada, e não herdado da página de resultados: é a mesma lógica que uma agência enfrenta ao definir uma estratégia de markup online, e ela quebra do mesmo jeito quando a base se move por baixo.
Idempotência, e o que significa um timeout na reserva
Esta é a seção para ler duas vezes.
Quando uma chamada de reserva dá timeout, você não sabe o que aconteceu. A requisição pode nunca ter chegado. Pode ter chegado e falhado. Ou, o caso que dói, chegou, o fornecedor criou o PNR na companhia e a resposta se perdeu no caminho de volta. Para o seu código, os três casos são idênticos. Para a companhia aérea, o terceiro é uma reserva ativa segurando assentos no nome do seu cliente.
O reflexo que vem de outras integrações é tentar de novo. Aqui, um retry às cegas pode gerar um segundo PNR para os mesmos passageiros no mesmo voo. As companhias tratam reservas duplicadas como violação de política; dependendo da empresa aérea e dos acordos da agência, a consequência vai do cancelamento automático de uma ou das duas reservas até uma nota de débito, um ADM, enviada a quem as emitiu. A agência que recebe essa nota vai querer saber por que o seu sistema reservou duas vezes.
O que funciona, mais ou menos nesta ordem:
- Crie a sua própria referência de reserva antes de chamar o fornecedor, persista essa referência e envie com a requisição sempre que a API aceitar uma referência do cliente. Se a API suportar uma chave de idempotência (idempotency key), use; se não suportar, a sua referência continua sendo o que permite localizar a reserva depois.
- Modele explicitamente o estado desconhecido. Pendente, confirmada, falhou e desconhecida. Um timeout leva a reserva para desconhecida, não para falhou.
- Resolva o desconhecido perguntando, não repetindo. Recupere a reserva pela sua referência, ou liste as reservas recentes daqueles passageiros, antes de decidir se vai tentar de novo.
- Rode um job de conciliação que varra tudo o que ainda está desconhecido e compare com o que o fornecedor informa, e mande o que ele não conseguir resolver para uma fila tratada por uma pessoa, em vez de chutar.
Timeouts na emissão são o mesmo problema, com dinheiro no meio. Se você captura o cartão antes de emitir e a emissão trava, tem um cliente que pagou e talvez nenhum bilhete. Se emite antes da captura e a captura falha, emitiu um documento que alguém vai ter de pagar à companhia. Autorizar o cartão primeiro, emitir e depois capturar em caso de sucesso é o desenho mais comum: o ponto é decidir isso de propósito, e não descobrir em produção.
Os conceitos de aviação que surpreendem quem programa para a web
Nenhum deles é difícil. Cada um já custou uma semana a alguém, só porque a pessoa não sabia que ele existia.
PNR não é bilhete
O PNR é o registro da reserva: passageiros, segmentos, contatos, um prazo. O bilhete é o documento pago que dá ao passageiro o direito de voar. Um PNR sem emissão expira no prazo de emissão e os assentos voltam à venda, às vezes sem nenhum aviso do seu lado.
Nomes são praticamente imutáveis
Depois da emissão, a maioria das tarifas não permite troca de nome além de uma pequena correção, e o que conta como pequena varia de companhia para companhia. O nome precisa bater com o documento de viagem. Colete sobrenome e nomes separadamente, não deixe um tratamento digitado em texto livre vazar para um campo de nome e valide antes da chamada de reserva, não depois.
Tipos de passageiro têm preço, não são enfeite
Adulto, criança e bebê são tipos tarifários, e a idade que define qual se aplica costuma ser a idade na data da viagem, não na data da reserva. Um bebê de colo normalmente não ocupa assento e só pode viajar com um adulto. Erre o tipo e a etapa de preço falha ou cota a tarifa errada.
Horários são locais, e segmentos não são trechos
Os horários de partida e chegada vêm na hora local de cada aeroporto. Não converta para o fuso do usuário na exibição e não calcule durações subtraindo um do outro sem os offsets. Uma viagem contém segmentos; um segmento com parada técnica contém mais de um trecho. A sua interface e os seus dados precisam concordar sobre qual deles é uma «parada».
As coisas acontecem depois da venda
As companhias alteram horários depois que os bilhetes são emitidos. Uma reserva que estava correta na emissão pode mostrar, semanas depois, um novo horário, um novo número de voo ou uma conexão quebrada, e dependendo do fornecedor você fica sabendo por uma notificação, por uma fila ou recuperando a reserva de novo. Conte com a reserva mudando depois que você parou de olhar para ela.
Void não é reembolso
Logo após a emissão costuma haver uma janela em que o bilhete pode ser anulado (void) como se nunca tivesse existido. Passada essa janela, só resta o reembolso conforme as regras tarifárias, que pode ter multa ou não devolver nada. A janela e as regras dela pertencem ao fornecedor e ao acordo de emissão: leia tudo antes de construir um botão «cancelar».
Quanto custa errar
As falhas numa integração de voos são caras de um jeito específico: caem sobre pessoas, não sobre logs. Uma reserva duplicada vira uma ligação para a companhia e possivelmente uma nota de débito na conta da agência. Um cliente cobrado sem bilhete vira um reembolso, uma reclamação e um risco de chargeback. Um bilhete emitido sem pagamento confirmado vira uma dívida com a companhia que alguém vai ter de quitar. Uma alteração de horário que ninguém processou vira um viajante no aeroporto para um voo que saiu mais cedo.
Nada disso aparece num teste do caminho feliz. Escreva primeiro os caminhos infelizes: o timeout na reserva, o preço que subiu, a emissão que falhou depois do PNR, o void depois de um pagamento bem-sucedido. Se esses estiverem resolvidos, o caminho feliz é a parte fácil.
Testando contra uma API de voos
Os ambientes de teste dos fornecedores são úteis e incompletos. Costumam ser mais calmos que a produção, então classes esgotadas e mudanças de preço são mais raras, e alguns nem simulam timeouts. Use esses ambientes para a forma das chamadas e para os erros de validação, e depois planeje uma rodada controlada em produção com reservas reais que você anula (void) dentro da janela, com a operação ciente do que você está fazendo.
Integrar ou não é outra pergunta. Se o que você precisa de verdade é uma loja, e não o inventário bruto no seu próprio sistema, o trade-off está explicado em white label ou motor de reservas próprio, e o mesmo raciocínio vale para um portal B2B para subagentes. Se você quer mesmo o inventário no seu código, esta plataforma oferece APIs de voos e hotéis, e o acesso começa com uma conversa sobre o seu caso de uso, não com uma chave self-service: que é também o momento certo para fazer cada uma das perguntas acima.