FAQ API

Sobre esta FAQ

Esta FAQ reúne perguntas e respostas sobre a API REST da Cangooroo para Hotel, Pagamento, Aéreo, Carro, Passeios/Ingressos, Transfer e Ônibus. Ela não contém credenciais, nomes de usuário, hosts de ambiente nem endpoints internos de nenhum cliente.

• Endereço base: todos os endpoints aparecem como {{url}}/API/REST/<Serviço>.svc/<Método>. Substitua {{url}} pelo host do ambiente contratado.
• Exemplos de credencial: aparecem como "<usuario>" e "<senha>".
• Pontos não confirmados: comportamentos observados mas sem confirmação no contrato oficial estão marcados como (não confirmado).

Tags

Cada pergunta termina com uma linha de tags, para facilitar a busca (Ctrl+F) e a importação em uma base de conhecimento. Toda pergunta tem pelo menos uma tag de produto e uma de tema.

Geral

Qual é o formato da URL da API?

Segundo a documentação oficial, {{url}} corresponde a https://ws-[clientIdentification].cangooroo.net, em que [clientIdentification] é a identificação do operador. Confira se está usando a URL com o prefixo ws-. O caminho completo é {{url}}/API/[SERVICE]/<Serviço>.svc/<método>.

Tags: geral url configuracao doc-oficial

A API é REST ou SOAP?

As duas. Troque [SERVICE] por REST ou SOAP. Esta FAQ usa sempre REST ({{url}}/API/REST/). Os métodos têm os mesmos nomes nos dois formatos.

Tags: geral url configuracao doc-oficial

Como conseguir acesso ao ambiente de produção?

O operador (dono da licença Cangooroo) pede ao suporte da Cangooroo a criação do usuário e, depois, habilita esse usuário.

Tags: geral configuracao autenticacao doc-oficial

Existe coleção Postman com exemplos?

Sim. A documentação oficial publica uma coleção Postman com exemplos de todos os contratos.

Tags: geral configuracao boas-praticas doc-oficial

Como a API é autenticada?

Pela própria requisição, não por cabeçalho HTTP. Toda chamada é um POST com Content-Type: application/json e um objeto Credential no corpo:

{ "Credential": { "Username": "<usuario>", "Password": "<senha>" } }

Tags: geral autenticacao doc-oficial

Uma mesma credencial serve para todos os produtos?

Nem sempre. Cada produto (RentACar, Tour, Transfer, Bus etc.) precisa estar habilitado para o usuário, e alguns produtos podem estar em ambientes (hosts) diferentes. Se um serviço responder com erro de usuário inexistente ou não habilitado, confira a habilitação do produto antes de investigar o código.

Tags: geral autenticacao configuracao

Como identificar um erro de negócio?

A API costuma responder HTTP 200 mesmo quando a operação falha. O erro vem no corpo, em Error.Message (em alguns serviços, ErrorMessage ou Error). Sempre verifique esse campo antes de tratar a resposta como sucesso.

Tags: geral erros boas-praticas

Quais mensagens indicam problema de credencial?

Mensagens contendo termos como "não existente", "não habilitado", "invalid" ou "unauthorized" em Error.Message indicam usuário inválido ou sem permissão para o serviço.

Tags: geral erros autenticacao

Quais mensagens indicam token de busca expirado?

O token devolvido pela busca vale 30 minutos e serve para um único processo de reserva. Mensagens com "token is expired", "invalid token", "token is empty", o código 12017 ou error_nl indicam token vencido ou inválido. No aéreo, uma NullReferenceException ("object reference not set") costuma ter a mesma causa. A solução é refazer a busca.

Tags: geral token erros doc-oficial

Quais timeouts usar?

Os tempos abaixo funcionam bem na prática:

Tags: geral timeout boas-praticas

Por que não repetir automaticamente o DoBooking?

Porque o timeout no cliente não significa que a reserva falhou no fornecedor. Repetir pode criar reserva duplicada. Em caso de timeout, consulte a reserva (por ClientReference ou na listagem) antes de tentar de novo.

Tags: geral reserva timeout boas-praticas doc-oficial

Os campos de data seguem qual formato?

A documentação oficial é clara: todo campo de data deve ser enviado como texto no formato YYYY-MM-DD, sem hora e sem fuso horário, tanto em REST quanto em SOAP. Algumas respostas, principalmente do Ônibus, trazem datas no formato WCF /Date(milissegundos)/, que precisa ser convertido.

Tags: geral datas campos doc-oficial

Os preços já vêm convertidos para a minha moeda?

Não. Os valores vêm com Value e Currency na moeda do fornecedor. A resposta de pagamento pode trazer a taxa usada pela operadora em PaymentResult.Currency (CurrencyFrom, CurrencyTo, ConvertionValue).

Tags: geral precos cambio

Dá para usar um token depois de 30 minutos?

Só com o módulo Retoken, contratado com o time comercial da Cangooroo. Com ele ativo, o GetBookingConditions de hotel aceita token vencido e responde com o campo RoomsConditions:

Tags: geral hotel token condicoes doc-oficial

A API tem paginação?

Não. Quando um serviço passar a ter, isso aparecerá na documentação dele. Em resultados grandes, use os filtros da busca.

Tags: geral busca limites doc-oficial

Existe limite de chamadas?

O limite é definido pelo dono da licença Cangooroo; consulte-o. Um HTTP 429 indica que o limite foi atingido.

Tags: geral limites erros doc-oficial

Como saber se o tempo de resposta está normal?

Compare com o Timeout configurado na requisição. Se a resposta chegar dentro desse tempo, a Cangooroo considera o comportamento normal.

Tags: geral timeout doc-oficial

Hotel e casas de temporada

Qual é o fluxo de reserva de hotel?

1. {{url}}/API/REST/Hotel.svc/Search — busca e devolve Token + Hotels[] com Rooms[].
2. {{url}}/API/REST/Hotel.svc/GetBookingConditions — confirma preço final e políticas de cancelamento dos quartos escolhidos.
3. {{url}}/API/REST/Payment.svc/GetPaymentConditionsByToken — obtém formas de pagamento e parcelamento.
4. {{url}}/API/REST/Hotel.svc/DoBooking — efetiva a reserva (com ou sem pagamento).
5. {{url}}/API/REST/Hotel.svc/GetBookingDetails — consulta status, localizador e voucher.

Tags: hotel busca condicoes reserva doc-oficial

Quais campos são obrigatórios na busca?

Dentro de Criteria: CheckinDate, NumNights, SearchRooms (cada quarto com NumAdults, ChildAges[] e Quantity) e um destes: DestinationId ou HotelsIds[].

Campos opcionais úteis:

• SearchType: Hotel (padrão) ou Home (casas de temporada).
• MainPaxCountryCodeNationality: nacionalidade do hóspede principal, por exemplo BR.
• ReturnExtendedHotelStaticData, ReturnHotelStaticData: incluem dados estáticos (fotos, comodidades, descrição).
• Filters.CheapestRoomOnly e Filters.HidePackageRate: true reduz a resposta ao quarto mais barato.
• Timeout: tempo máximo de busca no fornecedor, em milissegundos.

{
  "Credential": { "Username": "<usuario>", "Password": "<senha>" },
  "Criteria": {
    "CheckinDate": "2026-12-10",
    "NumNights": 5,
    "SearchRooms": [{ "NumAdults": 2, "ChildAges": [], "Quantity": 1 }],
    "SearchType": "Hotel",
    "MainPaxCountryCodeNationality": "BR",
    "DestinationId": 12345,
    "Filters": { "CheapestRoomOnly": false, "HidePackageRate": false }
  }
}

Tags: hotel busca campos doc-oficial

Como buscar casas de temporada (Vacation Homes)?

Use SearchType: "Home" e envie também ReturnHotelStaticData: true e ReturnOnRequestRooms: false. Sem esses dois campos, o inventário de casas pode não vir.

Tags: hotel casas-de-temporada busca campos

Por que a busca de casas volta vazia na primeira vez?

O cache do fornecedor costuma estar frio na primeira consulta. Repetir a busca até 3 vezes, com cerca de 1,2 s entre tentativas, normalmente resolve.

Tags: hotel casas-de-temporada busca boas-praticas nao-confirmado

Alguns campos da busca vêm como texto JSON?

Sim. Photos e Amenities podem chegar como string JSON e precisam de JSON.parse. Category pode vir em formatos variados e precisa ser normalizado para 1–5 estrelas.

Tags: hotel busca campos

Como montar o GetBookingConditions com vários quartos?

Envie Token, HotelId e RoomIds[]. Para reservar o mesmo quarto mais de uma vez, repita o RoomId no array uma vez para cada unidade. GetNextRoomOnError: true pede ao fornecedor que sugira o próximo quarto se o escolhido não estiver mais disponível (vem em RoomsNextOption[]).

Tags: hotel condicoes campos doc-oficial

Qual preço vale: o da busca ou o das condições?

O de GetBookingConditions (SellingPricePerRoom / TotalSellingPrice). O preço da busca é estimado e pode mudar. Compare os dois e avise o cliente se houver divergência.

Tags: hotel condicoes precos doc-oficial

O token serve para mais de um hotel?

Não. O token é vinculado ao hotel. Cada combinação (HotelId, Token) exige sua própria chamada de condições e de reserva.

Tags: hotel token multi-servico

O que vai no DoBooking?

Credential, Token, HotelId e Rooms[]. Cada quarto leva RoomId, Paxs[] (Name, Surname, Age, PaxType e, conforme o caso, documento, telefone e endereço) e, se pago com cartão, um objeto Payment.PaymentRequestCC1 com PaymentConditionId, ContractingParty e CreditCard. Opcionais: ClientReference, Remarks, SendEmail, PayBeforeBook e BookingId.

Tags: hotel reserva campos

Como juntar vários hotéis numa única reserva?

Faça os DoBooking em sequência. Pegue o BookingId do primeiro e envie-o como BookingId nos seguintes. O resultado é uma reserva-mãe com vários ServiceIds.

Tags: hotel reserva multi-servico

Por que aparecem quartos repetidos ao usar o BookingId âncora?

Ao receber um BookingId âncora, a API devolve a árvore completa da reserva-mãe, incluindo quartos criados em chamadas anteriores. Deduplique por ServiceId ao consolidar as respostas.

Tags: hotel reserva multi-servico

Quais campos da resposta do DoBooking guardar?

BookingId, BookingCode, Locator, Status, ServiceIds e ReservationId. São necessários para consulta, pagamento posterior e cancelamento.

Tags: hotel reserva campos

Quantos hotéis posso pedir numa busca por HotelsIds?

No máximo 300 IDs por requisição, segundo a recomendação oficial.

Tags: hotel busca limites doc-oficial

Quais outros filtros a busca aceita?

Em Filters: MinPrice e MaxPrice (faixa de preço), CheapestRoomOnly (só o quarto mais barato de cada hotel), SelectedHotelsIds[] (lista de hotéis) e HidePackageRate (oculta tarifas de pacote). Todos são opcionais.

Tags: hotel busca campos doc-oficial

O que faz ReturnOnRequestRooms?

Alguns fornecedores mantêm quartos "sob consulta" (on request). Com ReturnOnRequestRooms: true, esses quartos aparecem na busca; com false, ficam de fora.

Tags: hotel busca campos doc-oficial

A busca só com crianças funciona?

Não. Todo quarto precisa de pelo menos 1 adulto. Uma busca com NumAdults: 0 não retorna hotéis. ChildAges é opcional e só deve ser enviado quando houver crianças.

Tags: hotel busca passageiros doc-oficial

Posso guardar ou mapear o RoomId?

Não. O HotelId é um inteiro estável, mas o RoomId é um texto criptografado que muda a cada busca. Nunca presuma formato, tamanho nem faça mapeamento do RoomId. Para dados estendidos do quarto, use RoomMediaId com a API de conteúdo (Hotel Detail).

Tags: hotel busca campos boas-praticas doc-oficial

Posso consultar condições de vários hotéis numa só chamada?

Não. Cada GetBookingConditions aceita um único HotelId. Além disso, a quantidade de RoomIds deve ser exatamente a quantidade de quartos pesquisada: buscou 2 quartos, envie 2 RoomIds.

Tags: hotel condicoes limites doc-oficial

Posso reservar quartos diferentes para a mesma configuração de ocupação?

Não. Para a mesma configuração (por exemplo, 3 quartos com 1 adulto), envie o mesmo RoomId repetido 3 vezes. A documentação oficial não permite reservar quartos diferentes nesse caso.

Tags: hotel condicoes reserva doc-oficial

O que conferir na resposta do GetBookingConditions?

A documentação oficial torna estas verificações obrigatórias, porque alguns fornecedores usam cache na busca:

• preço, moeda e políticas de cancelamento;
• HotelInfo (nome e endereço), para confirmar que é o mesmo hotel da busca — a Cangooroo não assume custos de erro de mapeamento;
• MoreInformation, com informações que devem ser exibidas ao cliente, como taxas pagas no destino (resort fee, taxa municipal);
• PropertyTaxes, com as taxas pagas diretamente no hotel.

Tags: hotel condicoes precos boas-praticas doc-oficial

Por que o DoBooking de hotel falha?

As causas mais comuns, segundo a documentação oficial:

1. Os quartos enviados não estavam no último GetBookingConditions feito.
2. Passaram mais de 30 minutos entre a busca e a reserva.
3. O GetBookingConditions não foi chamado antes do DoBooking.

Tags: hotel reserva erros token doc-oficial

Como informar os hóspedes no DoBooking?

Em Passengers[], com Name, Surname, Age, Title, MainPax, isChild, documento (Cpf), endereço (Address, AddressNumber, City, State, ZipCode), Email e telefone (PhoneDDI, PhoneDDD, PhoneNumber). O primeiro passageiro da lista é considerado o principal.

Tags: hotel reserva passageiros doc-oficial

O que é SetWaitingPayment no hotel?

Com SetWaitingPayment: true, a reserva é criada com status aguardando pagamento. Ela pode ser paga até o token expirar; se não for paga, é rejeitada. Paga no prazo, segue para confirmação no fornecedor.

Tags: hotel reserva pagamento status doc-oficial

Preciso sempre informar o PaymentConditionId?

Não. Se o quarto tiver pré-pagamento ou pagamento direto no hotel, o cartão pode ser enviado sem PaymentConditionId; nesse caso ele é repassado apenas ao fornecedor.

Tags: hotel pagamento pagamento-cartao doc-oficial

Como cancelar hotel?

• {{url}}/API/REST/Hotel.svc/CancelAllHotelServices cancela todos os serviços de hotel da reserva (não cancela outros produtos).
• {{url}}/API/REST/Hotel.svc/CancelByService cancela um serviço específico. Alguns serviços não podem ser cancelados isoladamente; nesse caso o método retorna erro e é preciso cancelar todos.

Tags: hotel cancelamento doc-oficial

Como saber se uma reserva foi criada após um erro HTTP?

Use {{url}}/API/REST/Hotel.svc/CheckBookingStatus. Veja o fluxo completo em "Reservas, status e cancelamento".

Tags: hotel reserva erros status doc-oficial

Pagamento e PIX

Qual a diferença entre GetPaymentConditionsByToken e GetPaymentConditions?

ServiceType aceita HOTEL, FLIGHT, CAR, TRANSFER e TOUR.

Tags: pagamento condicoes doc-oficial

O que vem na resposta das condições de pagamento?

Uma lista PaymentConditions[] com o PaymentConditionId, as bandeiras aceitas e as opções de parcelamento. O PaymentConditionId escolhido é o que vai no pagamento.

Tags: pagamento condicoes campos

E se o serviço de condições de pagamento devolver 404?

Isso indica que o método não está disponível para aquela conta ou ambiente. Trate como "sem condições retornadas" e use uma condição padrão combinada com a Cangooroo para a sua conta.

Tags: pagamento condicoes erros nao-confirmado

Como pagar com cartão de crédito?

Há dois caminhos:

• Junto da reserva (hotel): envie Payment.PaymentRequestCC1 dentro de cada quarto no DoBooking.
• Depois da reserva (aéreo e outros): chame {{url}}/API/REST/Payment.svc/payBooking com BookingId, PaymentConditionId, ServicesId[] e PaymentRequestCC1.

PaymentRequestCC1 contém dois blocos. Os nomes abaixo são os da documentação oficial (Hotel e Payment):

• ContractingParty (pagador): PersonName, CPF, Email, PhoneNumberDDI, PhoneNumberDDD, PhoneNumber, Address, AddressNumber, AddressComplement, DistrictName, CityName, StateCode, CountryCode, ZipCode e ReceiveCreditCardReceipt.
• CreditCard: CardNumber, CardOperator (bandeira), Holder, MonthExpiration, YearExpiration, SecurityCode e NumberPayments (parcelas).

Remova espaços do número do cartão antes de enviar. (não confirmado) Em alguns produtos, como Carro, a integração usou nomes diferentes (HolderName, ExpirationMonth, ExpirationYear, CardType); confira a coleção Postman do produto.

Tags: pagamento pagamento-cartao campos doc-oficial

O que é PayBeforeBook?

Com PayBeforeBook: true (e um PaymentConditionId no nível raiz do DoBooking), o pagamento é cobrado antes da confirmação. Use quando a tarifa é não reembolsável (IsNonRefundable: true) ou quando alguma CancellationPolicy já está em vigor (StartDate no passado).

Tags: pagamento reserva cancelamento hotel

Como funciona o pagamento por PIX?

1. Faça o DoBooking com a forma de pagamento PIX (e PayBeforeBook se houver multa de cancelamento).
2. A resposta traz PaymentInfo com QR Code, código copia-e-cola e ExpirationDate.
3. Consulte {{url}}/API/REST/Hotel.svc/GetBookingDetails com o BookingId periodicamente (ex.: a cada 10 s) até o status mudar.

Tags: pagamento pix reserva status

Quais status acompanhar no PIX?

AwaitingPayment (aguardando), Confirmed (pago e confirmado), Cancelled e Expired. Pare a consulta ao chegar em qualquer um dos três últimos.

Tags: pagamento pix status

PIX funciona com vários hotéis na mesma compra?

(não confirmado) Na prática, o PIX foi usado com um hotel por reserva. Confirme com a Cangooroo antes de combinar vários serviços num único PIX.

Tags: pagamento pix multi-servico nao-confirmado

Como saber a taxa de câmbio aplicada?

A resposta do pagamento pode trazer PaymentResult.Currency com CurrencyFrom, CurrencyTo e ConvertionValue. Essa é a taxa real da operadora.

Tags: pagamento cambio

Como é a resposta das condições de pagamento?

Cada condição ativa traz Id (o PaymentConditionId a usar no pagamento), Name (ex.: o gateway), Operation, PaymentMode e um bloco CreditCard com NumberPaymentMin, o máximo de parcelas por bandeira (NumberPaymentVisa, NumberPaymentMaster etc.) e MinimumParcelValue (valor mínimo da parcela e moeda).

Tags: pagamento condicoes campos doc-oficial

Qual o nome oficial do método de condições por reserva?

A documentação o chama de GetPaymentConditionsByBookingId; o método exposto no serviço é GetPaymentConditions, com BookingId e Services (ServiceId como chave e ServiceType como valor). Ambos devolvem as condições cadastradas para a agência do usuário.

Tags: pagamento condicoes doc-oficial

Quando chamar GetPaymentConditionsByToken?

Depois do GetBookingConditions do serviço, usando o mesmo Token. O Id devolvido é o que vai no DoBooking ou no payBooking.

Tags: pagamento condicoes token doc-oficial

O payBooking paga a reserva inteira ou serviços específicos?

Os dois. Informe o BookingId e, se quiser pagar só parte, a lista ServicesId. A resposta traz os serviços pagos e o status da transação.

Tags: pagamento pagamento-cartao multi-servico doc-oficial

Dá para alterar a comissão no pagamento?

Sim. No payBooking, SmartCommissionValue define um novo valor de comissão para o serviço e RetainCommission retém a comissão integralmente.

Tags: pagamento precos doc-oficial

Aéreo

Qual é o fluxo de reserva aérea?

1. {{url}}/API/REST/Flight.svc/Search — busca voos.
2. {{url}}/API/REST/Flight.svc/SearchNextSegment — obtém o trecho de volta a partir do ResponseId da ida (ida e volta).
3. {{url}}/API/REST/Flight.svc/GetBookingConditions — revalida a seleção e devolve ResponseIds atualizados.
4. {{url}}/API/REST/Flight.svc/DoBooking — cria a reserva aguardando pagamento.
5. {{url}}/API/REST/Payment.svc/payBooking — paga a reserva.

Tags: aereo busca condicoes reserva pagamento

Quais campos são obrigatórios na busca?

Dentro de Criteria: DepartureDate, IataOriginAirport, IataDestinationAirport e NumberOfAdults. ReturnDate só é enviado quando a busca não é só de ida.

Tags: aereo busca campos

Qual a diferença entre Flights e Segments na resposta?

Flights[] são as ofertas (com TotalPrice / TotalSellingPrice). Segments[] são os trechos, cada um com ResponseId, aeroportos, horários e Luggages. Sem Segments não há itinerário comprável.

Tags: aereo busca campos

Como saber se a bagagem está incluída?

Em cada segmento: LuggageIncluded (booleano) e Luggages[0] com LuggageIncluded, CarryOnLuggageIncluded, Weight e WeightUnit.

Tags: aereo busca campos

A busca voltou vazia sem erro. O que fazer?

Repita a busca uma vez. Respostas vazias intermitentes acontecem enquanto a sessão do fornecedor é renovada. Evite guardar resultados vazios em cache.

Tags: aereo busca erros boas-praticas nao-confirmado

Como montar o GetBookingConditions em ida e volta?

Envie ResponsesIds[] com os ResponseIds da ida e da volta da mesma sessão numa única chamada. Voos só de ida vão um por chamada. Misturar ResponseIds de buscas diferentes provoca NullReferenceException.

Tags: aereo condicoes token erros

Quais ResponseIds vão no DoBooking?

Os devolvidos pelo GetBookingConditions em BookingConditionsFlight.Segments[].ResponseId, não os da busca original.

Tags: aereo condicoes reserva token

O que vai no DoBooking aéreo?

ResponsesIds[], Passengers[], SetWaitingPayment (normalmente true) e, opcionalmente, BookingId (reserva-mãe) e ClientReference. Preencha para todos os passageiros, inclusive crianças: Name, Surname, Cpf, Email, PhoneDDD e PhoneNumber. A falta de qualquer um causa NullReferenceException.

Tags: aereo reserva passageiros erros

Como saber se a reserva aérea foi criada?

Leia Flights[0] da resposta. Considere confirmada só se vierem Token e ServiceId, além do BookingId.

Tags: aereo reserva status

O voo pode entrar numa reserva já existente?

Sim, enviando BookingId no DoBooking aéreo. Porém, ao combinar voo e hotel, costuma funcionar melhor reservar o voo primeiro e usar o BookingId dele como âncora dos demais serviços.

Tags: aereo reserva multi-servico

Como pagar o aéreo?

Com {{url}}/API/REST/Payment.svc/payBooking, enviando BookingId, PaymentConditionId, ServicesId[] e PaymentRequestCC1 (ContractingParty, CreditCard, IsBilled: false). Opcionais: RetainCommission, SmartCommissionValue, UrlPosPayment.

Tags: aereo pagamento pagamento-cartao

Como saber se o pagamento foi recusado?

A resposta pode vir com HTTP 200 e erro em Error.Message. Se não houver erro, confira BookingDetail.Flights[0].Status e PaymentStatus: Rejected significa recusa.

Tags: aereo pagamento status erros

As famílias tarifárias (GetFareFamilies) funcionam?

(não confirmado) O método {{url}}/API/REST/Flight.svc/GetFareFamilies recebe ResponsesIds[], mas devolveu 404 em alguns ambientes. Confirme a disponibilidade com a Cangooroo. Se usar, GetBookingConditions aceita SelectedFareFamilyId opcional.

Tags: aereo condicoes precos nao-confirmado

Carro

Qual é o fluxo de locação de carro?

1. {{url}}/API/REST/RentACar.svc/Search — busca carros disponíveis.
2. {{url}}/API/REST/RentACar.svc/GetBookingConditions — detalha condições do carro escolhido.
3. {{url}}/API/REST/RentACar.svc/doBooking — efetiva a reserva.
4. {{url}}/API/REST/RentACar.svc/getBooking — consulta a reserva e o status do pagamento.

Tags: carro busca condicoes reserva

Quais campos são obrigatórios na busca?

Código do local de retirada, data e hora de retirada, data e hora de devolução. Eles vão em Criteria.Pickup e Criteria.Dropoff. Opcionais: local de devolução diferente, tipo do local e idade do condutor.

Tags: carro busca campos

Quais valores o tipo de local (LocationType) aceita?

Airport, Hotel e Store. Use Airport quando não tiver certeza.

Tags: carro busca campos

O que vem na resposta da busca?

Um Token e a lista de carros, cada um com fornecedor, modelo, categoria, informações de preço, opcionais, políticas de cancelamento, condições gerais e detalhes dos locais de retirada e devolução. Campos de imagem ou logo podem vir com valores inválidos como "none"; valide a URL antes de exibir.

Tags: carro busca campos boas-praticas

O que o GetBookingConditions acrescenta?

Recebe o ID do carro e o Token. Devolve opcionais, caução (depósito), políticas de cancelamento, características, condições de pagamento e prazo de pagamento.

Tags: carro condicoes campos

O que é obrigatório no doBooking?

Token, ID do carro e o condutor com Name, Surname, Age, Email, DocumentNumber, Cpf, ZipCode, Address, AddressNumber, City e State. Opcionais: Title, AddressComplement, CountryCode, opcionais do carro, pagamento, ClientReference e BookingId (reserva-mãe). Envie DocumentType como Cpf (com essa grafia).

Tags: carro reserva passageiros campos

O pagamento do carro é confirmado na hora?

Nem sempre. Se o status voltar como AwaitingPayment, NotPayed, Pending ou Processing, consulte getBooking algumas vezes (por exemplo, 4 vezes com 5 s de intervalo) até aparecer Paid, Approved ou Confirmed. Atenção: o status pode vir grafado AwatingPayment (sem o "i"); trate as duas grafias.

Tags: carro pagamento status boas-praticas

Como cancelar um carro?

Pelo mesmo método usado para hotel: {{url}}/API/REST/hotel.svc/CancelByService, com os ServiceIds. Veja a seção de cancelamento.

Tags: carro cancelamento doc-oficial

Passeios e ingressos

Qual é o fluxo de reserva de passeios?

1. {{url}}/API/REST/Tour.svc/Search — busca passeios e ingressos.
2. {{url}}/API/REST/Tour.svc/GetBookingConditions — condições de pagamento e cancelamento.
3. {{url}}/API/REST/Tour.svc/DoBooking — efetiva a reserva.

Tags: passeios busca condicoes reserva

Quais campos são obrigatórios na busca?

Dentro de Criteria: ID da cidade, data inicial e data final do serviço. Opcionais: NumberOfDays (calcule pela diferença de datas se não enviar), ServiceLanguage, AdultAges[] e ChildAges[]. A resposta traz Token e Tours[].

Tags: passeios busca campos

Que valor usar em ServiceLanguage?

(não confirmado) O valor "1" funcionou como padrão, mas o mapeamento dos códigos de idioma não está documentado. Confirme com a Cangooroo.

Tags: passeios busca campos nao-confirmado

O que vai no GetBookingConditions?

Token, TourId, IdAvailability e a data do serviço. TourId e IdAvailability vêm da disponibilidade escolhida na busca. A resposta inclui PaymentConditions[].

Tags: passeios condicoes campos

O que vai no DoBooking de passeios?

Obrigatórios: Token, TourId, IdAvailability e Passengers.Pax. Opcionais: BookingId (reserva-mãe), SetWaitingPayment, ClientReference, ProviderQuestions e pagamento (PaymentConditionId, PaymentRequestCC1, PaymentRequestCC2, RetainCommission, SmartCommissionValue, UrlPosPayment).

Tags: passeios reserva pagamento campos

Campos vazios atrapalham o DoBooking?

Sim. Remova do corpo campos vazios ou com valores como "null", "undefined" e "?" antes de enviar.

Tags: passeios reserva erros boas-praticas

Quais IDs guardar após a reserva?

BookingId, BookingCode, ServiceId, Locator, ReservationId, Status e Token.

Tags: passeios reserva campos

Como montar uma vitrine de ingressos de parques (Disney, Universal)?

Combine estes métodos:

• {{url}}/API/REST/Tour.svc/GetTicketDays — menor preço por quantidade de dias.
• {{url}}/API/REST/Tour.svc/GetTicketParks — lista de parques do destino.
• {{url}}/API/REST/Tour.svc/Search — produtos vendáveis para a data.
• {{url}}/API/REST/Tour.svc/GetTicketInfo — detalhes do produto: condições, itens não inclusos, parques inclusos, adicionais e validade.

O catálogo (GetTicketDays, GetTicketParks) e a venda (Search) podem estar em ambientes diferentes.

Tags: passeios ingressos busca

A API separa ingressos por marca?

Não. Não há campo de marca. A identificação (Disney, Universal etc.) precisa ser feita pelo nome ou descrição do produto, e GetTicketParks devolve todos os parques do destino.

Tags: passeios ingressos busca

Como saber quantos dias o ingresso cobre?

No texto de DurationActivity ou no nome do produto (padrões como "3 days" ou "3 dias"). Se não encontrar, considere a quantidade de dias pesquisada.

Tags: passeios ingressos campos

Aparecem produtos estranhos na busca de ingressos. O que são?

Produtos de homologação do fornecedor, com nomes como CONFIRM/CANCEL, CANCEL_ERROR, TECHNICAL_PROBLEM, ON_REQUEST ou TEST. Filtre-os antes de exibir.

Tags: passeios ingressos busca boas-praticas

A busca de ingressos voltou vazia. O que fazer?

Repita com intervalo crescente (por exemplo 1,2 s, 2,5 s, 4 s, 6 s). A primeira busca do dia costuma encontrar o cache do fornecedor frio.

Tags: passeios ingressos busca boas-praticas nao-confirmado

Qual disponibilidade escolher para um produto?

Cada produto tem várias disponibilidades, cada uma com seu IdAvailability. Prefira a de DateService igual à data pedida e, entre elas, a mais barata. Use o TourId e o IdAvailability dessa disponibilidade nas etapas seguintes.

Tags: passeios ingressos busca precos

Transfer

Qual é o fluxo de reserva de transfer?

1. {{url}}/API/REST/Transfer.svc/Search — busca transfers.
2. {{url}}/API/REST/Transfer.svc/GetBookingConditions — condições de pagamento e cancelamento.
3. {{url}}/API/REST/Transfer.svc/DoBooking — efetiva a reserva.

Tags: transfer busca condicoes reserva

Quais campos são obrigatórios na busca?

Código e tipo do local de embarque, código e tipo do local de desembarque, data e hora do serviço e número de adultos. Em ida e volta, também data e hora da volta. Opcionais: número de crianças, idades e idioma do serviço. Envie crianças e idades só quando houver crianças.

Tags: transfer busca campos

Que formato tem o código do local?

É o ID numérico do local no cadastro de localidades, enviado como texto. Não é o código IATA do aeroporto.

Tags: transfer busca campos

Quais tipos de local o transfer aceita?

Airport, Accommodation, Port, Station, ThemePark, Other e CityLocation. Diferente do carro, não há valor padrão: envie o tipo correto.

Tags: transfer busca campos

Como montar uma busca de ida e volta?

Além de Pickup e Dropoff, envie PickupBack e DropoffBack com os locais invertidos. Sem eles, a busca falha com erro em CacheV3.getAeroporto.

Tags: transfer busca campos erros

A busca falhou com erro em CacheV3.getAeroporto. O que fazer?

Além da causa acima, esse erro pode ser transitório de cache. Repetir até 3 vezes com 1 s de espera costuma resolver.

Tags: transfer busca erros boas-praticas

Embarque no aeroporto não retorna nada no horário exato. Por quê?

A disponibilidade costuma estar em faixas de 30 minutos. Arredonde o horário para cima até o próximo múltiplo de 30 minutos e, se não houver resultado, tente +30 e +60 minutos.

Tags: transfer busca boas-praticas nao-confirmado

Onde ficam os transfers na resposta?

Em grupos, sob Transfers, Services ou Result.Transfers, conforme o caso. Cada grupo contém os transportes. Em ida e volta, a resposta pode trazer um ou dois grupos.

Tags: transfer busca campos

O que vai no GetBookingConditions?

Token, data do serviço e TransferIds[]: um ID para só ida, dois para ida e volta.

Tags: transfer condicoes campos

O que vai no DoBooking de transfer?

Obrigatórios: Token, ID do transfer e Passengers.Pax. Opcionais: BookingId, SetWaitingPayment, ClientReference, pagamento e dados do voo. Quando o embarque ou desembarque é em aeroporto, informe o voo: OriginAirCiaName, OriginAirCiaNumber, OriginAirCiaTime, OriginAirCiaDate, os equivalentes DestinyAir... e, na volta, ReturnDestinationAir....

Tags: transfer reserva passageiros campos

Onde estão os IDs na resposta do DoBooking?

Dentro de Services[0], não na raiz: BookingId, ServiceId, Locator, Status e VoucherUrl.

Tags: transfer reserva campos voucher

O status veio TechnicalProblem. A reserva foi feita?

Depende do BookingId. Se veio um BookingId, a reserva existe e deve ser acompanhada. Se não veio, a reserva não foi criada.

Tags: transfer reserva status erros

Ônibus

Qual é o fluxo de reserva rodoviária?

1. {{url}}/API/REST/Bus.svc/Search — busca viagens.
2. {{url}}/API/REST/Bus.svc/GetSeats — mapa de poltronas da viagem.
3. {{url}}/API/REST/Bus.svc/GetBookingConditions — revalida viagem e poltronas.
4. {{url}}/API/REST/Bus.svc/DoBooking — emite a reserva.

Não há etapa separada de emissão: o DoBooking já emite.

Tags: onibus busca condicoes reserva

Como montar a busca?

Envie BusSegmentCriterio[] com um segmento para só ida ou dois para ida e volta. Cada segmento leva o código da rodoviária de origem, o de destino e a data (YYYY-MM-DD). A resposta traz Token e as viagens, cada uma com BusId, empresa, terminais, horários, preço, poltronas livres e política de multa.

Tags: onibus busca campos

Como saber se a viagem é de ida ou de volta?

Compare o código da rodoviária de origem do segmento (OriginBusStationCode) com o destino pesquisado. Se forem iguais, é o trecho de volta.

Tags: onibus busca campos

Os horários de partida e chegada estão errados. Por quê?

Em alguns ambientes, DepartureTime e ArrivalTime chegam inconsistentes, sobretudo na volta. Os horários reais estão codificados no próprio BusId, no formato yyyyMMddHHmm (partida e chegada). Prefira decodificar o BusId.

Tags: onibus busca datas boas-praticas nao-confirmado

As datas vêm em que formato?

No formato WCF /Date(milissegundos)/, às vezes em ISO. Trate os dois.

Tags: onibus datas campos

O GetSeats retorna ERR_0410. O que fazer?

Envie TipoTrecho com ida ou volta. Sem esse parâmetro, o fornecedor falha ao carregar as regras de cancelamento.

Tags: onibus erros campos

Por que o GetBookingConditions ou o DoBooking rejeitam o corpo?

O contrato é inconsistente entre viagens. Se uma forma falhar, tente variar: Seats como lista de números ou de objetos, com ou sem TipoTrecho, com ou sem ClientId: 0.

Tags: onibus condicoes reserva erros nao-confirmado

Como informar os passageiros?

Um passageiro por poltrona, com o primeiro marcado como MainPax: true. Não envie passageiros com o mesmo nome ou CPF: o fornecedor rejeita com "Passengers may not have the same names".

Tags: onibus reserva passageiros erros

Onde está o voucher do ônibus?

A URL do voucher pode vir em diferentes chaves da resposta do DoBooking. Procure de forma recursiva qualquer chave que contenha "voucher".

Tags: onibus reserva voucher

O que significam erros de restrição ou LimiteCredito?

A conta está bloqueada ou sem crédito junto ao fornecedor. Não é erro técnico da integração. Error.Message pode vir acompanhado de Stacktrace com o detalhe.

Tags: onibus reserva erros limites

E a mensagem "not processed"?

A viagem ou as poltronas não estão mais disponíveis. Refaça a busca e a seleção de poltronas.

Tags: onibus reserva erros

Vale repetir a busca quando der timeout?

Não. Quando a rota não tem serviço, o fornecedor pode simplesmente deixar a conexão pendurada; repetir só dobra a espera. Repetir vale para respostas HTML ou HTTP 400, 429 e 5xx (uma vez, com cerca de 1 s de espera).

Tags: onibus busca timeout boas-praticas

Como interpretar a política de multa?

A política é uma lista de janelas, cada uma com data de início e valor. Antes da primeira janela com valor maior que zero, o cancelamento é grátis. Depois, vale a última janela cuja data já passou. Se a multa for igual ao preço, é não reembolsável. Sem política, a viagem não permite cancelamento.

Tags: onibus cancelamento precos

Reservas, status e cancelamento

Como listar reservas?

Com {{url}}/API/REST/ClientBackOffice.svc/GetBookingList. O corpo leva Credential e SearchBookingCriteria:

{
  "Credential": { "Username": "<usuario>", "Password": "<senha>" },
  "SearchBookingCriteria": {
    "InitialBookingDate": "2026-07-01T00:00:00",
    "FinalBookingDate": "2026-10-31T23:59:59",
    "BookingNumber": ["123456"]
  }
}

Em vez de BookingNumber, é possível filtrar por ExternalReference ou ServiceTypes. A resposta vem em Reservations (em algumas versões, BookingSearchResult ou Bookings).

Tags: backoffice status campos doc-oficial

Existe outra forma de listar reservas por e-mail?

Sim: {{url}}/API/REST/Hotel.svc/GetBookingList aceita PaxEmail, Locator, CheckInFrom e CheckInTo.

Tags: backoffice hotel campos

Quais campos vêm em cada reserva da listagem?

Entre outros: BookingId, ServiceId, ServiceType, Status, data da última atualização, data da reserva, data do serviço, passageiro principal, ExternalReference e preço (moeda e valor).

Tags: backoffice campos

Quais valores o ServiceType pode ter?

Segundo a documentação do ClientBackOffice, são oito: Hotel, Insurance, Tour, Transfer, RentACar, Flight, Circuit e Package. Na prática também aparecem Activity e Car nas respostas.

Tags: backoffice campos doc-oficial

Quais status existem?

Depende do método:

O ClientBackOffice.svc devolve status por extenso, como Confirmed, Cancelled e Rejected. Cancelled e Rejected são finais.

Tags: backoffice hotel status

Quais são os status oficiais de uma reserva?

Atenção à grafia oficial AwatingPayment (sem o "i").

Tags: backoffice reserva status doc-oficial

Quando posso considerar a reserva confirmada?

Só quando a API responder corretamente com status Confirmed.

Tags: geral reserva status doc-oficial

Recebi HTTP 4xx ou 5xx no DoBooking. O que fazer?

Não repita o DoBooking de imediato. Mantenha a reserva como pendente no seu sistema e siga o fluxo oficial:

1. Chame CheckBookingStatus (no serviço do produto, ex.: {{url}}/API/REST/Hotel.svc/CheckBookingStatus) para saber se a reserva existe.
2. Se ele devolver BookingId e ServiceId, consulte ClientBackOffice.svc/GetBookingDetail e verifique o status.
3. Se devolver erro (reserva inexistente), aí sim tente o DoBooking de novo.

Um HTTP 429 costuma indicar excesso de chamadas.

Tags: geral reserva erros status boas-praticas doc-oficial

Quais filtros o GetBookingList do ClientBackOffice aceita?

Em SearchBookingCriteria, todos opcionais:

• BookingNumber[], BookingStatus[], ExternalReference, PassengerName e ServiceTypes[];
• períodos de reserva (InitialBookingDate / FinalBookingDate), de serviço (InitialServiceDate / FinalServiceDate), de atualização (InitialUpdateDate / FinalUpdateDate), de cancelamento (CancelationDateStart / CancelationDateEnd) e de prazo de pagamento (PaymentDeadlineStart / PaymentDeadlineEnd).

Tags: backoffice campos datas doc-oficial

Para quem é o ClientBackOffice e o que mais ele oferece?

É para usuários no nível de cliente ou agência, para integrar com sistemas de backoffice e ERP. Além de listar, detalhar e cancelar reservas, ele tem:

• Authenticate — valida usuário e senha.
• GetLastFXRate — câmbio cadastrado para a agência, com CurrencyCodeFrom, CurrencyCodeTo e ServiceType.
• GetIncidents — lista ocorrências por BookingId, ServiceId, IncidentId, Status ou período de criação.
• CreatIncident — abre ocorrência para um serviço (BookingId, ServiceId, Title, Message, SendEmail). O nome do método é grafado assim, sem o "e".
• AddIncidentMessage — adiciona mensagem a uma ocorrência (OccurrenceId, Title, Message, Type: Request ou Occurrence).

Tags: backoffice autenticacao cambio doc-oficial

O que o CancelBooking do ClientBackOffice faz?

Cancela todos os serviços da reserva (BookingId). A resposta traz o status para confirmar o cancelamento. Se as políticas de cancelamento já estiverem em vigor, pode haver multa.

Tags: backoffice cancelamento doc-oficial

A reserva acabou de ser criada e não aparece na listagem. Por quê?

A indexação pode levar alguns segundos. Tente de novo após 2 s e depois 4 s.

Tags: backoffice reserva boas-praticas nao-confirmado

Como consultar uma reserva específica?

Com {{url}}/API/REST/Hotel.svc/GetBookingDetails (enviando BookingId) ou com {{url}}/API/REST/ClientBackOffice.svc/GetBookingDetail.

Tags: backoffice hotel reserva status

Como cancelar hotel, carro, passeio ou transfer?

Pela documentação oficial, cada serviço tem os próprios métodos de cancelamento: CancelAll<Produto>Services (cancela todos os serviços daquele produto na reserva, ex.: CancelAllHotelServices, CancelAllRentACarServices, CancelAllFlightServices, CancelAllTransferServices, CancelAllTourServices) e CancelByService (cancela serviços específicos por ServiceIds[]). O identificador é o ServiceId, não o BookingId. (não confirmado) Na prática, hotel.svc/CancelByService também foi usado com sucesso para carro, passeio e transfer.

Tags: hotel carro passeios transfer cancelamento doc-oficial

O cancelamento falhou com "não encontrado" numa reserva antiga. O que pode ser?

Reservas antigas podem ter sido emitidas em outro ambiente da Cangooroo. Tente o cancelamento no ambiente onde a reserva foi criada.

Tags: geral cancelamento erros nao-confirmado

Como cancelar ônibus?

1. Tente {{url}}/API/REST/ClientBackOffice.svc/CancelBooking com o BookingId (cancela a reserva inteira).
2. Se não efetivar, use {{url}}/API/REST/Bus.svc/CancelByService com ServiceIds[].
3. Confirme com GetBookingDetail: repita até 3 vezes, com 1,5 s de espera, até o status conter "cancel".

Tags: onibus cancelamento backoffice

Por que confirmar o cancelamento do ônibus?

O Bus.svc responde HTTP 200 sem corpo mesmo quando a viação não cancela. Só a releitura do status garante o resultado.

Tags: onibus cancelamento status boas-praticas

A API de políticas de cancelamento está fora do ar. Como reconhecer?

Mensagens contendo err_0238, RegraCancelamentoQuarto, BuscaRegraCancelamento ou GetCancellationPolicies, ou termos como "no endpoint listening", "service unavailable" e "bad gateway" junto de "cancel", indicam indisponibilidade temporária do serviço de políticas. Mostre uma mensagem amigável e tente mais tarde.

Tags: geral cancelamento erros

A URL do voucher não abre. O que corrigir?

A URL pode vir com pequenas inconsistências. Antes de abrir:

• troque http:// por https://;
• converta & em &;
• remova barras duplas no caminho (preservando o protocolo);
• codifique + solto na query string como %2B.

Tags: geral voucher boas-praticas

Outros serviços

Quais serviços a API oferece além dos desta FAQ?

A documentação oficial lista também Seguro (Insurance.svc) e Circuito (Circuit.svc). Ambos seguem o mesmo padrão dos demais: Search, GetBookingConditions, DoBooking, CancelAll<Produto>Services e CancelByService. Os contratos de Aéreo, Transfer, Passeios, Seguro e Circuito ainda constam como "tbd" (em definição) na documentação.

Tags: seguro circuito doc-oficial

Qual a diferença entre ClientBackOffice e CangoorooBackOffice?

Tags: backoffice cambio doc-oficial

Existe API para consultar destinos, hotéis e aeroportos?

Sim. A documentação tem uma seção separada, Commons API, com Autocomplete, Hotel Detail (inclui mídia dos quartos via RoomMediaId), Airport Detail e Destination Hierarchy.

Tags: geral hotel busca doc-oficial

Webhook

O que o webhook envia?

O detalhe completo da reserva, no mesmo formato do GetBookingDetail do CangoorooBackOffice.

Tags: webhook reserva doc-oficial

Como ativar o webhook?

O módulo precisa estar no contrato. Com ele ativo:

1. Entre na intranet da Cangooroo.
2. Acesse Registrations → Operator → Settings.
3. Marque a opção do webhook, preencha a URL que receberá a chamada HTTP e salve.

Tags: webhook configuracao doc-oficial

Como testar o webhook?

A documentação sugere ferramentas como o webhook.site para inspecionar as chamadas recebidas. A Cangooroo não dá suporte a essas ferramentas.

Tags: webhook boas-praticas doc-oficial

Suporte

O que enviar ao abrir um chamado no suporte?

Por e-mail para support@cangooroo.net, sempre com:

• identificação do cliente (empresa); integradores terceiros devem procurar primeiro o dono da licença;
• URL do endpoint chamado;
• requisição completa e resposta completa;
• descrição da dúvida ou do erro e o objetivo.

Cada demanda vira um chamado separado. Bugs e problemas conhecidos têm prioridade sobre dúvidas.

Tags: suporte boas-praticas doc-oficial

Integradores terceiros podem pedir suporte direto?

Só depois de cadastrados como desenvolvedores na Cangooroo. Antes disso, o contato é com o dono da licença.

Tags: suporte configuracao doc-oficial

O que o suporte não cobre?

Dúvidas sobre linguagens de programação, ferramentas de teste, infraestrutura ou servidores do integrador. O suporte cobre apenas a API Cangooroo.

Tags: suporte doc-oficial

Qual o horário de atendimento?

De segunda a sexta, das 9h às 18h (horário de Brasília), por e-mail, WhatsApp ou telefone. Fora desse horário, há um formulário de emergência. Telefone e emergência são só para casos graves (Cangooroo fora do ar ou fluxo de reserva com erro), nunca para dúvidas de integração.

Tags: suporte doc-oficial

Onde está a lista completa de códigos de erro?

Na página Errors da documentação oficial, que aponta para uma planilha com código, erro e descrição.

Tags: suporte erros doc-oficial

Referência rápida de endpoints

Todos os métodos usam POST com JSON e Credential no corpo.

Fontes

Documentação oficial Cangooroo (consultada em 19/10/2026):

• Services
• Hotel
• Payment
• ClientBackOffice
• FAQ
• FAQ – Retoken
• FAQ – Fluxo de erros de reserva
• Errors
• Webhook
• Webservice Support
• Coleção Postman

As demais respostas vêm da experiência de integração e estão marcadas com (não confirmado) quando não há confirmação oficial.