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. 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. 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. 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. 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. 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. 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. 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. 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. 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.

