Resources for Developers

Add a search widget on your website or blog to send your visitors directly to our reservation system.

The search widget is designed to have a neutral appearance and standardized, mixing gently to your page and facilitating the recognition by your visitors.

For best results, apply the search widget at the top of the page, in a sidebar.

If your website is based on the platform WordPress.org We created a plugin for easy incorporation Search widget.

To install it, download it by plugin page on WordPress.org Or - via the administrative interface - click on the "Plugins" / "Add New" menu and look for "pousadinhas". Be sure to select the plugin " Pousadinhas Search Widget "!

If your website is based on the platform Joomla! We created a plugin for easy incorporation Search widget.

To install it, download it here and - through the administrative interface - click on the "Extensions" menu / "Install / Uninstall" continuing with the installation. For more information, visit plugin page in the extensions directory Joomla.org .

If you intend to use it "in situ" - ie without coupling it to the edge of the window - add the following {pousadinhas} the desired content.


a) Configuration

Below, use the form on the left to set the widget Search and preview the result in the right pane.

Options WidgetPreview
Processing ...
Select the destination for searches done using the widget.?
Uncheck this option to have the date fields are not initialized with default values.?
Select the language of your page.?
Select the corner of the screen where you want to dock the widget.?
Select this option if there is space constraint in the layout of your page.?
If your page is secure (https protocol) you should select this option.?

b) Implementation

Step 1. The code below should be inserted into your page, just above the tag </HEAD> Closing header.

Step 2. The code below should be inserted into your page, exactly where you want the widget to appear Search.

1. Application Registration

To use the Pousadinhas API it is necessary that the client application is registered on our platform. Please contact us via e-mail recursos@pousadinhas.com.br and provide the name and a detailed description of the application or integration that want to develop, indicating the features you will use.

2. Development and approval

By approving your application registration request, we will create an account for you in our testing environment and expediremos access credentials for use in development.

Completed the development, it is necessary to contact us again, providing instructions for access to the application, so our team can conduct tests. Only after the approval of the application, expediremos access credentials to the production environment.

3. Access credentials

The access credentials of client applications in our platform are composed of two pieces of information:

  • client_id - Client application identifier, public;
  • client_secret - Secrecy of the client application, private;

Access credentials can not be used for direct access Pousadinhas API . But they are necessary to obtain an access token ( access_token ), With the API authentication mechanism; then this token will be used to access the API.

The client application must maintain client_secret in absolute secrecy and shall request the return of the same whenever there is any suspected compromise.

In case of applications that will be deployed on untrusted devices (eg mobile applications), the client_secret must be stored overshadowed. In addition, the client application should prompt the user to do the update is applied whenever there is an indication of the error exchange client_secret .

4. Data encryption

All requests and responses sent and received in both authentication mechanism and API, use UTF-8 encoding.

5. Authentication mechanism

The authentication mechanism Pousadinhas API is based on the standard OAuth 2.0 . All access to the API must be made using an access token ( access_token ) Previously obtained through this mechanism.

The routines of obtaining and renewing access tokens are carried out through POST type requests to the following URL:

https://www.pousadinhas.com.br/oauth2/token?idioma=en

The application credentials should be informed of these requests through basic authentication URL, or through the POST variables client_id and client_secret .

The types of grant ( grant_type ) Supported by the authentication mechanism OAuth 2.0 implemented are: client_credentials , password and refresh_token . Please refer to the instructions OAuth 2.0 for additional parameters for each type of grant.

On success the authentication mechanism returns the code 200 and the result in JSON format, containing the access token ( access_token ), Its validity ( expires_in ) The access scope ( scope ) And optionally a token replacement ( refresh_token ).

In case of error the authentication mechanism returns the 400 code and the result in JSON format, containing the code OAuth 2.0 error ( error ) And a more detailed error description in English ( error_description ).

Getting an access token

To obtain an access token is required to submit a POST request to the URL authentication using the types of grant client_credentials or password .

By type of grant client_credentials You can get a token to access the platform of public data.

By type of grant password You can get a token to access public data and user data platform whose access credentials were provided in the request.

In granting password In addition to the access token, is also returned a token renewal ( refresh_token ) To be stored by the application and used to obtain a new access token so that the access token in use expires.

Where the application is making the request on behalf of an authenticated user, it should use the access token obtained by granting password . This should be observed even when accessed data can be obtained also through a token obtained through the type of grant client_credentials .

In no case the application should store the access credentials provided by persistently user. The application must ensure that the user-supplied credentials are discarded immediately after authentication and are not included by mistake in logs or pursuant to debug files.

The type of grant password is only released to the partner application platform client given the high level of confidence required by users to provide their access credentials.

Renewing an access token

For a new access token, which will replace an expired token, you must submit a POST request to the URL authentication using the type of grant refresh_token .

To get a new access token, the token old renovation will be repealed and should be replaced by new renovation token issued.

Before any access Pousadinhas API , The client application must first check the validity of the access token, renewing it if necessary. The use of an expired token generates an error in the API call (code 401) which should also be treated, by obtaining a new token and the subsequent retry.

6. API Structure

Access Pousadinhas API is calculated using the following base URL:

https://www.pousadinhas.com.br/api/v2/?idioma=en

The structure of the API access URLs from the URL base, follows a pattern that is divided into 4 grades:

  • /collection - Access to collection of objects;
  • /collection/{id} - Access to a collection object by identifier;
  • /collection/{id}/property - Access to a property of an object in the collection by the identifier and the name of the property;
  • /collection/name - Access to a transaction relating to one or more objects in the collection;

The Pousadinhas API follows the REST principles and HTTP protocol access patterns. The accessibility is organized as follows:

  • GET requests to read objects;
  • PUT requests for writing objects;
  • POST requests to create objects;
  • DELETE requests for removal of objects;

See the full list of API Resources .

7. Data format

The Pousadinhas API working with JSON format and optionally JSONP to GET type requests (returned when use is made of the parameter callback ).

All requests return, in addition to appropriate HTTP code, a JSON object with sequintes fields:

  • meta - Contains the HTTP return code ( code ) And, in case of error, the error description in English ( error_detail ) And error messages on the language set in the request ( error_messages ) Indicating the field that is associated with the error;
  • data - Contains the requested data;
  • caching - Contains the identifying key object ( hashkey ) And the data expiration time ( expires_in ) Used to optimize the traffic between the client application and the Pousadinhas API in the GET and PUT requests type;

POST and PUT requests, they shall submit the request content in JSON format in the body of the request and inform the header "Content-Type" and "application / json".

8. Data Caching

The Pousadinhas API implements a simple caching mechanism inspired by the native caching mechanism of the HTTP protocol.

In the GET and PUT requests, to inform the parameter hashkey (Or header If-None-Match ) The service will compare it with the result hash key and return it only when it does not match; thus saving the traffic information to the client application.

These requests the service returns the field caching containing the object hash key to be returned ( hashkey ) And expiration time data ( expires_in ). If the request has been made by using the header If-None-Match This information is returned via the header Etag and the policy max-age header Cache-Control Respectively.

When there is correspondence between the hash key and informed the hash key returned, the service returns the 304 code and omits the field data .

The client application should not submit a second GET request, to the same URL API, with exactly the same parameters when data there are not expired according to the field expires_in .

9. Pagination

The paging data via the API should be made using the URL parameters offset and limit . Parameter offset sets the page starting point. Parameter limit sets the page size. To go to the next page of results, simply submit the same application request but increasing the value of the field offset the field value limit .

To bring all data use the page size*Noting that this should be avoided for data of arbitrary size.

10. Ordination

The results of API requests can be ordered using the URL parameter sortby . This parameter defines which fields should be used in order, according to the sequence in which they are specified. The use of the suffix "-" causes the sort happens in a decreasing order.

For example, sortby=price-,name will order a collection of input data for the price, highest to lowest, and if two objects have the same price, the name of the object.

11. Fields filter

Via parameter fields you can define the fields to be returned by the API.

It is possible to define not only the fields to filter the returned object but also the objects referenced by the latter with arbitrary depth. You can also set the number of objects to return the collections that make up the object. Field id of objects is always returned and need not be specified.

For example, fields=name,place{name,photos(10)},photos(10){id} will the fields id , name , place.id and place.name , And field 10 id photos of fate and inn.

To bring all the objects in a collection use*Noting that this should be avoided for collections of arbitrary size.

12. Simulation run

Through Pousadinhas API You can simulate the execution (dry run) of POST / PUT without actually modifying the data requests, but it is possible to detect validation errors. For this simply specify the URL variable dryrun=1 in the request.

13. Standard parameters

The Pousadinhas API supports some URL pattern parameters (GET variables) that apply symmetrically to the various API services.

  • access_token - This variable must contain the valid access token obtained through the authentication mechanism OAuth 2.0 ;
  • callback - This variable specifies the function name that will be used in the return in JSONP format is limited to GET requests type;
  • hashkey - This variable contains the expected hash key to the data, if the value matches the value to be returned, the data is not sent back to the client;
  • fields - This variable describes the structure of data to be returned, hierarchically indicating the fields to be returned;
  • dryrun - This variable stipulates that the POST / PUT method should only simulate the request without actually changing the data; useful for testing and also data validation prior to submission;
  • sortby - This variable specifies which fields of the collection should be used to sort the result;
  • offset - This variable specifies the paging starting point;
  • limit - This variable specifies the size of the page;

14. Limitation on rate requests

To prevent abuse, Pousadinhas API keeps a record of access to the API that must be made within the pre-set quota of the client application.

The quota varies by type of request and access token, which may vary also by the API service. GET requests type has a higher dimension that requests POST type / PUT / DELETE. Access by token obtained by granting client_credentials enter the application of the quota, being shared by all instances. Have access by token obtained by granting password enter the user's quota, being shared by other client applications that use the same.

The size of the quota and the number of remaining requests are reported in the return of each API request through the headers X-RateLimit-Limit and X-RateLimit-Remaining Respectively.

To exceed the quota, the API will return to the client application code 429 and, in the header Retry-After The number of seconds the application waits before submitting a new attempt.

The client application must show the user a timer when you are waiting due to the bursting of the quota, allowing cancellation of the operation. It is also recommended that the client application suggests the user to log in to remedy the temporary quota restriction, if it does not find authenticated.

The limits on the application of rate requests can be reviewed on a case by request to our team.

15. Location

The location, in terms of language, currency and time zone, the calls fromPousadinhas APImust be made via the following URL parameters (GET variables):

  • language-This variable indicates the language that will be used in the messages returned by the API;
  • currency-This variable indicates the currency that will be used in the price returned by the API;
  • timezone-This variable indicates the time zone that will be used in the date/time encodings returned by the API;

ThePousadinhas APIalways returns the data according to these parameters, regardless of the setting of the user account associated with the access token used in the request.

16. Return Codes

Below is a list of return codes for success or error returned by the API and the situations in which they occur:

  • 200 - Success in implementing the operation;
  • 201 - Success in creating a new object;
  • 304 - Success in implementing the operation, but the informed object hash key coincided and data were omitted;
  • 400 - Not safe HTTP access; Mandatory parameters or variables not reported; Additional parameters or variables not recognized; Invalid parameters or variables; No such object or invalid JSON; Field upgrade that allows read-only; Dry run not supported;
  • 401 - Lack of access token; Token Invalid access, expired or revoked; Access denied the application;
  • 403 - Insufficient permissions to make the request;
  • 404 - Resource (collection, object, etc.) there;
  • 405 - Requisition type not supported;
  • 409 - Failed to create / update / removal of an object;
  • 429 - Exceeded quota access;

17. Console access

To become familiar with the Pousadinhas API , Visit API Console powered by Apigee.

The Environment Tests POUSADINHAS.COM.BR fictitious environment is a completely self-contained and identical in functionality to the production environment. Through it, you can test all the functionality of our platform in a completely isolated from reality and without affecting its operation.

If you are interested in accessing our Test Environment, please send an email to recursos@pousadinhas.com.br identifying and describing the reasons for his request.