Pular para o conteúdo
Blog

API de disponibilidade hoteleira e fornecedores lentos

Redação Tekravel
Escrito com a ajuda de IA

O ticket costuma chegar com cara de inofensivo. “Adicionar busca de hotéis à página de reserva: o fornecedor passou uma API de disponibilidade hoteleira, tem sandbox, deve caber em uma sprint.” Você lê a documentação, envia uma requisição para dois adultos em Dubai por três noites e a resposta volta. Depois envia a mesma requisição para uma cidade com mais propriedades e, por um tempo longo e desconfortável, nada volta. Quando volta, é um documento tão grande que o seu parser JSON começa a repensar as próprias escolhas de vida.

É nesse momento que o trabalho muda de formato. Disponibilidade de hotel não é uma consulta simples. É um fan-out: uma pergunta do usuário vira muitas perguntas para muitos fornecedores, e cada um responde no seu ritmo, com o seu vocabulário e com a sua própria ideia do que é um “quarto”. O client que você constrói precisa continuar útil enquanto esse fan-out ainda está se resolvendo. Este texto trata de como projetar esse client, pensando em quem conhece bem REST e JSON e nunca precisou explicar a um hotel por que uma tarifa não reembolsável apareceu para o hóspede como cancelamento grátis.

Por que uma API de disponibilidade hoteleira é mais lenta do que os endpoints que você conhece

De fora, uma busca de voos e uma busca de hotéis parecem iguais: sai uma consulta, voltam opções com preço. Por baixo, não são o mesmo problema. Se você leu nossas notas sobre o que uma integração com API de reserva de voos realmente envolve, já sabe que o preço encontrado na busca nem sempre é o preço que você reserva. Hotéis somam uma segunda dificuldade a essa: volume.

Uma única cidade pode ter centenas de propriedades. Cada propriedade vende vários tipos de quarto. Cada tipo de quarto é vendido em vários planos tarifários (rate plans): com café da manhã, sem café, reembolsável, não reembolsável, tarifa de membro, tarifa de pacote. E cada plano tarifário pode vir de mais de um fornecedor: um bedbank, um channel manager, um contrato direto, um wholesaler com quem vocês fecharam porque o allotment dele naquele hotel era melhor que o de qualquer outro. Multiplique tudo e uma busca “simples” vira uma árvore enorme, montada a partir de fontes que não concordam nem nos nomes nem nos IDs.

Então a parte lenta raramente é o seu código. É o fornecedor mais lento que você decidiu esperar.

Resultados progressivos ou resposta completa: escolha de propósito

Existem duas formas honestas de devolver resultados de busca de hotéis, e a maioria das integrações acaba num meio-termo que não agrada ninguém.

Esperar tudo. O backend dispara o fan-out, espera cada fornecedor responder ou estourar o timeout, junta, remove duplicados, ordena e devolve uma lista completa. O resultado é limpo: uma requisição, uma resposta, preços comparáveis porque estão todos na mesa. O custo é que o usuário fica olhando para um spinner pelo tempo que o fornecedor mais lento levar, toda vez.

Entregar o que já chegou. O backend inicia o fan-out e devolve na hora um handle da busca. O client consulta esse handle periodicamente, ou mantém um stream aberto, e recebe os resultados em lotes conforme os fornecedores respondem. Os primeiros hotéis aparecem rápido. O custo é complexidade em todo o resto: a lista se reordena enquanto o usuário está lendo, o selo de “mais barato” pode mudar de lugar e um hotel que veio de um fornecedor pode receber depois uma tarifa menor de outro.

Se a sua interface é uma página de busca diante de uma pessoa, o modo progressivo quase sempre é o certo: ela está navegando, não rodando um job em lote, e uma página que mostra que está trabalhando ganha de uma página que pensa em silêncio. Se quem consome é outra máquina, como um job de comparação de tarifas ou uma ferramenta de viagens corporativas que precisa de uma resposta definitiva, esperar costuma ser mais simples e correto.

Seja qual for a escolha, três regras mantêm um client progressivo sob controle:

  • Cada lote traz um estado de conclusão da busca como um todo, para o client saber a diferença entre “ainda não há mais resultados” e “não haverá mais resultados”.
  • Os resultados são mesclados no servidor por uma chave de hotel estável, e não simplesmente anexados. O client nunca deveria ter que deduzir que dois cards são o mesmo prédio.
  • A ordenação por preço é provisória até a busca terminar, e a interface deixa isso claro. Usuários perdoam uma lista que se acomoda; não perdoam um rótulo de “menor preço” que se revela errado.

Modelar quartos e planos tarifários sem que tudo desmorone

É aqui que a maioria das integrações de hotel falha em silêncio, e a falha aparece meses depois como chamado de suporte, não como relatório de bug.

O modelo tentador é plano: um hotel tem uma lista de ofertas, cada oferta tem um nome de quarto e um preço. Fica bonito na tela. Aí um fornecedor devolve “Deluxe King” e “Deluxe Room, 1 King Bed” para o que obviamente é o mesmo quarto, outro usa o mesmo nome para dois quartos de fato diferentes (um com vista para a cidade, outro sem), e um terceiro manda um preço por noite enquanto todos os outros mandam por estadia. Uma lista plana não consegue dizer qual desses casos você tem na frente. Ela só exibe.

Um modelo que sobrevive ao contato com fornecedores reais tem pelo menos quatro níveis, e os mantém separados:

NívelO que guardaO erro a evitar
HotelUm ID estável seu, mapeado para o código de cada fornecedorUsar o ID de hotel de um fornecedor como chave primária
QuartoOcupação, configuração de camas, o texto original do fornecedor guardado sem alterações“Limpar” os nomes dos quartos até dois quartos diferentes virarem um só
Plano tarifárioRegime de alimentação, reembolsabilidade, forma de pagamento, o fornecedor de origemTratar café da manhã ou reembolsabilidade como parte do nome do quarto
PreçoTotal da estadia, moeda, quais impostos e taxas estão incluídos e quais são pagos no hotelMostrar um valor por noite ao lado de valores por estadia, ou esconder taxas pagas na chegada

Dá para discordar de onde ficam as divisões: alguns times separam a ocupação num nível próprio, o que faz sentido quando se vendem reservas de vários quartos. O que não dá é fundir níveis porque a interface só mostra dois deles. A interface pode achatar na hora de renderizar. Os dados, não.

Um detalhe merece uma frase só para ele: guarde a descrição bruta do quarto enviada pelo fornecedor junto com qualquer versão normalizada. Quando um hóspede chegar e receber um quarto diferente do que está no voucher, a primeira coisa que todos vão perguntar é o que o fornecedor realmente mandou.

Políticas de cancelamento são dados, não um parágrafo

Muitos fornecedores devolvem as condições de cancelamento como texto livre: “Cancelamento grátis até 3 dias antes da chegada; depois disso, multa de 1 noite.” A tentação de exibir essa string e seguir em frente é enorme.

Não faça isso. Texto não pode ser comparado, ordenado, filtrado nem aplicado. O usuário quer filtrar só tarifas reembolsáveis. O financeiro quer saber quais reservas viram não reembolsáveis amanhã, para a agência cobrar o cliente antes de o prazo vencer. O fluxo pós-reserva precisa dizer ao cliente, no instante em que ele clica em cancelar, exatamente quanto vai ser cobrado. Nada disso funciona em cima de uma frase.

Modele cada política como uma lista ordenada de janelas de multa: deste instante até aquele, a cobrança é este valor (ou esta fração da estadia, ou este número de noites). Os limites são timestamps com fuso horário, e o fuso é o do hotel, não o do seu servidor nem o do usuário, porque “3 dias antes da chegada” significa um momento diferente dependendo de qual meia-noite você usa como referência. Guarde o texto original do fornecedor ao lado da versão estruturada, exiba a estruturada e trate qualquer divergência entre as duas como algo a investigar, não a esconder.

E confira a política de novo na hora da reserva, não só na busca. Entre uma chamada e outra, as políticas mudam com mais frequência do que qualquer um imagina.

Quanto custa errar de verdade

Uma busca lenta custa conversões, o que é ruim, mas visível: alguém vai reclamar. As falhas caras são as silenciosas.

Uma tarifa exibida como reembolsável que o fornecedor trata como não reembolsável vira uma disputa com um cliente que tem print da tela, e normalmente quem acaba pagando a multa é a própria agência. Um preço por noite apresentado como total da estadia vende quartos abaixo do custo até alguém na contabilidade perceber. Um quarto fundido com outro diferente manda uma família de quatro pessoas para um quarto feito para duas. Taxas pagas no hotel que nunca foram mostradas transformam uma avaliação cinco estrelas em chargeback. Cada uma dessas é uma decisão de modelagem tomada na primeira sprint, geralmente sob o rótulo “a gente arruma depois”.

Cache: o que você pode guardar e o que não pode

Todo time que integra uma API de hotéis acaba perguntando se pode fazer cache dos resultados para deixar a busca mais rápida e mais barata. A resposta é sim, para algumas coisas, e a linha entre elas importa mais do que qualquer número de desempenho.

Conteúdo estático (nomes de hotéis, endereços, coordenadas, fotos, listas de comodidades, descrições de quartos) muda pouco e é exatamente o que você deve guardar em cache, sem economia, no seu próprio armazenamento. Verifique nos termos do fornecedor como você pode armazenar e exibir esse conteúdo; algumas licenças impõem restrições. Buscá-lo ao vivo a cada pesquisa é lento e não traz benefício nenhum.

Tarifas e disponibilidade ao vivo são outra história. Um preço em cache é um palpite sobre o que o fornecedor vai cobrar, e fornecedores não honram os seus palpites. Um cache de curta duração dos resultados de busca pode ser aceitável para exibir uma página, desde que todo caminho de reserva reprecifique junto ao fornecedor antes de cobrar e que a interface trate um preço alterado como resultado normal, não como erro. Alguns fornecedores também limitam quantas buscas você pode fazer em relação a quantas reservas você efetivamente faz; um cache agressivo que esconde deles o seu tráfego real não é uma brecha em que valha a pena confiar.

O que você nunca deve colocar em cache é qualquer coisa que represente um compromisso: um token de preço bloqueado, um localizador de reserva, uma cotação de cancelamento. Isso pertence a um único usuário e a um único momento.

Antes de dar por encerrado

Uma checagem rápida, que vale rodar na sua integração antes que ela receba reservas reais:

  • A busca devolve um estado de conclusão, e o client se comporta de forma diferente antes e depois dele.
  • Os hotéis são identificados por um ID seu, com o código de cada fornecedor mapeado para ele.
  • Quarto, plano tarifário e preço são objetos separados nos seus dados, não importa o que a tela mostre.
  • Todo preço informa se é por noite ou por estadia, e o que é pago na chegada.
  • As políticas de cancelamento ficam armazenadas como janelas de multa com horário, no fuso do hotel, com o texto original preservado.
  • O caminho de reserva reprecifica e relê a política antes de cobrar qualquer pessoa.
  • Nada que represente um compromisso é servido a partir de um cache.

Se você está pesando entre construir tudo isso fornecedor por fornecedor ou partir de uma plataforma que já enfrentou esses problemas, o lado contratual pesa tanto quanto o código: nosso texto sobre contratos de consolidadora hoteleira e tarifas de bedbank mostra o que pedir. Nossas APIs de voos e hotéis são liberadas por conversa, não por uma chave self-service; se esse é o caminho que você quer explorar, comece essa conversa na página de travel APIs.

O fan-out nunca vai embora. Um bom client simplesmente para de fingir que ele não existe.

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.