A API do Cangooroo está disponível em dois formatos: SOAP e REST.

Endpoint

O endpoint da API é disponibilizado pelo operador responsável pela instância do Cangooroo com a qual sua aplicação irá se integrar.

Em geral, a URL segue o padrão abaixo:

https://ws-[identificacaoDoCliente].cangooroo.net

As informações específicas do ambiente, incluindo URL e credenciais de acesso, serão fornecidas durante o processo de integração.

SOAP

SOAP (Simple Object Access Protocol) é um protocolo de comunicação utilizado para troca de mensagens estruturadas entre aplicações.

As mensagens são transmitidas em formato XML e normalmente utilizam HTTP como protocolo de transporte. Por ser um padrão amplamente utilizado em integrações corporativas, oferece alta interoperabilidade entre diferentes plataformas e tecnologias.

REST

REST (Representational State Transfer) é um estilo arquitetural para desenvolvimento de APIs.

As APIs REST utilizam requisições HTTP para acessar e manipular recursos, permitindo uma comunicação simples, stateless (sem armazenamento de estado da sessão) e amplamente compatível com aplicações modernas.

As mensagens são enviadas e recebidas em formato JSON.

Como realizar requisições

Nas APIs REST, a comunicação acontece por meio de requisições HTTP enviadas pelo cliente ao servidor.

Cada requisição é composta pelos seguintes elementos:

• Método HTTP (HTTP Verb), que define a operação a ser executada;
• Endpoint do recurso desejado;
• Cabeçalhos HTTP (Headers), contendo informações adicionais da requisição;
• Corpo da requisição (Request Body), quando aplicável.

Métodos HTTP

A API utiliza os métodos HTTP padrão para manipulação dos recursos.

Header Accept

As respostas da API são retornadas no formato JSON.

Embora atualmente o envio do header Accept não seja obrigatório, recomenda-se incluí-lo em todas as requisições para garantir compatibilidade com futuras versões da API.

Accept: application/json

Exemplo:

POST https://ws-[identificacaoDoCliente].cangooroo.net/API/REST/... HTTP/1.1 
Accept: application/json

Códigos de resposta HTTP

A API utiliza os códigos de status HTTP para indicar o resultado de cada requisição.

Formato das mensagens

Os serviços REST do Cangooroo utilizam JSON como formato padrão para envio e recebimento de dados.

Ao montar uma requisição JSON:

• Valores do tipo texto devem ser enviados entre aspas duplas (").
• Valores numéricos devem ser enviados sem aspas.
• Valores booleanos devem utilizar true ou false.

Esse formato torna a comunicação simples, legível e compatível com praticamente qualquer linguagem de programação.

Compressão GZip

Todos os endpoints da API oferecem suporte à compressão GZip.

Recomenda-se habilitar esse recurso em sua aplicação, pois ele reduz o volume de dados trafegados entre cliente e servidor, diminuindo o consumo de banda e melhorando o tempo de resposta das requisições.

Ferramentas recomendadas

Durante o desenvolvimento e homologação da integração, algumas ferramentas podem facilitar os testes e a análise de requisições.

As mais utilizadas são:

• SoapUI: testes de Web Services SOAP;
• Postman: testes de APIs REST;
• Fiddler: captura e inspeção de requisições e respostas HTTP.

Essas ferramentas são apenas recomendações e não fazem parte do suporte oficial do Cangooroo.

Também recomendamos acompanhar a página de atualizações da documentação para conhecer novos recursos, melhorias e alterações da API.

Autenticação

O acesso aos recursos da API é controlado por meio de credenciais e de um token de autenticação.

Ambos são necessários durante o fluxo de integração.

Credenciais

As credenciais são fornecidas pelo operador responsável pela instância do Cangooroo utilizada pela sua empresa.

Normalmente são compostas por:

• UserName
• Password

Essas credenciais identificam e autenticam a aplicação que está consumindo a API.

Token

Além das credenciais, determinadas operações exigem um Token, gerado automaticamente durante a consulta de disponibilidade.

Sempre que uma requisição de disponibilidade (Availability) é realizada, a resposta retorna um token exclusivo, vinculado às credenciais utilizadas e aos dados retornados naquela pesquisa.

Esse token deve ser armazenado pela aplicação e utilizado nas etapas seguintes do fluxo de reserva, garantindo que todas as informações permaneçam consistentes entre a consulta e a confirmação da reserva.

Cada pesquisa gera um token diferente, independentemente do serviço consultado.

Validade do Token

O token permanece válido por 30 minutos após sua geração.

Caso esse período seja excedido antes da confirmação da reserva, será necessário realizar uma nova consulta de disponibilidade para obter um novo token.

Timezone

Salvo quando explicitamente informado na documentação de um método específico, não envie informações de fuso horário (timezone) nas requisições.

Quando um endpoint exigir esse tipo de informação, a documentação correspondente apresentará o formato esperado.