Tratamento de erros da API do motor de reservas: três falhas que custam dinheiro

O ticket de suporte chega numa quinta-feira à noite. Um cliente pagou, a página ficou girando e depois mostrou um erro genérico. O cartão foi cobrado. Seus logs mostram um POST para o fornecedor que nunca recebeu resposta. A companhia aérea segurou um assento? Ninguém sabe dizer, e o cliente está esperando. Um bom tratamento de erros da API do motor de reservas é, em grande parte, o trabalho de nunca estar nessa posição, ou pelo menos de saber exatamente o que fazer quando se está.
A maioria dos guias de integração trata os erros como um catálogo de códigos de status. Em reservas, os códigos são a parte fácil. O que custa dinheiro é um pequeno conjunto de situações em que a requisição parece ter falhado, mas o mundo mudou mesmo assim, ou parece ter funcionado e o mundo não mudou. Três delas importam mais que as outras.
Falha um: o preço mudou entre a busca e a reserva
Resultados de busca são uma cotação, não um contrato. As tarifas ficam em cache, o estoque é compartilhado entre todos os canais pelos quais o fornecedor vende, e o valor que você mostrou às 14h02 pode estar velho poucos minutos depois. O fornecedor avisa na etapa de criação da reserva, às vezes com uma resposta limpa de «tarifa alterada», às vezes devolvendo em silêncio um total diferente dentro de uma resposta que, no mais, deu certo.
A segunda variedade é a perigosa. Se o seu código lê a confirmação, grava a reserva e cobra do cliente o valor que ele viu, a diferença sai da sua margem ou, mais tarde, de um ADM. A regra é simples: compare o total confirmado pelo fornecedor com o total aceito pelo cliente, sempre, em código, antes de capturar o pagamento.
O que fazer quando divergem depende do tamanho da diferença e de quem a arca. Alguns centavos de arredondamento entre moedas são uma tolerância que você define uma vez. Qualquer coisa maior volta ao cliente como novo preço, com um botão de aceite explícito. Nunca absorva automaticamente, nunca cobre automaticamente.
Falha dois: reservado, mas não emitido
Existir um PNR não é o mesmo que existir um bilhete. Muitos fluxos criam a reserva primeiro e emitem o e-ticket em uma etapa separada, com um prazo entre as duas. Se o pagamento passa e a emissão falha, você fica com o dinheiro de um cliente e uma reserva que vai expirar no relógio dela.
A falha raramente é barulhenta. A chamada de emissão devolve um erro ou um timeout, e a reserva fica num estado que seu banco chama de «pago» enquanto o fornecedor ainda diz «retida». Enquanto isso o prazo de emissão corre e, ao contrário da sua fila de suporte, a companhia aérea não espera.
Trate isso como um estado próprio, não como variante de sucesso ou de falha. Uma reserva precisa de pelo menos estes: criada, retida, pagamento capturado, emitindo, emitida, falhou-e-reembolsável. «Pagamento capturado, emitindo» é o estado que pede um temporizador: quando uma reserva passa tempo demais ali, um job deve reler a reserva no fornecedor e decidir, sem esperar que um humano perceba. A decisão é barata quando você conhece o prazo do fornecedor, porque ele diz por quanto tempo é seguro tentar de novo antes de reembolsar.
Falha três: o timeout com resultado desconhecido
É o ticket da quinta à noite. Sua requisição saiu; nenhuma resposta voltou; a conexão caiu ou o gateway desistiu. O fornecedor pode ter processado tudo, parte ou nada.
A tentação é repetir. Não repita às cegas uma chamada de criação, porque a segunda tentativa pode gerar uma segunda reserva, e duplicidade é custo real: dois assentos segurados, talvez dois bilhetes emitidos, uma briga de reembolso por um deles.
A ordem segura é: parar, ler e só então decidir. Pare o fluxo do cliente com um estado honesto, «estamos confirmando sua reserva». Leia o lado do fornecedor consultando a reserva pela referência que você gerou antes da chamada (por isso você cria primeiro uma referência de cliente própria e a envia, se o fornecedor aceitar). Só então decida: encontrada significa seguir a partir do estado real; não encontrada após a janela de processamento do próprio fornecedor significa que é seguro tentar uma vez.
Se o fornecedor não oferece consulta pela sua referência, busque por nome do passageiro, rota e data numa janela estreita e trate uma correspondência como encontrada. Feio, mas bem mais barato que uma duplicidade.
Uma tabela de decisão da qual você pode discordar
| O que você vê | O que você sabe | O que fazer | O que não fazer |
|---|---|---|---|
| Fornecedor devolve «tarifa alterada» | Nada foi reservado | Mostrar o novo total, pedir aceite, rodar a criação de novo | Rodar de novo com o preço antigo torcendo para passar |
| Sucesso, mas o total difere do aceito pelo cliente | Existe uma reserva no novo preço | Segurar o pagamento, perguntar ao cliente, cancelar a reserva se ele recusar | Capturar o valor antigo e engolir a diferença |
| Pagamento capturado, chamada de emissão com erro | Existe um PNR, status do bilhete desconhecido | Reler a reserva, repetir a emissão dentro do prazo, reembolsar depois dele | Marcar a reserva como falha e esquecer o PNR |
| Timeout na criação | Resultado desconhecido | Consultar pela sua referência, depois seguir ou repetir uma vez | Repetir cegamente na hora |
| Timeout no cancelamento | Você ainda pode responder pelo trecho | Reler o status antes de dizer algo ao cliente | Mostrar «cancelado» porque o clique aconteceu |
Uma linha da qual você pode discordar: algumas equipes reembolsam no primeiro erro de emissão para manter o cliente calmo. É defensável em bilhetes baratos e um mau hábito nos caros, porque você pode perder uma tarifa que teria salvado um minuto depois.
Quanto custa errar
Cada falha tem uma conta diferente. Uma mudança de preço não detectada é margem perdida em toda reserva que ela toca, em geral descoberta só na conciliação. Um caso reservado-não-emitido é um cliente que chega ao aeroporto com uma reserva vencida e uma cobrança no cartão: chargeback e problema de reputação ao mesmo tempo. Uma nova tentativa cega após timeout é uma reserva duplicada, e as companhias auditam duplicidades; um padrão delas é o tipo de coisa que acaba num ADM.
Nada disso é exótico. É a tubulação sem glamour que separa uma demonstração de algo que você pode deixar rodando no fim de semana.
Monte o job de conciliação antes de precisar dele
As três falhas terminam igual: seu banco e o do fornecedor discordam. Por isso escreva o job que os compara antes do primeiro incidente, não depois. Uma execução noturna é o mínimo; a cada poucos minutos para o que estiver em estado transitório é melhor. Ele lista reservas travadas em retida, emitindo ou desconhecida, pergunta ao fornecedor o que ele pensa e então corrige o registro ou abre um ticket com as evidências anexadas.
Guarde toda requisição e resposta das chamadas de reserva, inclusive timeouts, com a referência enviada. Quando um cliente contesta uma cobrança, esse log é o seu argumento. Ele também mantém honesta a conversa sobre latência: veja o que você pode e não pode corrigir na latência de API para entender por que timeouts são um fato da vida, e não um bug a eliminar.
Se você ainda está decidindo como ligar a conexão com o fornecedor, o passo a passo em integração de API de reserva de voos cobre a ordem das chamadas que este artigo pressupõe. E se quiser conversar sobre como esses estados se encaixam nas nossas APIs de voos e hotéis, o acesso começa por uma conversa: veja a página da API de viagens.