Guia técnico

Como integrar uma API hoteleira: passo a passo para travel techs

9 min de leitura · atualizado em 22/11/2026

Integrar uma API hoteleira vai além de chamar um endpoint de pesquisa. Inventário multibroker muda a cada segundo, cada oferta tem sua política e uma reserva pode ficar pendente. Este passo a passo segue o fluxo da API Iterpec, mas os cuidados valem para qualquer integração B2B de hotéis.

O fluxo em nove passos

  1. 1. Contrato e credenciais

    Assine o contrato e receba usuário e senha da API, exclusivos da sua empresa. Credenciais são de produção: as reservas são reais.

  2. 2. Carregue o catálogo estático

    Use o catálogo GraphQL da Iterpec como fonte de destinos e hotéis, atualizado a cada 30 dias. Guarde no seu sistema para pesquisas rápidas.

  3. 3. Enriqueça cada hotel

    Busque o HotelDetail de cada hotel (fotos, textos, quartos, comodidades) e mantenha em cache. Depois, atualize apenas os hotéis que mudaram.

  4. 4. Pesquisa de descoberta

    Faça o Search por destino ou lista de hotéis com cheapestRoomOnly=true. Use timeout de 3 segundos para respostas rápidas ou 6 segundos como padrão; acima de 10 segundos a pesquisa fica lenta demais.

  5. 5. Pesquisa do hotel escolhido

    Repita o Search só para o hotel escolhido com cheapestRoomOnly=false para receber todos os quartos. Agrupe ofertas do mesmo quarto e mostre as opções de cancelamento e regime de alimentação.

  6. 6. Valide antes de reservar

    Chame GetBookingConditions. Se a oferta vier indisponível (CanBook=false), refaça a pesquisa do hotel sem ela e peça nova escolha. Se o quarto mudar, peça confirmação ao cliente.

  7. 7. Reserve

    Use DoBooking com os mesmos hóspedes e idades das crianças da pesquisa. Em reservas faturadas não se envia cartão; nas demais, os dados de cartão são obrigatórios.

  8. 8. Acompanhe o status

    Confirmed é reserva confirmada; Rejected não foi criada nem cobrada. Pending ou TechnicalProblem são resultado incerto: consulte GetBookingDetail a cada 5 minutos e nunca recrie a reserva às cegas.

  9. 9. Cancele com precisão

    Cancele a reserva inteira pelo BookingId ou apenas alguns quartos pelos ServiceIds, e confirme o resultado em GetBookingDetail.

Erros que mais derrubam integrações

  • Buscar detalhes completos dos hotéis durante a pesquisa do cliente, em vez de usar o cache.
  • Reaproveitar uma oferta marcada como indisponível em vez de refazer a pesquisa.
  • Tratar uma reserva pendente como falha e criar outra, gerando duplicidade.
  • Esconder taxas locais ou a política de cancelamento até depois da compra.
  • Usar timeouts muito longos achando que isso garante o menor preço.

Testes e homologação

Como as credenciais são de produção, toda reserva de teste é real. Teste apenas tarifas com cancelamento gratuito comprovado, no menor valor possível, cancele no mesmo dia e confirme o status Cancelled em GetBookingDetail.

Na homologação da Iterpec, você envia as evidências de cada etapa, a equipe revisa e, após aprovação humana, a integração recebe um certificado.

Ferramentas que aceleram a integração

  • Documentação interativa com Try-it-out e exemplos em 6 linguagens.
  • Servidor MCP para assistentes de IA, que ensina este mesmo fluxo dentro do seu editor de código.
  • Página pública de status com disponibilidade e latência do serviço.

Perguntas frequentes

Existe ambiente de testes separado?
A integração usa credenciais de produção. Os testes são feitos com reservas reais canceláveis sem custo e canceladas no mesmo dia.
Preciso pedir os detalhes do hotel a cada pesquisa?
Não. Guarde o HotelDetail no seu sistema e atualize apenas os hotéis alterados a cada ciclo de 30 dias.
Como começo a integração com a Iterpec?
Escreva para [email protected] para contrato e credenciais e acompanhe a documentação da API.

Leia também