Iterpec
API Iterpec

Cada serviço depende de contratação e habilitação próprias. Se Hotel, RentACar, Transfer, Tour, Flight, Insurance, Payment, ClientBackOffice ou Commons ainda não estiver contratado/habilitado, contate comercial@iterpec.com; acesso a um serviço não habilita os demais. Melhorias documentais preservam a URL base dinâmica https://ws.iterpec.com; Commons mantém seu endereço próprio.

Testes em produção: reservas reais e cancelamento obrigatório
API REST · v1.0

API Iterpec

Documentação completa da API REST para integração B2B de turismo. Permite buscar e reservar hotéis, aluguéis de carro, transfers e passeios, além de gerenciar reservas via backoffice.

🏨Hotel🚗RentACar🚌Transfer🎡Tour & Tickets
Fluxo em 3 passos
Search → GetBookingConditions → DoBooking para todos os produtos.
Token de sessão
Tokens retornados no Search são válidos por 30 minutos.
Suporte
helpdesk@iterpec.com para dúvidas operacionais.
FLUXO DE RESERVA
1
Dados Estáticos
AirportDetail
2
Autocomplete
DestinationId
3
Hotel Detail
Hotel Detail
4a
Search
Availability
4b
GetBookingConditions
Validate price
4c
DoBooking
Confirm
4d
Cancel
Trip / Service

Production-Ready Integration Checklist

O que separa uma POC de uma integração production-grade com a Iterpec. Use como gate antes de subir tráfego real.

🔐
Segurança & Compliance
  • ▸Bearer MCP em secret manager (nunca em repo)
  • ▸Credenciais Iterpec rotacionadas a cada 90 dias
  • ▸PCI: tokenização do cartão pelo gateway (sem PAN/CVV em log/DB)
  • ▸LGPD: mascarar documento e e-mail em logs
  • ▸mTLS opcional disponível para tráfego B2B
🔄
Idempotência & Concorrência
  • ▸Idempotency-Key (UUID v4) por DoBooking, persistida
  • ▸Lock distribuído por (HotelId+RoomIds+CheckIn+userId)
  • ▸Em timeout, reconciliar via GetBooking antes de retentar
  • ▸Máquina de estado persistente (PENDING/CONFIRMED/FAILED)
⏱️
Resiliência & Retries
  • ▸Backoff exponencial (250ms→500ms→1s→2s, máx 5)
  • ▸Respeitar header Retry-After em 429
  • ▸Circuit breaker por endpoint (abre após 3 falhas 5xx)
  • ▸Search multibroker: timeout rápido de 3s ou padrão de 6s; acima de 10s é muito lento. Ajustar timeout HTTP para acomodar espera e transporte.
📊
Observabilidade
  • ▸Log estruturado JSON por etapa (sem PII sensível)
  • ▸Trace ID propagado em todos os passos do fluxo
  • ▸Métricas: latência p50/p95/p99, taxa de OnRequest, conversão
  • ▸Alerta: PENDING > 24h, taxa de FAILED > 1%, 5xx em sequência
✅
Validação de Negócio
  • ▸GetBookingConditions SEMPRE < 5min antes de DoBooking
  • ▸Comparar TotalSellingPrice Search vs Conditions
  • ▸Tratar bookingStatus=FAILED dentro de HTTP 200
  • ▸Apresentar PropertyTaxes + MoreInformation integralmente
📅
Datas & Localização
  • ▸Todas as datas em ISO-8601 UTC no payload
  • ▸Conversão para fuso local APENAS na apresentação
  • ▸Idade exata para cada criança (não estimar)
  • ▸Nacionalidade e Residência em ISO-3166-1 alpha-2
Uptime SLA
99.9%
~43min/mês
Latência Search
< 2.5s p95
Multi-supplier
Token TTL
30 min
Rotativo por etapa
Rate limit
120 req/min
Por credencial
Modelo de maturidade — onde sua integração está?
L1 — POC

Search + DoBooking happy path. Sem retries, sem logs.

L2 — Beta

GetBookingConditions, tratamento de erros, logs básicos.

L3 — Production

Idempotência, retries, observabilidade, polling OnRequest.

L4 — Enterprise

Circuit breaker, multi-region, SLO alerts, reconciliação diária.

Datas, UTC e Boas Práticas

Todas as datas devem ser enviadas como string no formato ISO 8601. Nunca inclua informações de fuso horário nas datas, a menos que a documentação do campo específico indique o contrário.

CampoFormatoExemploObservação
Datas (CheckinDate, CheckoutDate, ServiceDate)YYYY-MM-DD2024-12-20Sempre no fuso horário local do destino.
Horários (Time, CheckInHour, CheckOutHour)HH:MM14:00Sempre em UTC. Converta para o fuso local ao exibir ao usuário.
Timestamps de resposta (TimeSpan)YYYY-MM-DD HH:MM:SS2024-12-20 14:30:58Sempre em UTC.
Datas em políticas de cancelamento (StartDate, EndDate)YYYY-MM-DD2024-12-15Representam o intervalo em que a penalidade se aplica (inclusive).
⚠️

CheckInHour e CheckOutHour são sempre em UTC. Converta para o fuso local do usuário antes de exibir.

ReToken e Revalidação de Disponibilidade

O **Token** do Search expira para uso em DoBooking, mas a **chave de ReToken** permanece válida por **25 horas**, permitindo revalidar a mesma busca sem refazer todo o Search. Objetivo do ReToken: **manter o mesmo Search original** (mesmos hotéis, mesmos quartos, mesmas datas), apenas confirmando se disponibilidade e preço se mantêm. Pode haver alterações — sempre tratar os três estados de retorno.

ReToken — Revalidação de Disponibilidade
Search
Gera Token + chave de ReToken (válida 25h)
Usuário volta?
Se dentro de 25h, use ReToken para manter a mesma busca
Não expirado
GetBookingConditions normal
Expirado (>25h)
Refaça o Search completo
RevalidateBookingConditions
SameRoomsFound / RoomsFoundWithChanges / RoomsNotFound
SameRoomsFound
Mesmo quarto encontrado

Disponibilidade e preço idênticos ao Search original. Prossiga normalmente para o DoBooking com o novo Token retornado.

RoomsFoundWithChanges
Quarto encontrado com alterações

O quarto ainda está disponível, mas houve mudança de preço ou de condições. Exiba as novas condições ao usuário antes de confirmar.

RoomsNotFound
Quarto não encontrado

O quarto não está mais disponível. Retorne ao Search para buscar novas opções. Nenhuma penalidade é aplicada.

Autenticação e Autorização

A API utiliza uma combinação de credenciais fixas (Username/Password) e tokens de sessão dinâmicos para autenticar e autorizar cada requisição.

1{
2  "Credential": {
3    "Username": "seu_usuario",
4    "Password": "sua_senha"
5  }
6}

Erros & Configurações

A API retorna códigos HTTP padrão. Todas as respostas são em JSON com compressão GZip disponível.

CódigoNomeDescrição
200OKA API retorna códigos HTTP padrão. Todas as respostas são em JSON com compressão GZip disponível.
400Bad RequestInvalid body — check required fields
401UnauthorizedInvalid credentials
404Not FoundResource not found
500Internal Server ErrorInternal error — contact support
Como Solicitar Suporte
📧 operacao@iterpec.com
Seg–Sex, 09:00–18:00 (GMT-3)
WhatsApp (fora do horário): +55 11 9 9501-4348
⚠️ Os contatos de voz/WhatsApp são exclusivos para emergências: queda de sistema ou erros no fluxo de reserva. Questões de integração são tratadas apenas por e-mail.

Status de Reserva

Cada reserva possui um status que reflete seu estado atual no sistema Cangooroo.

CONFIRMADO

Reserva confirmada, encaminhada ao hotel e com garantia de pagamento ao fornecedor.

CANCELADO

Após criação pendente: tentativa não criada e não cobrada. Em cancelamento solicitado de reserva criada: multas seguem a política. Distinguir os dois contextos.

REJEITADO

Tentativa não criada e não cobrada; tratar como cancelada. Pode ocorrer por idades das crianças divergentes entre pesquisa/reserva, indisponibilidade ou mudança de preço.

PENDENTE

Resultado incerto: acompanhar a cada 5 minutos e consultar operacao@iterpec.com até Confirmed ou Cancelled. Não reenviar DoBooking.

PROBLEMA TÉCNICO

Resultado incerto, como Pending ou erro 501. Não criar nova reserva; consultar operacao@iterpec.com e GetBookingDetail a cada 5 min até Confirmed ou Cancelled.

SOLICITAÇÃO DE RESERVA

Ocorre quando o cadastro do cliente está bloqueado por falta de crédito disponível.

AGUARDANDO PAGAMENTO

Conteúdo pré-pago com tarifa em penalidade. O sistema aguarda pagamento via cartão.

PROBLEMA NO CANCELAMENTO

Alguma conexão não comunicou o cancelamento ao fornecedor. Envie e-mail para comercial@iterpec.com.

EM PROGRESSO

Status de transição. Use GetBookingDetail para recuperar o status real.

1

Dados Estáticos

Dados de destinos, aeroportos e conteúdo base que raramente mudam. Recomendado atualizar a cada 30 dias e armazenar em cache local.

GET🌐Geral

DestinationHierarchy

GEThttps://commons.t4w.com.br/new/api/v1/mapping/destination-hierarchy/managerid/{managerId}/token/{token}
💡 Contrato publicado em https://api-doc.cangooroo.com/, adaptado à URL Iterpec. Comparação documental, não validação real nem habilitação do serviço. Serviço não contratado? comercial@iterpec.com. Exemplos são ilustrativos; não executar reservas sem segurança comprovada.
Hierarquia de destinos para seleção geográfica e persistência local. Usar IDs retornados, não inventar IDs. Catálogo leve GraphQL continua sendo a fonte preferida para carga completa rápida.

URL Parameters

NomeTipoReq.Descrição
managerIdintegerreqManager Iterpec: 270
tokenstringreqToken próprio Commons
parentIdnumberoptFiltro opcional de pai

Response Fields

NomeTipoReq.Descrição
DestinationIdintegeroptID do destino
NamestringoptNome
TypestringoptTipo geográfico
Childrenarray[object]optFilhos da hierarquia; exemplo publicado, validar resposta real
1{}
GET🌐Geral

AirportDetail

GEThttps://commons.t4w.com.br/new/api/v1/mapping/airport/iata/{IATA}/manager/{managerId}/token/{token}
Busca dados detalhados de um aeroporto pelo código IATA. Útil para exibir informações de origem/destino em buscas de transfer e pacotes.

URL Parameters

NomeTipoReq.Descrição
IATAstringreqCódigo IATA do aeroporto
ex: GRU
tokenstringreqToken de acesso
ex: SEU_TOKEN_ITERPEC
managerIdintegerreqID do manager
ex: 270
1{}
2

Autocomplete

Sugestões em tempo real de destinos, hotéis e pontos de interesse. Ideal para campos de busca com digitação progressiva.

3

Enriquecer dados estáticos com Hotel Detail

Enriquece os dados de um hotel com fotos, geolocalização, amenities e informações de quartos. Use o HotelId retornado pelo Autocomplete ou pelo Search.

GET🏨Hotel

HotelDetail

GEThttps://commons.t4w.com.br/new/api/v1/mapping/hotel/{hotelId}/token/{token}
Sincronizar fotos, textos multilíngues, geolocalização, amenities e quartos no cache do cliente. Carga inicial com retomada, três hotéis/minuto e no máximo uma nova sincronização/dia; depois atualizar mensalmente apenas novos/alterados por lastUpdateSource no GraphQL. Não requisitar em massa durante pesquisa. Consulta individual em tempo real, quando necessária, vai diretamente à Commons conforme limites contratados. IDs de fotos/quartos não garantem mapeamento universal; validar nomes, vista e camas.

URL Parameters

NomeTipoReq.Descrição
hotelIdintegerreqID do hotel (retornado pelo Autocomplete ou Search)
ex: 160459
tokenstringreqToken de acesso
ex: SEU_TOKEN_ITERPEC
managerIdintegerreqID do manager
ex: 270

Response Fields

NomeTipoReq.Descrição
idintegeroptID do hotel
destinationobjectoptDados do destino com nome multilíngue
namestringoptNome do hotel
addressstringoptEndereço completo
latitudenumberoptLatitude geográfica
longitudenumberoptLongitude geográfica
categorystringoptCategoria em estrelas (1–5)
amenitiesarray[string]optLista de comodidades do hotel
photosarray[string]optURLs das fotos do hotel
roomsarray[object]optDados dos tipos de quarto com fotos e amenities
1{}

Payment

Pagamento de reservas via cartão de crédito. Utilizado quando `IsPrePayment: true` no Search.

POST💳Payment

GetPaymentConditionsByBookingId

POSThttps://ws.iterpec.com/API/REST/Payment.svc/GetPaymentConditionsByBookingId
💡 Contrato publicado em https://api-doc.cangooroo.com/, adaptado à URL Iterpec. Comparação documental, não validação real nem habilitação do serviço. Serviço não contratado? comercial@iterpec.com. Exemplos são ilustrativos; não executar reservas sem segurança comprovada.
Consultar condições antes de escolher método e parcelas para reserva existente.

Request Body

NomeTipoReq.Descrição
CredentialobjectreqUsuário e senha de produção específicos deste cliente; não enviar nem registrar em logs.
BookingIdstringreqID de reserva existente
1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "BookingId": "{{BookingId}}"
7}
POST💳Payment

getPaymentConditionByToken

POSThttps://ws.iterpec.com/API/REST/Payment.svc/getPaymentConditionByToken
💡 Contrato publicado em https://api-doc.cangooroo.com/, adaptado à URL Iterpec. Comparação documental, não validação real nem habilitação do serviço. Serviço não contratado? comercial@iterpec.com. Exemplos são ilustrativos; não executar reservas sem segurança comprovada.
Consultar condições de pagamento antes de criar a reserva. Não confundir com token MCP/Commons.

Request Body

NomeTipoReq.Descrição
CredentialobjectreqUsuário e senha de produção específicos deste cliente; não enviar nem registrar em logs.
TokenstringreqToken vigente das condições
1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "Token": "{{Token}}"
7}
POST💳Payment

payBooking

POSThttps://ws.iterpec.com/API/REST/Payment.svc/payBooking
💡 Contrato publicado Cangooroo adaptado à URL Iterpec; confirmar formato habilitado antes de migrar integração. Não validado por pagamento real. Nunca guardar cartão ou CVV.
Realiza o pagamento de uma reserva via cartão de crédito. Utilizado quando `IsPrePayment` é `true` no retorno do Search.

Request Body

NomeTipoReq.Descrição
CredentialobjectreqUsuário e senha de produção específicos deste cliente; não enviar nem registrar em logs.
BookingIdstringreqReserva existente
ContractingPartyobjectreqDados do contratante na raiz, não dentro de PaymentRequestCC1.
CreditCardobjectreqDados do cartão apenas no envio autorizado; nunca armazenar SecurityCode ou registrar cartão em logs.
ServicesIdarrayoptOpcional; omitir paga todos os serviços, preencher restringe aos serviços escolhidos.
RetainCommissionbooleanoptRetenção de comissão conforme contrato
SmartCommissionValuenumberoptValor de comissão conforme contrato
1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "BookingId": "{{BookingId}}",
7  "ContractingParty": {
8    "PersonName": "{{PersonName}}",
9    "CPF": "{{CPF}}",
10    "Email": "{{Email}}",
11    "Address": "{{Address}}",
12    "AddressComplement": "{{AddressComplement}}",
13    "AddressNumber": "{{AddressNumber}}",
14    "CityName": "{{CityName}}",
15    "CountryCode": "{{CountryCode}}",
16    "DistrictName": "{{DistrictName}}",
17    "PhoneNumber": "{{PhoneNumber}}",
18    "PhoneNumberDDD": "{{PhoneNumberDDD}}",
19    "PhoneNumberDDI": "{{PhoneNumberDDI}}",
20    "StateCode": "{{StateCode}}",
21    "ZipCode": "{{ZipCode}}",
22    "ReceiveCreditCardReceipt": "false"
23  },
24  "CreditCard": {
25    "Holder": "{{Holder}}",
26    "CardNumber": "{{CardNumber}}",
27    "SecurityCode": "{{SecurityCode}}",
28    "MonthExpiration": 12,
29    "YearExpiration": 2028,
30    "NumberPayments": 1,
31    "CardOperator": "{{CardOperator}}"
32  }
33}

ClientBackOffice

Gestão e consulta de reservas. Use GetBookingList para monitorar alterações e GetBookingDetail para atualizar dados.

POST📋BackOffice

authenticate

POSThttps://ws.iterpec.com/API/REST/ClientBackOffice.svc/authenticate
💡 Contrato publicado em https://api-doc.cangooroo.com/, adaptado à URL Iterpec. Comparação documental, não validação real nem habilitação do serviço. Serviço não contratado? comercial@iterpec.com. Exemplos são ilustrativos; não executar reservas sem segurança comprovada.
Autenticação ClientBackOffice documentada; credenciais do próprio cliente, não conta corporativa Iterpec.

Request Body

NomeTipoReq.Descrição
UsernamestringreqUsuário do cliente
PasswordstringreqSenha do cliente
1{}
POST📋BackOffice

getLastFXRate

POSThttps://ws.iterpec.com/API/REST/ClientBackOffice.svc/getLastFXRate
💡 Contrato publicado em https://api-doc.cangooroo.com/, adaptado à URL Iterpec. Comparação documental, não validação real nem habilitação do serviço. Serviço não contratado? comercial@iterpec.com. Exemplos são ilustrativos; não executar reservas sem segurança comprovada.
Consultar referência cambial; não altera a moeda/condições vinculadas à credencial.

Request Body

NomeTipoReq.Descrição
CredentialobjectreqUsuário e senha de produção específicos deste cliente; não enviar nem registrar em logs.
CurrencyCodeFromstringreqMoeda ISO de origem
CurrencyCodeTostringreqMoeda ISO de destino
ServiceTypenumberreqCódigo do tipo de serviço habilitado
1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "CurrencyCodeFrom": "USD",
7  "CurrencyCodeTo": "BRL",
8  "ServiceType": 1
9}
POST📋BackOffice

getIncidents

POSThttps://ws.iterpec.com/API/REST/ClientBackOffice.svc/getIncidents
💡 Contrato publicado em https://api-doc.cangooroo.com/, adaptado à URL Iterpec. Comparação documental, não validação real nem habilitação do serviço. Serviço não contratado? comercial@iterpec.com. Exemplos são ilustrativos; não executar reservas sem segurança comprovada.
Ocorrências exclusivamente das reservas acessíveis ao cliente; não substitui reconciliação de status.

Request Body

NomeTipoReq.Descrição
CredentialobjectreqUsuário e senha de produção específicos deste cliente; não enviar nem registrar em logs.
IncidentobjectreqWrapper obrigatório, filtros opcionais
1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "Incident": {
7    "BookingId": "{{BookingId}}"
8  }
9}
POST📋BackOffice

creatIncident

POSThttps://ws.iterpec.com/API/REST/ClientBackOffice.svc/creatIncident
💡 Contrato publicado em https://api-doc.cangooroo.com/, adaptado à URL Iterpec. Comparação documental, não validação real nem habilitação do serviço. Serviço não contratado? comercial@iterpec.com. Exemplos são ilustrativos; não executar reservas sem segurança comprovada.
Cria ocorrência com credenciais do cliente. Confirmar habilitação; não assumir alteração de reserva ou abertura corporativa.

Request Body

NomeTipoReq.Descrição
CredentialobjectreqUsuário e senha de produção específicos deste cliente; não enviar nem registrar em logs.
IncidentobjectreqGrafia creatIncident publicada; não inventar createIncident
1{}
POST📋BackOffice

addIncidentMessage

POSThttps://ws.iterpec.com/API/REST/ClientBackOffice.svc/addIncidentMessage
💡 Contrato publicado em https://api-doc.cangooroo.com/, adaptado à URL Iterpec. Comparação documental, não validação real nem habilitação do serviço. Serviço não contratado? comercial@iterpec.com. Exemplos são ilustrativos; não executar reservas sem segurança comprovada.
Adicionar mensagem somente a ocorrência autorizada do próprio cliente.

Request Body

NomeTipoReq.Descrição
CredentialobjectreqUsuário e senha de produção específicos deste cliente; não enviar nem registrar em logs.
IncidentMessageobjectreqMensagem para ocorrência existente
1{}
POST📋BackOffice

GetBookingDetail

POSThttps://ws.iterpec.com/API/REST/ClientBackOffice.svc/GetBookingDetail
💡 GetBookingDetail por BookingId a cada 5 minutos para Pending/TechnicalProblem/501. Resultado incerto não autoriza nova reserva; consultar operacao@iterpec.com.
Obtém dados detalhados de uma reserva e **atualiza seu status** com o estado mais recente do fornecedor. É o método central para resolver reservas em estados ambíguos. Além de retornar dados para faturamento, voucher, HCN, link de check-in e informações adicionais quando enviados pelo fornecedor, cada chamada sincroniza o status da reserva com o fornecedor. Isso torna o método essencial para monitoramento automático via polling.

Request Body

NomeTipoReq.Descrição
CredentialobjectreqCredenciais de acesso
BookingIdstringreqID da reserva (ReservationId)
ex: "1864605"

Response Fields

NomeTipoReq.Descrição
BookingobjectoptDados completos da reserva
⚠️
Resultado incerto não é reserva rejeitada
8. GetBookingDetail por BookingId → Confirmed confirma; Rejected equivale a Cancelled/não criada, não cobrada. Pending/TechnicalProblem/501: resultado incerto, consultar operacao@iterpec.com e acompanhar a cada 5 minutos até Confirmed ou Cancelled. Cancelled após tentativa pendente não significa cancelamento solicitado; só após resolução iniciar nova reserva. Atualizar HCN, link de check-in e outras informações quando chegarem; voucher por BookingId-ServiceId.
📊 Decisão após DoBooking
ResultadoSignificadoAção
ConfirmedReserva criada e confirmada.Emitir voucher; consultar detalhes posteriores para HCN e link de check-in.
RejectedTentativa não criada; equivale a Cancelled, não cobrada.Conferir idades das crianças, disponibilidade e preço; oferecer nova pesquisa.
Pending / TechnicalProblem / 501Não se sabe se a reserva foi criada. Analogia operacional ao erro 501, não prova de rejeição.E-mail para operacao@iterpec.com; GetBookingDetail por BookingId a cada 5 minutos até Confirmed ou Cancelled. Não reenviar às cegas.
Cancelled após criação pendenteTentativa não criada e não cobrada; não foi cancelamento solicitado pelo cliente.Resultado resolvido: pode iniciar nova reserva.
PendingCancellationCancelamento solicitado ainda sem resolução.Consultar Operação e acompanhar; não confundir com falha de criação. Multas seguem a política da reserva.
📋 Acompanhamento persistente, sem prazo de confirmação inventado
Agendar consultas a cada 300.000 ms (5 minutos) em fila persistente. Status ausente/desconhecido, erro de rede ou fim de uma janela interna de monitoramento NÃO significa Cancelled: manter resultado incerto e encaminhar a Operação. Não prometer resolução em 30 minutos ou atendimento em 2 horas. Registrar somente identificadores e estados, sem credenciais, cartão ou dados pessoais.
📋 Informações que podem chegar depois
Atualizar dados de GetBookingDetail também após a confirmação para obter HCN (Hotel Confirmation Number), link de check-in e outras informações adicionais, conforme os campos realmente retornados pelo fornecedor. HCN pode não estar presente na primeira resposta. Não inventar nome de campo para o link de check-in.
1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "BookingId": "1864605"
7}
POST📋BackOffice

GetBookingList

POSThttps://ws.iterpec.com/API/REST/ClientBackOffice.svc/GetBookingList
Recupera lista de reservas que sofreram alteração de status, valor, período ou dados dos passageiros.

Request Body

NomeTipoReq.Descrição
CredentialobjectreqCredenciais de acesso
SearchBookingCriteriaobjectreqWrapper obrigatório; seus filtros são opcionais
1{
2  "Credential": {
3    "Password": "{{minhasenha}}",
4    "Username": "{{meuusuario}}"
5  },
6  "SearchBookingCriteria": {
7    "BookingNumber": [],
8    "InitialServiceDate": "2024-01-01",
9    "FinalServiceDate": "2024-01-31"
10  }
11}
PRD · UX OTAget_reference({topic:'rate_selectors'})

Seletores de Tarifa estilo OTA

Cancelamento × Regime de alimentação são dependentes em cascata (igual Expedia/Hotels.com), não paralelos. O card mostra sempre o cheapest da interseção e o seletor de meal só exibe opções que existem para o cancelamento escolhido. Default = combinação mais barata absoluta do hotel.

Demo interativo

Hotel Orlando Full Range

Matriz completa — todas as políticas, vários meals

a partir deR$ 380/noite

Política de cancelamento

Regime de alimentação

Não reembolsávelSem café
R$ 380

Tente:

  • Trocar cancelamento — a lista de meals se ajusta automaticamente.
  • Selecione "Cancún AI-only" — só meal AI aparece em qualquer política.
  • Selecione "Búzios" — Free cancellation fica disabled (não existe).

Snippet completo (copiável)

// 1. Tipos
type CancellationType = 'free' | 'partial' | 'non_refundable';
type MealCode = 'RO' | 'BB' | 'HB' | 'FB' | 'AI';

interface RateMatrix {
  matrix: Record<CancellationType, Partial<Record<MealCode, RoomCombination>>>;
  availableCancellations: CancellationType[];
  availableMealsByCancellation: Record<CancellationType, MealCode[]>;
  cheapestOverall: RoomCombination;
}

// 2. Construção O(n) sobre as combinations do Search
function buildRateMatrix(combinations: RoomCombination[]): RateMatrix {
  const matrix = { free: {}, partial: {}, non_refundable: {} };
  let cheapestOverall = combinations[0];
  for (const c of combinations) {
    const cancel = c.cancellationPolicy.type;
    const meal = c.mealPlan.code;
    const current = matrix[cancel][meal];
    if (!current || c.bestPrice.amount < current.bestPrice.amount) {
      matrix[cancel][meal] = c;
    }
    if (c.bestPrice.amount < cheapestOverall.bestPrice.amount) cheapestOverall = c;
  }
  const availableCancellations = Object.keys(matrix)
    .filter(k => Object.keys(matrix[k]).length > 0);
  const availableMealsByCancellation = Object.fromEntries(
    availableCancellations.map(k => [
      k,
      Object.keys(matrix[k]).sort(
        (a, b) => matrix[k][a].bestPrice.amount - matrix[k][b].bestPrice.amount
      ),
    ])
  );
  return { matrix, availableCancellations, availableMealsByCancellation, cheapestOverall };
}

// 3. Comportamento dos seletores (React)
function HotelCard({ combinations }) {
  const rate = useMemo(() => buildRateMatrix(combinations), [combinations]);
  const [cancel, setCancel] = useState(rate.cheapestOverall.cancellationPolicy.type);
  const [meal, setMeal] = useState(rate.cheapestOverall.mealPlan.code);

  const availableMeals = rate.availableMealsByCancellation[cancel];
  const effectiveMeal = availableMeals.includes(meal) ? meal : availableMeals[0];
  const selected = rate.matrix[cancel][effectiveMeal];

  function onCancelChange(next) {
    setCancel(next);
    const meals = rate.availableMealsByCancellation[next];
    if (!meals.includes(meal)) setMeal(meals[0]); // auto-relaxar
  }
  // ... render chips: cancelamento (todos visíveis, indisponíveis disabled),
  //               meal (apenas os disponíveis para o cancel escolhido)
}

Faça

  • • Cascata: meal depende do cancelamento escolhido.
  • • Cancelamentos sempre visíveis (disabled quando faltar) com tooltip.
  • • Auto-relaxe meal para a mais barata do novo conjunto.
  • • Exiba "+R$ X vs. tarifa mais barata" quando ≠ cheapestOverall.
  • • Badges sempre visíveis (Reembolsável, Café, AI, Cancele até DD/MM).

Evite

  • • Mostrar 5 meals sempre, sem oferta real.
  • • Seletores paralelos independentes sem cascata.
  • • Esconder cancelamentos indisponíveis (em vez de disabled).
  • • Recalcular cheapest no servidor a cada clique.
  • • Default arbitrário (ex.: free+BB) em vez de cheapestOverall.
⚡

Conecte sua IA à Iterpec em 2 minutos

Plugue nosso servidor MCP em 19+ clientes de IA (Claude, Cursor, Windsurf, Cline, Zed, ChatGPT, n8n…) e seu agente passa a consultar endpoints, montar payloads, ler o changelog e seguir as regras de reserva sozinho. Sem ticket, sem reunião de onboarding. Copie a configuração, cole no seu cliente, comece a integrar.

!
Pré-requisito — virar cliente Iterpec

Para usar MCP, Skills e Vibecoding em produção (chamar Search, GetBookingConditions, DoBooking de verdade) você precisa de 2 credenciais:

  • Bearer Token do MCP — autentica seu agente de IA contra https://iterpec.com/api/mcp.
  • Username + Password da API Iterpec — enviados no body de cada chamada produtiva (Credential.Username / Credential.Password). Sem eles, os endpoints de Search/Booking respondem 401.

Ambas são liberadas só após preencher o formulário comercial e assinar contrato com a Iterpec. Antes disso, o MCP responde apenas documentação (schema, exemplos, changelog) — útil para prototipar, mas sem acesso ao inventário real.

Endpoint
POST https://iterpec.com/api/mcp
Transport: Streamable HTTP (MCP 2025-06-18). Apenas POST é aceito.
Autenticação (2 camadas)
Authorization: Bearer <imcp.xxx.yyy>
1) Bearer no header — autentica o MCP.
2) Username + Password no body — autenticam a API de produção.
Solicite os dois a comercial@iterpec.com após assinar contrato. Nunca comite no código — use variável de ambiente / secret manager.

Tools disponíveis

NomeDescriçãoParâmetros
list_endpointsLista grupos e endpoints da API (com filtro opcional por produto ou termo).product?, search?
get_endpointDetalhes completos de um endpoint: parâmetros, exemplo curl e resposta.endpointId
get_changelogNotas de release da API Cangooroo, ordem cronológica decrescente.service?, since?, limit?
get_referenceFluxo de reserva, status, ReToken e convenções de data/UTC.topic ("booking_statuses" | "retoken" | "date_conventions" | "all")
Homologação por etapa (sandbox + revisão humana)

Antes de ir para produção, cada cliente prova etapa por etapa que respeita as regras críticas (idempotency, taxas locais, multi-quarto, polling, ReToken). Cada etapa é aprovada ou reprovada de forma independente — você pode submeter cancel antes de aprovar booking.

  1. get_homologation_checklist — provas exigidas por etapa.
  2. validate_step_payload — validação local determinística (gratuita, ilimitada).
  3. submit_step_for_homologation — envia evidência (PII mascarada) para revisão.
  4. get_homologation_status — status por etapa com motivo e correção exigida.
  5. get_certificate — emitido após todas as etapas obrigatórias aprovadas.

Etapas obrigatórias para certificado: search_detail, conditions, booking, detail, cancel. Opcionais: search_quick, multi_room. Requer token MCP assinado (formato imcp.*).

Prefere UI? Use o sandbox web em /sandbox — mesma validação determinística, mesmo fluxo de revisão, sem precisar de cliente MCP.

⇢

Diagramas canônicos — passo a passo da integração

Mapa visual de quem chama o quê, em qual ordem, com qual token, e como o endpoint do Iterpec WS muda em 01/07/2026. As mesmas fontes Mermaid estão expostas em get_reference{topic:'flow_diagrams'} para que a IA cliente possa pedi-las direto.

Quem chama o quê, em que ordem, com qual token.

Renderizando diagrama…
Ver fonte Mermaid (copiar e colar em qualquer editor)
sequenceDiagram
    autonumber
    participant U as Usuário final
    participant C as Client App (IA integradora)
    participant M as MCP Server<br/>iterpec.com/api/mcp
    participant W as Iterpec WS<br/>(host por data)
    Note over C,M: Auth MCP: Bearer imcp.* ou wsk_*
    Note over C,W: Auth WS: Username + Password → ReToken 25h
    C->>M: tools/call start_here
    M-->>C: Mapa de tools + system_instructions
    C->>M: tools/call get_reference{topic:"api_endpoint"}
    M-->>C: Host correto (até/após 01-07-2026)
    Note over C: Catálogo GraphQL local e HotelDetail cacheado de todos os hotéis
    U->>C: Destino ou endereço + raio, datas e hóspedes
    C->>W: Search descoberta (DestinationId OU HotelIds, cheapestRoomOnly=true)
    W-->>C: Menor preço por hotel + Token de descoberta
    Note over C: Descartar Token da descoberta
    U->>C: Escolhe hotel
    C->>W: Search (HotelIds=[id], cheapestRoomOnly=false)
    W-->>C: Todos os quartos e tarifas + Token da sessão
    U->>C: Escolhe quarto e tarifa
    C->>W: GetBookingConditions (Token vigente, quarto selecionado)
    W-->>C: book, políticas, taxas, nomes/endereço, revalidação
    alt book=false ou RoomsNotFound
        Note over C: Excluir ID da oferta inválida na sessão
        C->>W: Search mesmo hotel false, mesmas datas e ocupação
        W-->>C: Novas ofertas e novo Token
        C-->>U: Tarifa indisponível, escolher nova oferta e revalidar
    else Oferta disponível
        opt Quarto ou condições mudaram
            C-->>U: Original indisponível, apresentar substituto e condições
            U->>C: Aceite explícito
        end
        Note over C: isBilled=true sem cartão, false exige cartão. Mesmas idades das crianças
        C->>W: DoBooking (Token vigente, Idempotency-Key)
        W-->>C: BookingId + ServiceIds + status
        loop Pending, TechnicalProblem ou 501: cada 5 minutos até resolução
            Note over C: Não reenviar DoBooking, consultar Operação por e-mail
            C->>W: GetBookingDetail (BookingId)
            W-->>C: Confirmed OU Cancelled
        end
        alt Confirmed
            C-->>U: Reserva confirmada e voucher do cliente B2B
            Note over C: Detalhes posteriores podem trazer HCN e link de check-in
        else Rejected ou Cancelled após criação pendente
            C-->>U: Tentativa não criada e não cobrada, pode iniciar nova reserva
        end
    end
    opt Cancelamento solicitado de reserva criada
        C->>W: CancelAllHotelServices (BookingId) OU CancelByService (ServiceIds[])
        W-->>C: Status e multas conforme políticas
    end
Tokens — camada MCP
  • imcp.<ws>.<sig> — assinado pelo admin, para IAs (Claude/Cursor).
  • wsk_<secret> — token de workspace, para CI/CD e scripts.
  • Sempre em Authorization: Bearer … contra iterpec.com/api/mcp.
Tokens — camada Iterpec WS (produção)
  • Username + Password obtidos via contrato comercial.
  • ReToken com TTL 25h — renovar antes de expirar.
  • Host até 01/07/2026: iterpec-ws.cangooroo.net; após: ws.iterpec.com.
Regras que a IA cliente NÃO pode esquecer
  • 1 BookingId pode conter N ServiceIds (multi-quarto).
  • DoBooking SEMPRE com Idempotency-Key UUID v4 (TTL 24h).
  • GBC repetível: book=false bloqueia; diferenças de hotel/endereço/quarto e condições exigem aceite explícito.
  • ReToken renova ANTES de expirar (25h); não esperar 401.
  • Voucher usa SEMPRE GetBookingDetail, nunca a resposta de DoBooking diretamente.
  • Branding e central 24/7 no voucher são SEMPRE do cliente B2B — nunca expor 'Iterpec' ao hóspede final.
  • hidePackageRate é decisão por canal/sessão: true em B2C hotel puro, false em B2C pacote e B2B.
▶

Playground MCP — Try it

Execute chamadas JSON-RPC reais contra /api/mcp sem precisar instalar Claude Desktop ou Cursor. Cole seu token (imcp.* ou wsk_*), liste as tools, escolha uma, edite os argumentos JSON e clique Executar. O token fica apenas em sessionStorage (some ao fechar a aba).

Exemplos prontos

Dica: tokens imcp.* recebem headers Deprecation/Sunset a partir de 30/09/2026. Se vir HTTP 429, respeite o Retry-After.

⇄

Corporate Approval — Simulador de cenários

Visualize a timeline didática dos dois fluxos descritos por get_reference{topic:'corporate_approval'}: reserva primeiro (fora da penalidade) ou aprovar primeiro com polling GBC (em penalidade). Esta simulação é local — não chama a API.

Timeline de ações
  1. 00:00Search → seleção da oferta
    Preço inicial R$ 842.30 · janela de cancelamento grátis até check-in -3d
  2. 00:01DoBooking imediato
    Como está fora da penalidade, reserva primeiro (custo zero se cancelar antes da janela).
  3. 00:02Envia para aprovação corporativa
    BookingId persistido. Notifica aprovador. Sem polling GBC nesta fase.
  4. 04:12Aprovador aprova
    Reserva permanece confirmada. Gerar voucher com dados do GetBookingDetail.
  5. 04:13Voucher emitido
    Branding e central 24/7 do cliente B2B (nunca expõe Iterpec ao hóspede).

Regra dura: em tarifa não-reembolsável, NUNCA executar DoBooking antes da aprovação; sempre fazer GetBookingConditions fresh (<5 min) na abertura da tela do aprovador e exibir o diff de preço/quarto.

Teste rápido via cURL (tools/list)

Prefere terminal? Faça o handshake JSON-RPC direto. Substitua SEU_TOKEN_AQUI.

curl --location 'https://iterpec.com/api/mcp' \
  --header 'Authorization: Bearer SEU_SHARED_SECRET_AQUI' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Disponibilidade e SLO em tempo real em /status. Métricas Prometheus para observabilidade externa em GET /api/public/mcp-metrics (Bearer ITERPEC_MCP_METRICS_TOKEN).

Configuração por cliente

19 clientes MCP suportados. Clique no logo para ver a configuração específica.

Claude DesktopConfiguração para Claude Desktop · App nativo Anthropic
{
  "mcpServers": {
    "iterpec-api": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://iterpec.com/api/mcp",
        "--header", "Authorization:${ITERPEC_MCP_TOKEN}"
      ],
      "env": { "ITERPEC_MCP_TOKEN": "Bearer SEU_TOKEN_AQUI" }
    }
  }
}
Notas: o servidor exige o header Accept: application/json, text/event-stream em todas as requisições POST (padrão MCP Streamable HTTP). Apenas o método POST é aceito; GET/DELETE retornam 405. O shared secret é validado por comparação direta — rotacione pelo painel de secrets quando necessário.

© 2026 Iterpec · comercial@iterpec.com