Ressources pour les développeurs

Ajouter un widget de recherche sur votre site ou blog pour envoyer vos visiteurs directement à notre système de réservation.

Le widget de recherche a été développé pour avoir un regard neutre et standardisée, en mélangeant doucement à votre page et à faciliter la reconnaissance par vos visiteurs.

Pour de meilleurs résultats, appliquer le widget de recherche en haut de la page, dans une barre latérale.

Si votre site est basé sur la plate-forme WordPress.org Nous avons créé un plugin pour faciliter le widget de recherche d'incorporation.

Pour l'installer, téléchargez-le en page du plugin sur WordPress.org ; ou - par l'intermédiaire de l'interface d'administration - cliquez sur les "plugins" / "Ajouter un nouveau" menu et rechercher "pousadinhas". Veillez à sélectionner le plugin " Pousadinhas Search Widget "!

Si votre site est basé sur la plate-forme Joomla! Nous avons créé un plugin pour faciliter le widget de recherche d'incorporation.

Pour l'installer, télécharger ici et - grâce à l'interface d'administration - cliquez sur le "Extensions" / menu "Installation / désinstallation" de poursuivre l'installation. Pour plus d'informations, visitez le site page du plugin dans le répertoire des extensions Joomla.org .

Si vous avez l'intention de l'utiliser "in situ" - c'est à dire sans la coupler au bord de la fenêtre - ajouter ce qui suit {pousadinhas} le contenu souhaité.


a) Configuration

Ci-dessous, utilisez le formulaire sur la gauche pour régler le widget de recherche et prévisualiser le résultat dans le volet de droite.

Options WidgetAvant-première
Traitement en cours ...
Sélectionnez la destination de recherches effectuées à l'aide du widget.?
Décochez cette option pour que les champs de date ne sont pas initialisés avec les valeurs par défaut.?
Sélectionnez la langue de votre page.?
Sélectionnez le coin de l'écran où vous souhaitez ancrer le widget.?
Cochez cette option s'il ya contrainte d'espace dans la présentation de votre page.?
Si votre page est sécurisée (protocole https), vous devez sélectionner cette option.?

b) La mise en œuvre

Étape 1. Le code ci-dessous doit être inséré dans votre page, juste au-dessus de la balise </HEAD> fermeture de tête.

Étape 2. Le code ci-dessous doit être inséré dans votre page, exactement là où vous voulez que le widget semble Recherche.

1. Enregistrement de l'application

Pour utiliser le L'API Pousadinhas il est nécessaire que l'application client est inscrit sur la plateforme. Se il vous plaît nous contacter par e-mail recursos@pousadinhas.com.br et fournir le nom et une description détaillée de l'application ou de l'intégration qui veulent développer, indiquant les fonctionnalités que vous allez utiliser.

2. Élaboration et approbation

En approuvant votre demande d'inscription de l'application, nous allons créer un compte pour vous dans notre environnement de test et expediremos accéder informations d'identification pour l'utilisation dans le développement.

Terminé le développement, il est nécessaire de nous contacter de nouveau, donnant des instructions pour l'accès à l'application, afin que notre équipe peut effectuer des tests. Ce ne est qu'après l'approbation de la demande, l'accès expediremos informations d'identification pour l'environnement de production.

3. Informations d'identification

Les autorisations d'accès des applications de clients dans notre plate-forme sont composées de deux éléments d'information:

  • client_id - Identification de la demande du client, du public;
  • client_secret - Le secret de l'application cliente, privée;

Informations d'identification ne peuvent pas être utilisés pour un accès direct L'API Pousadinhas . Mais ils sont nécessaires pour obtenir un jeton d'accès ( access_token ), Avec le mécanisme d'authentification de l'API; alors ce jeton sera utilisé pour accéder à l'API.

L'application client doit maintenir client_secret dans le secret absolu et demande le retour de la même à chaque fois que l'on soupçonne compromis.

En cas de demandes qui seront déployées sur les périphériques non fiables (par exemple, les applications mobiles), le client_secret doivent être stockés éclipsé. En outre, l'application client doit demander à l'utilisateur de faire la mise à jour est appliquée chaque fois qu'il ya une indication de l'échange d'erreur client_secret .

4. Le cryptage des données

Toutes les demandes et les réponses envoyées et reçues dans les deux mécanisme d'authentification et API, utilisent encodage UTF-8.

5. mécanisme d'authentification

Le mécanisme d'authentification L'API Pousadinhas est basé sur la norme OAuth 2.0 . Tous les accès à l'API doit être faite en utilisant un jeton d'accès ( access_token ) Auparavant obtenu grâce à ce mécanisme.

Les routines d'obtention et de renouvellement de jetons d'accès sont effectuées par requêtes de type POST à ​​l'URL suivante:

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

Les références d'application devraient être informés de ces demandes par le biais base URL d'authentification, ou par les variables de POST client_id et client_secret .

Les types de subvention ( grant_type ) Pris en charge par le mécanisme d'authentification OAuth 2.0 mis en œuvre sont: client_credentials , password et refresh_token . Se il vous plaît se référer aux instructions OAuth 2.0 pour des paramètres supplémentaires pour chaque type de subvention.

En cas de succès le mécanisme d'authentification renvoie le code 200 et le résultat au format JSON, contenant le jeton d'accès ( access_token ), Sa validité ( expires_in ) La portée de l'accès ( scope ) Et éventuellement un remplacement de jeton ( refresh_token ).

En cas d'erreur du mécanisme d'authentification renvoie le code 400 et le résultat en format JSON, contenant le code OAuth 2.0 erreur ( error ) Et une description d'erreur plus détaillée en anglais ( error_description ).

Obtenir un jeton d'accès

Pour obtenir un jeton d'accès est tenu de soumettre une requête POST à ​​l'authentification d'URL en utilisant les types de subvention client_credentials ou password .

Par type de subvention client_credentials Vous pouvez obtenir un jeton pour accéder à la plate-forme de données publiques.

Par type de subvention password Vous pouvez obtenir un jeton pour accéder aux données publiques et plate-forme de données de l'utilisateur dont l'accès pouvoirs ont été fournies dans la demande.

En accordant password En plus du jeton d'accès, est également retourné un jeton de renouvellement ( refresh_token ) Pour être stockées par l'application et utilisé pour obtenir un nouveau jeton d'accès de sorte que le jeton d'accès en cours d'utilisation expire.

Lorsque la demande est fait la demande au nom d'un utilisateur authentifié, il doit utiliser le jeton d'accès obtenu en accordant password . Cela devrait être observé même lorsque les données accessibles peuvent être obtenus également par un jeton obtenu par le type de subvention client_credentials .

En aucun cas, l'application doit stocker les informations d'identification d'accès fournis par la persistance utilisateur. L'application doit se assurer que les informations d'identification fournies par l'utilisateur sont jetés immédiatement après l'authentification et ne sont pas inclus par erreur dans les journaux ou en vertu de fichiers de débogage.

Le type de subvention password est seulement sorti au client partenaire plateforme d'application étant donné le niveau élevé de confiance requis par les utilisateurs à fournir leurs informations d'identification d'accès.

Renouveler un jeton d'accès

Pour un jeton d'accès nouvelle, qui va remplacer un jeton périmé, vous devez soumettre une requête POST à ​​l'authentification d'URL en utilisant le type de subvention refresh_token .

Pour obtenir un nouveau jeton d'accès, l'ancien rénovation jeton sera abrogé et devrait être remplacé par nouveau jeton de rénovation émis.

Avant tout accès L'API Pousadinhas , L'application client doit d'abord vérifier la validité du jeton d'accès, renouveler si nécessaire. L'utilisation d'un jeton périmé génère une erreur dans l'appel d'API (code 401) qui devrait également être traitée, par l'obtention d'un nouveau jeton et la nouvelle tentative ultérieure.

6. Structure API

Accès L'API Pousadinhas est calculé en utilisant l'URL de base suivante:

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

La structure des URL d'accès de l'API de la base de l'URL, suit un modèle qui est divisé en quatre catégories:

  • /collection - Accès à la collection d'objets;
  • /collection/{id} - L'accès à un objet de collection par identifiant;
  • /collection/{id}/property - Accès à une propriété d'un objet de la collection par l'identifiant et le nom de la propriété;
  • /collection/name - Accès à une transaction portant sur un ou plusieurs objets de la collection;

Le L'API Pousadinhas suit les principes de repos et de modèles d'accès du protocole HTTP. L'accessibilité est organisé comme suit:

  • Des requêtes GET pour lire les objets;
  • demandes PUT pour écrire des objets;
  • Les requêtes POST pour créer des objets;
  • SUPPRIMER demandes de suppression d'objets;

Voir la liste complète des Ressources API .

7. Format de données

Le L'API Pousadinhas travailler avec le format JSON et JSONP éventuellement à GET demandes de type (retourné lorsqu'il est fait usage du paramètre callback ).

Toutes les demandes de retour, en plus du code HTTP échéant, un objet JSON avec des champs de sequintes:

  • meta - Contient le code retour HTTP ( code ) Et, en cas d'erreur, la description d'erreur en anglais ( error_detail ) Et les messages d'erreur sur l'ensemble de la langue dans la demande ( error_messages ) Indiquant le champ qui est associé à l'erreur;
  • data - Contient les données demandées;
  • caching - Contient l'objet clé d'identification ( hashkey ) Et le temps d'expiration de données ( expires_in ) Utilisé pour optimiser le trafic entre l'application client et le L'API Pousadinhas dans le GET et PUT type demandes;

POST et PUT demandes, ils soumettent le contenu des demandes au format JSON dans le corps de la demande et d'informer l'en-tête "Content-Type" et "application / json".

8. Données Caching

Le L'API Pousadinhas met en œuvre un mécanisme simple de mise en cache inspiré par le mécanisme de mise en cache natif du protocole HTTP.

Dans les requêtes GET et PUT, d'informer le paramètre hashkey (Ou tête If-None-Match ) Le service sera comparer avec le résultat clé de hachage et à les renvoyer quand il ne correspond pas; économisant ainsi les informations de trafic à l'application cliente.

Ces demandes le service renvoie le domaine caching contenant la clé objet de hachage à retourner ( hashkey ) Et des données de temps d'expiration ( expires_in ). Dans le cas où la demande a été faite en utilisant l'en-tête If-None-Matchces informations sont renvoyées par le biais de l'en-tête Etag et la politique max-age l'en-tête Cache-Control, respectivement.

Quand il ya correspondance entre la clé de hachage et en a informé la clé de hachage retourné, le service renvoie le code 304 et omet le domaine data .

L'application client ne devrait pas présenter une deuxième requête GET, à la même API URL, avec exactement les mêmes paramètres lorsque les données ne sont pas périmés il selon le domaine expires_in .

9. Pagination

Les données de radiomessagerie via l'API doivent être faites en utilisant les paramètres d'URL offset et limit . Paramètre offset définit le point de départ la page. Paramètre limit définit la taille de la page. Pour aller à la page suivante de résultats, tout simplement présenter la même demande d'application mais en augmentant la valeur du champ offset la valeur du champ limit .

Pour mettre toutes les données utilisent la taille de la page*Notant que cela doit être évitée pour les données de taille arbitraire.

10. Ordination

Les résultats de requêtes de l'API peuvent être commandés en utilisant le paramètre d'URL sortby . Ce paramètre définit les champs doivent être utilisés dans l'ordre, selon l'ordre dans lequel ils sont spécifiés. L'utilisation du suffixe "-" provoque la sorte se passe dans un ordre décroissant.

Par exemple, sortby=price-,name ordonnera une collection de données d'entrée pour le prix, plus élevé au plus bas, et si deux objets ont le même prix, le nom de l'objet.

11. Filtre champs

Via paramètre fields vous pouvez définir les champs à être retournés par l'API.

Il est possible de définir non seulement les champs pour filtrer l'objet retourné, mais aussi les objets référencés par ce dernier avec la profondeur arbitraire. Vous pouvez également définir le nombre d'objets à retourner les collections qui font l'objet. Domaine id des objets est toujours retourné et n'a pas besoin d'être spécifié.

Par exemple, fields=name,place{name,photos(10)},photos(10){id} seront les champs id , name , place.id et place.name , Et sur le terrain 10 id Photos du destin et auberge.

D'apporter tous les objets dans une utilisation de la collection*Notant que cela doit être évitée pour les collections de taille arbitraire.

12. Simulation terme

Par L'API Pousadinhas Vous pouvez simuler l'exécution (marche à vide) du POST / PUT sans modifier les demandes de données, mais il est possible de détecter les erreurs de validation. Pour cela simplement spécifier la variable d'URL dryrun=1 dans la demande.

13. Les paramètres standard

Le L'API Pousadinhas soutient certains paramètres de modèle d'URL (variables GET) qui se appliquent symétriquement aux différents services de l'API.

  • access_token - Cette variable doit contenir le jeton d'accès valide obtenu par le mécanisme d'authentification OAuth 2.0 ;
  • callback - Cette variable spécifie le nom de la fonction qui sera utilisé dans le retour au format JSONP est limitée à GET type demandes;
  • hashkey - Cette variable contient la clé de hachage attendue aux données, si la valeur correspond à la valeur à retourner, les données ne est pas envoyé au client;
  • fields - Cette variable décrit la structure de données à être retourné, indiquant hiérarchiquement les champs doivent être retournés;
  • dryrun - Cette variable stipule que la méthode POST / PUT ne doit simuler la demande sans réellement changer les données; utile pour les tests et la validation également avant la soumission de données;
  • sortby - Cette variable détermine quels champs de la collection devraient être utilisées pour trier le résultat;
  • offset - Cette variable spécifie le point de départ radiomessagerie;
  • limit - Cette variable spécifie la taille de la page;

14. Limitation des demandes de taux

Pour prévenir les abus, L'API Pousadinhas tient un registre d'accès à l'API qui doit être faite dans le pré-set quota de l'application cliente.

Le quota varie selon le type de demande et jeton d'accès, qui peut varier aussi par le service de l'API. GET type demandes a une dimension plus élevée que les demandes de type POST / PUT / DELETE. Accès par jeton obtenu en accordant client_credentials entrez l'application du quota, étant partagée par toutes les instances. Avoir accès par le jeton obtenu en accordant password entrer dans le quota de l'utilisateur, étant partagée par d'autres applications clientes qui utilisent le même.

La taille du quota et le nombre de demandes restantes sont rapportés dans le rendement de chaque demande d'API à travers les têtes X-RateLimit-Limit et X-RateLimit-Remaining Respectivement.

Pour dépasser le quota, l'API sera de retour au code de l'application client 429 et, dans la tête Retry-After Le nombre de secondes l'application attend avant de soumettre une nouvelle tentative.

L'application client doit montrer à l'utilisateur une minuterie lorsque vous êtes en attente en raison de l'éclatement de la quote-part, permettant l'annulation de l'opération. Il est également recommandé que l'application cliente suggère à l'utilisateur de se connecter à remédier à la restriction temporaire de quota, si elle n'a pas trouver authentifié.

Les limites à l'application des demandes de taux peuvent être examinées au cas par demande à notre équipe.

15. Emplacement

L'emplacement, en termes de langue, de monnaie et de fuseau horaire, les appels deL'API Pousadinhasdoit se faire via les paramètres d'URL suivants (GET variables) :

  • language-Cette variable indique la langue qui sera utilisée dans les messages renvoyés par l'API ;
  • currency-Cette variable indique la monnaie qui sera utilisée dans le prix retourné par l'API ;
  • timezone-Cette variable indique le fuseau horaire qui sera utilisé dans les codages de date et d'heure retournées par l'API ;

LeL'API Pousadinhasretourne toujours les données en fonction de ces paramètres, indépendamment du paramétrage du compte d'utilisateur associé au jeton d'accès utilisé dans la requête.

16. Codes de retour

Voici une liste des codes de retour de réussite ou d'erreur renvoyé par l'API et les situations dans lesquelles ils se produisent:

  • 200 - Le succès dans la mise en œuvre de l'opération;
  • 201 - Réussir à créer un nouvel objet;
  • 304 - Le succès dans la mise en œuvre de l'opération, mais le hachage de l'objet éclairé clé coïncidé et les données ont été omis;
  • 400 - Accès HTTP pas en sécurité; Paramètres ou variables obligatoires ne sont pas signalés; Paramètres ou variables supplémentaires non reconnues; Paramètres ou variables invalides; Aucun objet ou invalide JSON; mise à niveau de champ qui permet en lecture seule; Marche à sec pas pris en charge;
  • 401 - Manque de jeton d'accès; L'accès Token non valide, expiré ou révoqué; Accès refusé la demande;
  • 403 - Autorisations insuffisantes pour faire la demande;
  • 404 - Des ressources (collecte, objet, etc.) il;
  • 405 - Type de Réquisition pas pris en charge;
  • 409 - Impossible de créer / mise à jour / suppression d'un objet;
  • 429 - Dépassé accès aux contingents;

17. Accès à la console

Pour se familiariser avec le L'API Pousadinhas , Visite Console API alimenté par Apigee.

Les essais d'environnement POUSADINHAS.COM.BR environnement fictif est complètement autonome et identique dans la fonctionnalité de l'environnement de production. Grâce à elle, vous pouvez tester toutes les fonctionnalités de notre plateforme dans un environnement totalement isolé de la réalité et sans compromettre sa fonctionnalité.

Si vous êtes intéressé à accéder à notre environnement de test, s'il vous plaît envoyez un courriel à recursos@pousadinhas.com.br identifier et décrire les raisons de votre demande.