Recursos para Desenvolvedores

Adicione um Widget de Busca em seu website ou blog para encaminhar seus visitantes diretamente ao nosso sistema de reservas.

O Widget de Busca foi desenvolvido para ter uma aparência neutra e padronizada, mesclando suavemente à sua página e facilitando o reconhecimento por seus visitantes.

Para obter melhores resultados, aplique o Widget de Busca na parte superior da página, em uma coluna lateral.

Se seu website é baseado na plataforma WordPress.org, criamos um plugin para fácil incorporação do Widget de Busca.

Para instalá-lo, baixe-o pela página do plugin no WordPress.org; ou – através da interface administrativa – clique no menu “Plugins” / “Adicionar Novo” e procure por “pousadinhas”. Certifique-se de selecionar o plugin “Pousadinhas Search Widget”!

Se seu website é baseado na plataforma Joomla!, criamos um plugin para fácil incorporação do Widget de Busca.

Para instalá-lo, baixe-o aqui e – através da interface administrativa – clique no menu “Extensões” / “Instalar/Desinstalar” prosseguindo com a instalação. Para mais informações, visite a página do plugin no diretório de extensões do Joomla.org.

Caso pretenda utilizá-lo “in loco” – isto é, sem acoplá-lo à borda da janela – acrescente a sequência {pousadinhas} ao conteúdo desejado.


a) Configuração

Abaixo, use o formulário à esquerda para configurar o Widget de Busca e pré-visualize o resultado no painel à direita.

Opções do WidgetPré-visualização
Processando...
Selecione o destino para buscas feitas usando o Widget.?
Desmarque esta opção para que os campos de data não sejam inicializados com valores padrão.?
Selecione o idioma de sua página.?
Selecione o canto da tela no qual você deseja acoplar o Widget.?
Marque esta opção se houver restrição de espaço no layout de sua página.?
Se sua página é segura (protocolo https) você deve selecionar esta opção.?

b) Implementação

Passo 1. O código abaixo deve ser inserido em sua página, logo acima da tag </HEAD> de fechamento do cabeçalho.

Passo 2. O código abaixo deve ser inserido em sua página, exatamente onde você deseja que o Widget de Busca seja exibido.

1. Registro da aplicação

Para usar a API do Pousadinhas é necessário que a aplicação cliente seja registrada em nossa plataforma. Entre em contato conosco através do e-mail recursos@pousadinhas.com.br e forneça o nome e uma descrição detalhada da aplicação ou integração que deseja desenvolver, indicando quais as funcionalidades irá utilizar.

2. Desenvolvimento e homologação

Ao aprovarmos sua solicitação de registro da aplicação, criaremos uma conta para você em nosso Ambiente de Testes e expediremos as credenciais de acesso para serem utilizadas no desenvolvimento.

Concluído o desenvolvimento, é necessário entrar em contato novamente conosco, fornecendo instruções de acesso à aplicação, para que nossa equipe possa conduzir testes. Somente após a homologação da aplicação, expediremos as credenciais de acesso para o ambiente de produção.

3. Credenciais de acesso

As credênciais de acesso das aplicações cliente em nossa na plataforma são compostas de duas informações:

  • client_id - identificador da aplicação cliente, público;
  • client_secret - segredo da aplicação cliente, privado;

As credenciais de acesso não podem ser usadas para acesso direto à API do Pousadinhas. Porém elas são necessárias para a obtenção um token de acesso (access_token), junto ao mecanismo de autenticação da API; este token então deverá ser usado no acesso à API.

A aplicação cliente deve manter o client_secret no mais absoluto sigilo e deverá solicitar a troca do mesmo imediatamente sempre que houver suspeita de comprometimento.

Em caso de aplicativos que serão implantados em dispositivos não confiáveis (e.g. aplicativos móveis), o client_secret deverá ser armazenado ofuscado. Além disto, a aplicação cliente deverá solicitar ao usuário que faça a atualização da aplicação sempre que houver erro indicativo de troca do client_secret.

4. Codificação dos dados

Todas as requisições e respostas, enviadas e recebidas, de ambos, mecanismo de autenticação e API, utilizam a codificação UTF-8.

5. Mecanismo de autenticação

O mecanismo de autenticação da API do Pousadinhas é baseado no padrão OAuth 2.0. Todo acesso à API deve ser feito usando um token de acesso (access_token) previamente obtido através deste mecanismo.

As rotinas de obtenção e renovação de tokens de acesso são realizadas através de requisições do tipo POST à seguinte URL:

https://www.pousadinhas.com.br/oauth2/token

As credenciais da aplicação deverão ser informadas nestas requisições através da autenticação básica de URL, ou através das variáveis de POST client_id e client_secret.

Os tipos de concessão (grant_type) suportados pelo mecanismo de autenticação OAuth 2.0 implementados são: client_credentials, password e refresh_token. Por favor consultar a documentação do OAuth 2.0 para obter parâmetros adicionais de cada tipo de concessão.

Em caso de sucesso o mecanismo de autenticação retorna o código 200 e o resultado, em formato JSON, contendo o token de acesso (access_token), seu prazo de validade (expires_in), o escopo de acesso (scope) e, opcionalmente, um token de renovação (refresh_token).

Em caso de erro o mecanismo de autenticação retorna o código 400 e o resultado, em formato JSON, contendo o código OAuth 2.0 do erro (error) e uma descrição mais detalhada do erro em inglês (error_description).

Obtendo um token de acesso

Para obter um token de acesso é necessário submeter uma requisição POST à URL de autenticação usando os tipos de concessão client_credentials ou password.

Através do tipo de concessão client_credentials é possível obter um token para acessar os dados públicos da plataforma.

Através do tipo de concessão password é possível obter um token para acessar os dados públicos da plataforma bem como os dados do usuário cujas credenciais de acesso foram fornecidas na requisição.

Na concessão password, além do token de acesso, é retornado também um token de renovação (refresh_token) que deve ser armazenado pela aplicação e utilizado para obtenção de um novo token de acesso assim que o token de acesso em uso expire.

Sempre que a aplicação estiver fazendo a requisição em nome de um usuário autenticado, a mesma deverá utilizar o token de acesso obtido através da concessão password. Isto deve ser observado mesmo quando os dados acessados possam ser obtidos também através de um token obtido através do tipo de concessão client_credentials.

Em nenhuma hipótese a aplicação deverá armazenar as credenciais de acesso fornecidas pelo usuário de maneira persistente. A aplicação deve garantir que as credenciais fornecidas pelo usuário sejam descartadas imediatamente após a autenticação e não sejam incluídas por descuido em logs ou em arquivos de depuração da aplicação.

O tipo de concessão password só é liberado para aplicações cliente parceiras da plataforma dado o alto nível de confiança exigido pelos usuários ao fornecerem suas credenciais de acesso.

Renovando um token de acesso

Para obter um novo token de acesso, que irá substituir um token expirado, é necessário submeter uma requisição POST à URL de autenticação usando o tipo de concessão refresh_token.

Ao obter um novo token de acesso, o token de renovação antigo será revogado e deverá ser substituído pelo novo token de renovação expedido.

Antes de qualquer acesso à API do Pousadinhas, a aplicação cliente deverá primeiramente verificar a validade do token de acesso, renovando-o caso necessário. O uso de um token expirado gera um erro na chamada da API (código 401) que também deverá ser tratado, através da obtenção de um novo token e a subsequente retentativa.

6. Estrutura da API

O acesso à API do Pousadinhas é realizado através da seguinte URL base:

https://www.pousadinhas.com.br/api/v2/

A estrutura das URLs de acesso da API, a partir da URL base, segue um padrão que está divido em 4 tipos:

  • /collection - acesso a coleção de objetos;
  • /collection/{id} - acesso a um objeto da coleção pelo identificador;
  • /collection/{id}/property - acesso a uma propriedade de um objeto da coleção pelo identificador e o nome da propriedade;
  • /collection/name - acesso a uma operação relacionada a um ou mais objetos da coleção;

A API do Pousadinhas segue os princípios REST e os padrões de acesso do protocolo HTTP. Os acessos são organizados da seguinte forma:

  • Requisições GET para leitura de objetos;
  • Requisições PUT para escrita de objetos;
  • Requisições POST para criação de objetos;
  • Requisições DELETE para remoção de objetos;

Veja a lista completa de Recursos da API.

7. Formato dos dados

A API do Pousadinhas trabalha com o formato JSON e, opcionalmente, JSONP para requisições do tipo GET (retornado quando é feito uso do parâmetro callback).

Todas as requisições retornam, além do código HTTP adequado, um objeto JSON com os sequintes campos:

  • meta - contem o código de retorno HTTP (code) bem como, em caso de erro, a descrição do erro em inglês (error_detail) e as mensagens de erro localizadas no idioma definido na requisição (error_messages) indicando o campo que está associado ao erro;
  • data - contém os dados solicitados;
  • caching - contém a chave identificadora do objeto (hashkey) e o prazo de expiração dos dados (expires_in) utilizados para otimização do trafego entre a aplicação cliente e a API do Pousadinhas em requisições do tipo GET e PUT;

Requisições do tipo POST e PUT, devem submeter o conteúdo da requisição em formato JSON no corpo da requisição e informar o cabeçalho “Content-Type” sendo “application/json”.

8. Caching de dados

A API do Pousadinhas implementa um mecanismo simples de caching inspirado no mecanismo nativo de caching do protocolo HTTP.

Nas requisições GET e PUT, ao informar o parâmetro hashkey (ou o cabeçalho If-None-Match) o serviço irá compará-lo com a chave hash do resultado e retorná-lo apenas quando a mesma não corresponde; dessa forma economizando no trafego de informações com a aplicação cliente.

Nestas requisições o serviço retorna o campo caching que contém a chave hash do objeto a ser retornado (hashkey) e o tempo de expiração dos dados (expires_in). No caso da requisição ter sido feita usando o cabeçalho If-None-Match, estas informações são retornadas através do cabeçalho Etag e a diretiva max-age do cabeçalho Cache-Control, respectivamente.

Quando há correspondência entre a chave hash informada e a chave hash retornada, o serviço retorna o código 304 e omite o campo data.

A aplicação cliente não deve submeter uma segunda requisição do tipo GET, para a mesma URL da API, exatamente com os mesmos parâmetros, quando os dados ainda não houverem expirado de acordo com o campo expires_in.

9. Paginação

A paginação de dados obtidos através da API deve ser feita usando os parâmetros de URL offset e limit. O parâmetro offset define o ponto de início da página. O parâmetro limit define o tamanho da página. Para ir para a próxima página de resultados, basta aplicação submeter a mesma requisição porém acrescentando ao valor do campo offset o valor do campo limit.

Para trazer todos os dados use o tamanho da página *, observando que isto deve ser evitado para dados de tamanho arbitrário.

10. Ordenação

Os resultados de requisições da API podem ser ordenados usando o parâmetro de URL sortby. Este parâmetro define quais campos devem ser usados na ordenação, de acordo com a sequência em que são especificados. O uso do sufixo “-” faz com que a ordenação aconteça de maneira decrescente.

Por exemplo, sortby=price-,name ordenará uma coleção de dados primeiramente pelo preço, do mais caro ao mais barato, e, caso dois objetos tenham o mesmo preço, pelo nome do objeto.

11. Filtro de campos

Através do parâmetro fields é possível definir os campos a serem retornados pela API.

É possivel definir não somente os campos a serem filtrados do objeto retornado mas também dos objetos referênciados por este, com profundidade arbitrária. Também é possível definir a quantidade de objetos a serem retornados das coleções que compõem o objeto. O campo id dos objetos é sempre retornado e não precisa ser especificado.

Por exemplo, fields=name,place{name,photos(10)},photos(10){id} trará os campos id, name, place.id e place.name, além de 10 campos id de fotos do destino e da pousada.

Para trazer todos os objetos de uma coleção use *, observando que isto deve ser evitado para coleções de tamanho arbitrário.

12. Simulação de execução

Através da API do Pousadinhas é possível simular a execução (dry run) das requisições POST/PUT sem de fato modificar os dados, porém sendo possível detectar erros de validação. Para isto basta especificar a variável de URL dryrun=1 na requisição.

13. Parâmetros padrão

A API do Pousadinhas suporta alguns parâmetros padrão de URL (variáveis GET) que se aplicam de maneira simétrica aos diversos serviços da API.

  • access_token - esta variável deve conter o token de acesso válido obtido através do mecanismo de autenticação OAuth 2.0;
  • callback - esta variável indica o nome da função que será usada no retorno no formato JSONP, limita-se a requisições do tipo GET;
  • hashkey - esta variável contem a chave hash esperada para os dados, caso o valor coincida com o valor a ser retornado, os dados não são enviados novamente para o cliente;
  • fields - esta variável descreve a estrutura dos dados a serem retornados, indicando hierarquicamente os campos a serem retornados;
  • dryrun - esta variável estipula que o método POST/PUT deve apenas simular a requisição sem de fato alterar os dados; util para testes e também a validação de dados antes da submissão;
  • sortby - esta variável indica quais campos da coleção deverão ser usados para ordenar o resultado;
  • offset - esta variável indica o ponto de início da paginação;
  • limit - esta variável indica o tamanho da página;

14. Limitação na taxa de requisições

Para evitar abusos, a API do Pousadinhas mantém um registro de acessos à API que devem ser efetuados dentro da cota pré-definida da aplicação cliente.

A cota varia por tipo de requisição e por token de acesso, podendo variar também por serviço da API. Requisições do tipo GET tem uma cota maior que requisições do tipo POST/PUT/DELETE. Os acessos por token obtido através da concessão client_credentials entram na cota da aplicação, sendo compartilhado por todas as instâncias. Já os acessos por token obtido através da concessão password entram na cota do usuário, sendo compartilhado por outras aplicações cliente que o mesmo utilize.

O tamanho da cota e o número de requisições restantes são informados no retorno de cada requisição da API através dos cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining, respectivamente.

Ao exceder a cota, a API retornará à aplicação cliente o código 429 e, no cabeçalho Retry-After, o número de segundos que a aplicação deverá aguardar antes de submeter uma nova tentativa.

A aplicação cliente deve mostrar ao usuário um temporizador sempre que estiver aguardando devido ao estouro da cota, permitindo o cancelamento da operação. Também é recomendável que a aplicação cliente sugira ao usuário autenticar-se para sanar a restrição de cota temporária, caso o mesmo não se encontre autenticado.

Os limites na taxa de requisições da aplicação podem ser revistos, caso a caso, através de solicitação à nossa equipe.

15. Localização

A localização, em termos de idioma, moeda e fuso horário, nas chamadas da API do Pousadinhas deve ser feita através dos seguintes parâmetros de URL (variáveis GET):

  • language - esta variável indica o idioma que será usado nas mensagens retornadas pela API;
  • currency - esta variável indica a moeda que será usada nos preços retornados pela API;
  • timezone - esta variável indica o fuso horário que será usado nas codificações de data/hora retornadas pela API;

A API do Pousadinhas sempre retorna os dados de acordo com estes parâmetros, independentemente da configuração da conta de usuário associada ao token de acesso usado na requisição.

16. Códigos de retorno

Abaixo segue a lista de códigos de retorno, para sucesso ou erro, devolvidos pela API e as situações em que ocorrem:

  • 200 - Sucesso na execução da operação;
  • 201 - Sucesso na criação de um novo objeto;
  • 304 - Sucesso na execução da operação, porém a chave hash do objeto informada coincidiu e os dados foram omitidos;
  • 400 - Acesso via HTTP não seguro; Parâmetros ou variáveis obrigatórias não informadas; Parâmetros ou variáveis adicionais não reconhecidas; Parâmetros ou variáveis inválidas; Objeto JSON inexistente ou inválido; Atualização de campo que permite somente leitura; Dry run não suportado;
  • 401 - Falta do token de acesso; Token de acesso inválido, expirado ou revogado; Acesso negado ao recurso;
  • 403 - Permissões insuficientes para efetuar a requisição;
  • 404 - Recurso (coleção, objeto, etc) não existe;
  • 405 - Tipo da requisição não suportado;
  • 409 - Falha na criação/atualização/remoção de um objeto;
  • 429 - Cota de acesso excedida;

17. Console de acesso

Para se familiarizar com a API do Pousadinhas, acesse o Console da API powered by Apigee.

O Ambiente de Testes do POUSADINHAS.COM.BR é um ambiente fictício completamente auto-contido e idêntico em funcionalidade ao ambiente de produção. Através dele, é possível testar toda a funcionalidade de nossa plataforma de maneira totalmente isolada da realidade e sem afetar seu funcionamento.

Caso tenha interesse em acessar nosso Ambiente de Testes, por favor, envie um e-mail para recursos@pousadinhas.com.br se identificando e descrevendo os motivos que justificam sua requisição.