IPAPI Reference

search⌘K

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

Dados Estáticos

AirportDetail

Autocomplete

DestinationId

Hotel Detail

Hotel Detail

Search

Availability

GetBookingConditions

Validate price

DoBooking

Confirm

Cancel

Trip / Service

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.

Campo	Formato	Exemplo	Observação
Datas (CheckinDate, CheckoutDate, ServiceDate)	`YYYY-MM-DD`	`2024-12-20`	Sempre no fuso horário local do destino.
Horários (Time, CheckInHour, CheckOutHour)	`HH:MM`	`14:00`	Sempre em UTC. Converta para o fuso local ao exibir ao usuário.
Timestamps de resposta (TimeSpan)	`YYYY-MM-DD HH:MM:SS`	`2024-12-20 14:30:58`	Sempre em UTC.
Datas em políticas de cancelamento (StartDate, EndDate)	`YYYY-MM-DD`	`2024-12-15`	Representam 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** retornado pelo Search é válido por **30 minutos**. Se o usuário demorar mais do que isso para avançar para o GetBookingConditions, o token expira. Nesse cenário, o sistema utiliza o **ReToken** — um mecanismo de revalidação automática que verifica se o quarto ainda está disponível e se o preço se manteve, sem necessidade de refazer o Search completo.

ReToken — Revalidação de Disponibilidade

Token gerado (válido 30 min)

Token expirado?

Verificação automática

Não expirado

GetBookingConditions normal

Expirado

ReToken ativado automaticamente

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ódigo	Nome	Descrição
200	OK	A API retorna códigos HTTP padrão. Todas as respostas são em JSON com compressão GZip disponível.
400	Bad Request	Invalid body — check required fields
401	Unauthorized	Invalid credentials
404	Not Found	Resource not found
500	Internal Server Error	Internal error — contact support

Como Solicitar Suporte

📧 support@cangooroo.net

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

Reserva cancelada. Cobranças de penalidade continuam se aplicáveis.

REJEITADO

Falta de disponibilidade, mudança de tarifa, timeout do fornecedor ou nomes com caracteres especiais. Refaça a reserva sem risco de penalidade.

PROBLEMA TÉCNICO

Timeout no recebimento do número de confirmação. Em 70% dos casos a reserva está confirmada. Não crie nova reserva — consulte helpdesk@iterpec.com.

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 helpdesk@iterpec.com.

EM PROGRESSO

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

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

AirportDetail

GEThttp://commons.t4w.com.br/new/api/v1/mapping/airport/{airportCode}/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

Nome	Tipo	Req.	Descrição
airportCode	string	req	Código IATA do aeroporto `ex: GRU`
token	string	req	Token de acesso `ex: aac7faba-ca30-4071-a18a-41cda1424bdc`
managerId	integer	req	ID do manager `ex: 270`

1{}

Arquivos de Dados Estáticos

Dados que não mudam com frequência (nomes de hotéis, endereços, coordenadas, IDs de destino) estão disponíveis para download. Recomendamos atualizar esses arquivos a cada 30 dias.

🏨

HotéisZIP

Lista completa de hotéis com IDs, nomes, destinos e categorias. Atualizar a cada 30 dias.

📍

DestinosZIP

Lista de destinos com IDs, nomes multilíngues e códigos de país.

🚗

Locadoras de AutomóveisZIP

Lista de locadoras com lojas, endereços, horários e códigos de aeroporto.

📄

Descritivos de Hotéis — PortuguêsZIP

Textos descritivos completos de hotéis em português (amenities, políticas, descrição geral).

📄

Descritivos de Hotéis — InglêsZIP

Textos descritivos completos de hotéis em inglês.

📄

Descritivos de Hotéis — EspanholZIP

Textos descritivos completos de hotéis em espanhol.

Autocomplete

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

GET🌐Geral

Autocomplete

GEThttp://commons.t4w.com.br/new/api/v1/mapping/autocomplete/all/{any_term}/managerId/{managerId}/token/{token}

Insira qualquer termo com ao menos **3 caracteres**. Retorna opções de destinos, hotéis ou pontos de interesse. Exemplo: use `"miam"` para buscar Miami. O resultado inclui o `DestinationId` necessário para o Search de hotéis.

URL Parameters

Nome	Tipo	Req.	Descrição
any_term	string	req	Termo de busca (mínimo 3 caracteres) `ex: miam`
managerId	integer	req	ID do manager `ex: 270`
token	string	req	Token de acesso `ex: aac7faba-ca30-4071-a18a-41cda1424bdc`

Response Fields

Nome	Tipo	Req.	Descrição
id	integer	opt	ID do destino ou hotel
type	string	opt	Tipo do resultado: Destination ou Hotel
name	string	opt	Nome do destino ou hotel
countryCode	string	opt	Código ISO do país
destinationId	integer	opt	ID do destino (quando type = Hotel)

1{}

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

GEThttp://commons.t4w.com.br/new/api/v1/mapping/hotel/{hotelId}/token/{token}

Busca fotos, dados completos, geolocalização, fotos de quarto (se disponível) e amenities do hotel e dos quartos. Este endpoint é chamado **após** o Autocomplete ou o Search para enriquecer a exibição do hotel ao usuário antes da reserva.

URL Parameters

Nome	Tipo	Req.	Descrição
hotelId	integer	req	ID do hotel (retornado pelo Autocomplete ou Search) `ex: 160459`
token	string	req	Token de acesso `ex: aac7faba-ca30-4071-a18a-41cda1424bdc`
managerId	integer	req	ID do manager `ex: 270`

Response Fields

Nome	Tipo	Req.	Descrição
id	integer	opt	ID do hotel
destination	object	opt	Dados do destino com nome multilíngue
name	string	opt	Nome do hotel
address	string	opt	Endereço completo
latitude	number	opt	Latitude geográfica
longitude	number	opt	Longitude geográfica
category	string	opt	Categoria em estrelas (1–5)
amenities	array[string]	opt	Lista de comodidades do hotel
photos	array[string]	opt	URLs das fotos do hotel
rooms	array[object]	opt	Dados dos tipos de quarto com fotos e amenities

1{}

Chamadas Dinâmicas

filtro por produto

Exibindo endpoints de:🏨 Hotel

Search

🏨Hotel— Primeiro passo do fluxo dinâmico. Busca disponibilidade em tempo real para hotéis, carros, transfers e passeios.

POST🏨Hotel1° passo

Search

POSThttps://ws.iterpec.com/API/REST/Hotel.svc/Search

Busca disponibilidade de hotéis em tempo real. O **Token** retornado deve ser armazenado e utilizado nos próximos passos. Válido por **30 minutos**. `CheapestRoomOnly: true` retorna apenas o quarto mais barato por hotel. `HidePackageRate: false` inclui tarifas de pacote.

Request Body

Nome	Tipo	Req.	Descrição
Credential	object	req	Credenciais de acesso
Criteria	object	req	Critérios de busca

Response Fields

Nome	Tipo	Req.	Descrição
Token	string	opt	Token de sessão (válido 30 min). Obrigatório nos próximos passos.
TimeSpan	string	opt	Data e hora da pesquisa
TotalTime	number	opt	Tempo de resposta em segundos
Hotels	array[object]	opt	Lista de hotéis disponíveis com quartos e preços

1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "Criteria": {
7    "CheckinDate": "2024-12-20",
8    "CheckoutDate": "2024-12-27",
9    "DestinationId": 1010422,
10    "MainPaxCountryCodeNationality": "BR",
11    "NumNights": 7,
12    "ReturnHotelStaticData": true,
13    "HidePackageRate": false,
14    "CheapestRoomOnly": false,
15    "SearchType": "Hotel",
16    "SearchRooms": [
17      {
18        "ChildAges": [],
19        "NumAdults": 2,
20        "Quantity": 1
21      }
22    ]
23  }
24}

GetBookingConditions

🏨Hotel— Segundo passo. Valida disponibilidade, confirma preço final e retorna políticas de cancelamento antes da reserva.

POST🏨Hotel2° passo

GetBookingConditions

POSThttps://ws.iterpec.com/API/REST/Hotel.svc/GetBookingConditions

Retorna condições de reserva, políticas de cancelamento, taxas locais e valida o preço. **Obrigatório verificar novamente o preço** — fornecedores podem ter cache de disponibilidade. Se o ReToken estiver ativo e o token expirado, retorna `RevalidateBookingConditions` com status: - `SameRoomsFound` — preço e disponibilidade iguais - `RoomsFoundWithChanges` — houve mudança de preço ou disponibilidade - `RoomsNotFound` — quarto não disponível, refaça o Search

Request Body

Nome	Tipo	Req.	Descrição
Credential	object	req	Credenciais de acesso
HotelId	integer	req	ID do hotel (apenas um por chamada)
RoomIds	array[integer\|string]	req	IDs dos quartos selecionados no Search
Token	string	req	Token retornado pelo Search

Response Fields

Nome	Tipo	Req.	Descrição
Token	string	opt	Novo token — usar no DoBooking
CanPayLater	boolean	opt	true = pagamento pode ser feito depois
RestrictionType	string	opt	Tipo de restrição: CanBook, OnRequest, etc.
RevalidateBookingConditions	string	opt	SameRoomsFound \| RoomsFoundWithChanges \| RoomsNotFound
RoomsConditions	array[object]	opt	Condições detalhadas por quarto

⚠️

⚠️ Taxas Locais Obrigatórias — Dois Formatos Possíveis

O GetBookingConditions pode retornar valores obrigatórios a serem pagos diretamente no hotel de duas formas distintas e complementares. O integrador deve verificar ambos os campos antes de exibir o resumo da reserva ao hóspede. Omitir essas informações pode gerar reclamações, chargebacks e cancelamentos.

📊 Formato 1 — PropertyTaxes (Estruturado)

Quando o fornecedor envia as taxas de forma estruturada, elas aparecem no array `RoomsConditions[].PropertyTaxes`. Cada item representa uma taxa distinta com nome, valor, moeda e tipo de cobrança.

Campo	Tipo	Exemplo	Descrição
Name	string	"Resort Fee"	Nome da taxa conforme o fornecedor
Amount	number	35.00	Valor da taxa
Currency	string	"USD"	Moeda (pode ser diferente da reserva)
Type	string	"PerNight"	PerNight \| PerStay \| PerPerson \| PerPersonPerNight
Description	string	"Collected at property"	Descrição adicional do fornecedor

📋 Formato 2 — MoreInformation (Texto Livre)

Quando o fornecedor não estrutura as taxas no PropertyTaxes, elas podem aparecer embutidas no campo MoreInformation como texto corrido. Este campo contém observações gerais do hotel — políticas, restrições e, frequentemente, taxas obrigatórias não estruturadas. Exemplo real: ``


"IMPORTANT: A mandatory resort fee of USD 35 per room per night will be collected at the property. This fee is not included in the room rate. Additional city tax of EUR 4.50 per person per night may apply."

`` O integrador deve sempre exibir o conteúdo completo do MoreInformation ao hóspede, mesmo que não consiga extrair valores estruturados. Uma IA ou regex pode ajudar a destacar os trechos relevantes.

Este PRD define como um sistema de IA deve processar o campo `MoreInformation` para identificar e extrair valores obrigatórios a serem pagos localmente no hotel.

1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "HotelId": 61221,
7  "RoomIds": [35100101],
8  "Token": "m+Jb/PG5CBOqYcquX10YRPZMmMF..."
9}

Booking

🏨Hotel— Terceiro passo. Confirma a reserva com os dados dos passageiros e de pagamento.

POST🏨Hotel3° passo

DoBooking

POSThttps://ws.iterpec.com/API/REST/Hotel.svc/DoBooking

💡 Use `Surname: "NoBook"` para testes — a reserva não será efetivada no fornecedor.

Confirma a reserva de hotel com os dados dos passageiros. Necessário o token retornado pelo GetBookingConditions. Para **adicionar um serviço a uma reserva existente**, informe o `BookingId` da reserva. Para criar uma nova reserva, use `BookingId: "0"`.

Request Body

Nome	Tipo	Req.	Descrição
Credential	object	req	Credenciais de acesso
BookingId	string	req	"0" para nova reserva. ID existente para adicionar serviço. `ex: "0"`
HotelId	integer	req	ID do hotel
Paxs	array[object]	req	Dados dos passageiros

Response Fields

Nome	Tipo	Req.	Descrição
RequestId	integer	opt	ID da reserva confirmada (ReservationId)
TimeSpan	string	opt	Data e hora da confirmação
Rooms	array[object]	opt	Dados dos quartos confirmados

1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "BookingId": "0",
7  "HotelId": 94171,
8  "Paxs": [
9    {
10      "Address": "Rua das Flores",
11      "AddressNumber": "100",
12      "Age": 35,
13      "City": "São Paulo",
14      "Cpf": "123.456.789-00",
15      "DocumentType": "CPF",
16      "Email": "viajante@email.com",
17      "MainPax": true,
18      "Name": "João",
19      "Surname": "NoBook",
20      "PhoneDDD": "11",
21      "PhoneNumber": "999999999",
22      "State": "SP",
23      "Title": "Mr",
24      "ZipCode": "01310-100",
25      "IsChild": false,
26      "IsBilled": false
27    }
28  ]
29}

Cancel

🏨Hotel— Cancelamento de reservas. Dois modos: **por viagem** (cancela todos os serviços) ou **por serviço** (cancela um serviço específico).

POST🏨HotelModo 1

Cancel por Viagem

POSThttps://ws.iterpec.com/API/REST/Hotel.svc/CancelAllHotelServices

Cancela **todos os serviços de hotel** de uma reserva de uma vez, usando o `BookingId` (ReservationId).

Request Body

Nome	Tipo	Req.	Descrição
Credential	object	req	Credenciais de acesso
BookingId	string	req	ID da reserva (ReservationId) `ex: "1864605"`
RefundPayment	boolean	opt	true = solicita estorno do pagamento

1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "BookingId": "1864605",
7  "RefundPayment": false
8}

POST🏨HotelModo 2

Cancel por Serviço

POSThttps://ws.iterpec.com/API/REST/Hotel.svc/CancelByService

Cancela um **serviço específico** dentro de uma reserva usando o `ServiceId`. Use quando a reserva tem múltiplos serviços e você quer cancelar apenas um.

Request Body

Nome	Tipo	Req.	Descrição
Credential	object	req	Credenciais de acesso
ServiceIds	array[integer]	req	IDs dos serviços a cancelar `ex: [1864605]`
RefundPayment	boolean	opt	true = estorno da taxa de cancelamento

1{
2  "Credential": {
3    "Username": "{{meuusuario}}",
4    "Password": "{{minhasenha}}"
5  },
6  "ServiceIds": [1864605],
7  "RefundPayment": true
8}

Payment

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

POST💳Payment

payBooking

POSThttps://ws.iterpec.com/API/REST/Payment.svc/payBooking

Realiza o pagamento de uma reserva via cartão de crédito. Utilizado quando `IsPrePayment` é `true` no retorno do Search.

Request Body

Nome	Tipo	Req.	Descrição
BookingId	string	req	ID da reserva
Credential	object	req	Credenciais de acesso
PaymentConditionId	string	req	ID da condição de pagamento
PaymentRequestCC1	object	req	Dados do cartão de crédito

1{
2  "BookingId": "1864605",
3  "Credential": {
4    "Password": "{{minhasenha}}",
5    "Username": "{{meuusuario}}"
6  },
7  "PaymentConditionId": "CC-001",
8  "PaymentRequestCC1": {
9    "ContractingParty": {
10      "Address": "Rua das Flores, 100",
11      "CPF": "123.456.789-00",
12      "CityName": "São Paulo",
13      "CountryCode": "BR",
14      "Email": "titular@email.com",
15      "PersonName": "João Silva",
16      "PhoneDDD": "11",
17      "PhoneNumber": "999999999"
18    }
19  }
20}

ClientBackOffice

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

POST📋BackOffice

GetBookingDetail

POSThttps://ws.iterpec.com/API/REST/ClientBackOffice.svc/GetBookingDetail

💡 Chamar este método atualiza o status da reserva. Use polling a cada 5–30 min para resolver estados ambíguos (TechnicalProblem, PendingCancellation).

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 e número de confirmação do hotel (HCN), cada chamada sincroniza o status da reserva com o fornecedor. Isso torna o método essencial para monitoramento automático via polling.

Request Body

Nome	Tipo	Req.	Descrição
Credential	object	req	Credenciais de acesso
BookingId	string	req	ID da reserva (ReservationId) `ex: "1864605"`

Response Fields

Nome	Tipo	Req.	Descrição
Booking	object	opt	Dados completos da reserva

⚠️

🔄 Chamar GetBookingDetail ATUALIZA o status da reserva

Cada chamada a este método sincroniza o status da reserva com o fornecedor. Não é apenas uma consulta — é uma atualização ativa. Use isso a seu favor: ao chamar periodicamente (polling), você obtém o status final de reservas que ficaram em estados ambíguos após o DoBooking.

📊 Estados Ambíguos que Requerem Polling

Após o DoBooking, uma reserva pode retornar em um dos seguintes estados que exigem acompanhamento ativo:

Status	Significado	Analogia	Ação Recomendada
TechnicalProblem	Erro técnico durante a criação. Não se sabe se a reserva foi criada no fornecedor.	HTTP 500 de uma API	Polling a cada 5 min por até 30 min
Pending	Reserva criada, aguardando confirmação do fornecedor (ex: OnRequest).	HTTP 202 Accepted	Polling a cada 10 min por até 30 min
PendingCancellation	Solicitação de cancelamento enviada, aguardando confirmação do fornecedor.	HTTP 202 de um DELETE	Polling a cada 5 min por até 30 min
Rejected	Reserva rejeitada pelo fornecedor. Status final — sempre resultará em cancelamento.	HTTP 422	Não requer polling — status final

Este PRD define como implementar o monitoramento automático de reservas em estados ambíguos usando GetBookingDetail como mecanismo de polling.

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

Nome	Tipo	Req.	Descrição
Credential	object	req	Credenciais de acesso
SearchBookingCriteria	object	opt	Filtros de busca (todos opcionais)

1{
2  "Credential": {
3    "Password": "{{minhasenha}}",
4    "Username": "{{meuusuario}}"
5  },
6  "SearchBookingCriteria": {
7    "BookingNumber": [],
8    "CheckinDateFrom": "2024-01-01",
9    "CheckinDateTo": "2024-01-31"
10  }
11}