Ressourcen für Entwickler

Fügen Sie ein Such-Widget auf Ihrer Website oder Blog, um Ihre Besucher direkt an unser Buchungssystem.

Das Such-Widget wurde entwickelt, um einen Blick neutral und standardisiert haben, vorsichtiges Mischen auf Ihre Seite und die Erleichterung der Anerkennung von Ihren Besuchern.

Für die besten Ergebnisse zu erzielen, die Such-Widget auf dem oberen Rand der Seite, in einer Seitenleiste.

Wenn Ihre Website ist auf der Basis der Plattform WordPress.org Wir haben ein Plugin für die einfache Einbindung Search Widget.

Um es zu installieren, laden Sie es von Plugin Seite auf WordPress.org ; oder - über die Verwaltungsschnittstelle - klicken Sie auf die "Plugins" / "Add New"-Menü und suchen Sie nach "pousadinhas". Achten Sie darauf, wählen Sie das Plugin " Pousadinhas Search Widget "!

Wenn Ihre Website ist auf der Basis der Plattform Joomla! Wir haben ein Plugin für die einfache Einbindung Search Widget.

Um es zu installieren, Download hier und - durch die Verwaltungsoberfläche - klicken Sie auf den "Extensions"-Menü / "Installieren / Deinstallieren" mit der Installation fortfahren. Für weitere Informationen, besuchen Sie Plugin Seite im Erweiterungsverzeichnis Joomla.org .

Wenn Sie beabsichtigen, es "in situ" zu verwenden - also ohne Kopplung an den Rand des Fensters - fügen Sie den folgenden {pousadinhas} der gewünschte Inhalt.


a) Configuration

Unten verwenden Sie das Formular auf der linken Seite, um das Widget Suchen und Vorschau das Ergebnis im rechten Fensterbereich gesetzt.

Optionen WidgetVorschau
Die Verarbeitung ...
Wählen Sie das Ziel für die Suche erfolgt über das Widget.?
Deaktivieren Sie diese Option, um die Datumsfelder haben, werden nicht mit Standardwerten initialisiert.?
Wählen Sie die Sprache Ihrer Seite.?
Wählen Sie die Ecke des Bildschirms, wo Sie wollen, um das Widget andocken.?
Aktivieren Sie diese Option, wenn es Platzproblem in das Layout Ihrer Seite.?
Wenn Ihre Seite sicher ist (https-Protokoll), sollten Sie diese Option auswählen.?

b) Umsetzung

Schritt 1. Der folgende Code sollte in die Seite eingefügt werden, direkt über dem tag </HEAD> Schließen Header.

Schritt 2. Der folgende Code sollte in die Seite eingefügt werden, wo genau Sie das Widget auf Suche erscheinen soll.

1. Anwendungsregistrierung

Um das zu verwenden Die Pousadinhas API es ist notwendig, dass die Client-Anwendung auf der Plattform registriert. Bitte kontaktieren Sie uns per E-Mail recursos@pousadinhas.com.br und geben Sie den Namen und eine detaillierte Beschreibung der Anwendung oder Integration, entwickeln wollen, was auf die Funktionen, die Sie verwenden.

2. Entwicklung und Zulassung

Mit der Annahme der Anwendung Registrierungsanfrage, werden wir für Sie ein Konto in unserer Testumgebung zu erstellen und expediremos zugreifen Anmeldeinformationen für den Einsatz in der Entwicklung.

Abschluss der Entwicklung, ist es notwendig, uns erneut zu kontaktieren, die Anweisungen für den Zugriff auf die Anwendung, so kann unser Team Tests durchzuführen. Erst nach der Genehmigung des Antrags, zugreifen expediremos Anmeldeinformationen in der Produktionsumgebung.

3. Anmeldeinformationen:

Die Zugangsdaten von Client-Anwendungen in unserer Plattform werden von beiden Informationen zusammen:

  • client_id - Client-Anwendungs-ID, öffentliche;
  • client_secret - Geheimhaltung der Client-Anwendung, privat;

Anmeldedaten nicht für den direkten Zugriff verwendet werden Die Pousadinhas API . Aber sie sind notwendig, um ein Zugriffstoken zu erhalten ( access_token ) Mit der API-Authentifizierungsmechanismus; dann dieses Token wird verwendet, um die API zugreifen kann.

Die Client-Anwendung muss halten client_secret in absoluter Geheimhaltung und steht der Rückführung derselben zu verlangen, wenn sich die mutmaßlichen Kompromittierung.

Bei Anwendungen, die auf vertrauenswürdigen Geräten bereitgestellt werden (zB mobile Anwendungen) und die client_secret Muss gespeichert überschattet werden. Darüber hinaus sollten die Client-Anwendung den Benutzer, um das Update zu tun auffordern wird angewandt, wenn es ein Hinweis auf die Fehleraustausch client_secret .

4. Datenverschlüsselung

Alle Anfragen und Antworten gesendet und in beiden Authentifizierungsmechanismus und API erhalten, UTF-8-Codierung.

5. Authentifizierungsmechanismus

Der Authentifizierungsmechanismus Die Pousadinhas API wird an den Standard OAuth 2.0 . Jeder Zugriff auf die API muss über ein Zugriffstoken (gemacht werden access_token ) Vorher durch diesen Mechanismus erzielt.

Die Routinen der Erlangung und Aufrechterhaltung Zugriffstoken werden über Typ POST-Anfragen an den folgenden URL durchgeführt:

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

Die Bewerbungsunter sollte dieser Anforderungen durch Standardauthentifizierung URL oder durch die POST-Variablen informiert werden client_id und client_secret .

Die Arten von Zuschüssen ( grant_type ) Unterstützt durch den Authentifizierungsmechanismus OAuth 2.0 implementiert sind: client_credentials . password und refresh_token . Bitte die Hinweise OAuth 2.0 für zusätzliche Parameter für jede Art von Zuschuss.

Bei Erfolg wird der Authentifizierungsmechanismus gibt den Code 200 und das Ergebnis im JSON-Format, mit dem Zugriffstoken ( access_token ) Seine Gültigkeit ( expires_in ) Der Zugriffsbereich ( scope ) Und gegebenenfalls eine Tokenersetzung ( refresh_token ).

Im Fehlerfall wird der Authentifizierungsmechanismus gibt die 400-Code und das Ergebnis im JSON-Format, mit dem Code OAuth 2.0 Fehler ( error ) Und eine detailliertere Fehlerbeschreibung in Englisch ( error_description ).

Erste ein Zugriffstoken

Um ein Zugriffstoken zu erhalten, ist erforderlich, um eine POST-Anforderung an die URL-Authentifizierung über die Art der Finanzhilfe einreichen client_credentials oder password .

Nach Art der Finanzhilfe client_credentials Sie können einen Token zu bekommen, um die Plattform der öffentlichen Daten zugreifen.

Nach Art der Finanzhilfe password Sie können ein Zeichen bekommen, um öffentliche Daten und Benutzerdaten-Plattform, deren Anmeldedaten wurden in dem Antrag zugreifen.

Bei der Gewährung von password Neben dem Zugriffstoken wird auch zurückgegeben ein Token Erneuerung ( refresh_token ) Um die von der Anwendung gespeichert und verwendet, um eine neue Zugriffstoken zu erhalten, so dass die Zugriffstoken im Einsatz abläuft.

Wird der Antrag, der die Anfrage im Namen von einem authentifizierten Benutzer sollte die Zugriffstoken durch die Vergabe erhalten verwenden password . Dies sollte auch beachtet werden, wenn Zugriff auf Daten können auch durch ein Token durch die Art der Zuteilung erhalten erhalten client_credentials .

Auf keinen Fall sollte der Antrag die Zugangsdaten durch anhaltend Benutzer zur Verfügung gestellt zu speichern. Die Anwendung muss sicherstellen, dass die vom Benutzer angegebenen Anmeldeinformationen werden sofort nach der Authentifizierung verworfen und nicht versehentlich in Protokollen oder nach Debug-Dateien enthalten.

Die Art der Finanzhilfe password nur zur Partneranwendung Plattform Client angesichts der hohen Maß an Vertrauen von Benutzern erforderlich sind, um ihnen den Zugang Anmeldeinformationen veröffentlicht.

Erneuerung ein Zugriffstoken

Für eine neue Access-Token, die ein abgelaufenes Token ersetzen wird, müssen Sie eine POST-Anforderung an die URL-Authentifizierung über die Art der Finanzhilfe einreichen refresh_token .

Um eine neue Zugriffstoken zu erhalten, wird der Token alte Sanierung aufgehoben und durch neue Renovierung Token ausgegeben ersetzt werden.

Vor jedem Zugriff Die Pousadinhas API Muss der Client-Anwendung zuerst die Gültigkeit der Zugriffstoken, erneuern Sie diese gegebenenfalls. Die Verwendung einer abgelaufenen Token erzeugt einen Fehler in der API-Aufruf (Code 401), die ebenfalls behandelt werden soll, durch den Erwerb einer neuen Token und der anschließenden erneuten.

6. API-Struktur

Zugriff Die Pousadinhas API wird unter Verwendung der folgenden Basis-URL:

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

Die Struktur der API-Zugriffs-URLs aus dem URL-Basis, folgt einem Muster, das in 4 Klassen unterteilt:

  • /collection - Zugang zur Sammlung von Objekten;
  • /collection/{id} - Zugang zu einer Sammlung Objekt Kennung;
  • /collection/{id}/property - Der Zugriff auf eine Eigenschaft eines Objekts in der Sammlung durch die Kennung und den Namen der Eigenschaft;
  • /collection/name - Zugang zu einer Transaktion in Bezug auf ein oder mehrere Objekte in der Sammlung;

Die Die Pousadinhas API folgt den REST-Prinzipien und HTTP-Protokoll Zugriffsmuster. Die Zugänglichkeit ist wie folgt aufgebaut:

  • GET-Anfragen, um Objekte zu lesen;
  • PUT-Anfragen für das Schreiben von Objekten;
  • POST-Anfragen, um Objekte zu erstellen;
  • DELETE-Anforderungen für das Entfernen von Objekten;

Die vollständige Liste der API Ressourcen .

7. Datenformat

Die Die Pousadinhas API Arbeit mit JSON-Format und optional JSONP Typ Anfragen GET (zurück bei der Verwendung des Parameters gemacht callback ).

Alle Anträge zurück, die neben entsprechenden HTTP-Code, ein JSON-Objekt mit sequintes Felder:

  • meta - Enthält die HTTP-Return-Code ( code ), Und im Falle eines Fehlers die Fehlerbeschreibung in Englisch ( error_detail ) Und Fehlermeldungen auf der eingestellten Sprache in der Anfrage ( error_messages ), Die das Feld, das von dem Fehler betroffen ist;
  • data - Enthält die angeforderten Daten;
  • caching - Enthält die Identifizierung von Schlüsselobjekt ( hashkey ) Und den Daten-Ablaufzeit ( expires_in ) Verwendet, um den Datenverkehr zwischen dem Client-Anwendung und der Optimierung Die Pousadinhas API in der GET und PUT-Anfragen Typ;

POST und PUT-Anfragen, nehmen sie in den Antrag Inhalt im JSON-Format in den Körper der Antrag stellen und informieren den Header "Content-Type" und "application / json".

8. Daten Caching

Die Die Pousadinhas API implementiert einen einfachen Caching-Mechanismus, inspiriert von der Mutter Caching-Mechanismus des HTTP-Protokolls.

In der GET und PUT-Anfragen, um den Parameter zu informieren hashkey (Oder Kopf If-None-Match ) Der Dienst wird mit dem Ergebnis, Raute-Taste vergleichen und senden Sie es nur, wenn es nicht übereinstimmt; Das spart die Verkehrsinformationen an die Clientanwendung.

Diese Anforderungen der Service liefert den Feld caching mit dem Ziel Raute-Taste, um zurückzugeben ( hashkey ) Und Ablaufzeit-Daten ( expires_in ). Wenn der Antrag unter Verwendung des Kopf gemacht If-None-Match Diese Information wird über den Header zurückgegeben Etag und die Politik max-age Kopfzeile Cache-Control Jeweils.

Wenn es Übereinstimmung zwischen der Raute-Taste und informierte die Raute-Taste wieder, kehrt der Dienst die 304-Code und lässt die Feld data .

Die Client-Anwendung sollte keine zweite GET-Anforderung stellen, der die gleiche URL API, mit genau denselben Parametern, wenn Daten dort entsprechend dem Feld nicht abgelaufen expires_in .

9. Pagination

Die Paging-Daten über die API sollte mit den URL-Parameter vorgenommen werden offset und limit . Parameter offset setzt die Seitenausgangspunkt. Parameter limit setzt die Seitengröße. Um auf die nächste Seite mit Ergebnissen zu gehen, wählen Sie einfach die gleiche Anwendungsanforderung, sondern die Erhöhung der Wert des Feldes offset der Feldwert limit .

Bringen alle Daten verwenden, die Seitengröße * , Feststellend, dass dies für beliebig lange Daten vermieden werden.

10. Ordination

Die Ergebnisse der API-Anfragen können mit dem URL-Parameter zu bestellen sortby . Dieser Parameter legt fest, welche Felder in der Reihenfolge verwendet werden, in der Reihenfolge, in der sie angegeben sind. Die Verwendung des Suffixes "-" wird die Sortierung erfolgt in einer abnehmenden Reihenfolge.

Zum Beispiel, sortby=price-,name eine Sammlung von Eingabedaten für den Preis, höchsten zum niedrigsten bestellen, und wenn zwei Objekte den gleichen Preis, den Namen des Objekts haben.

11. Felder Filter

Über den Parameter fields können Sie festlegen, welche Felder von der API zurückgegeben werden.

Es ist möglich, nicht nur die Bereiche definieren, um die zurückgegebene Objekt, sondern auch die Objekte, die von der letzteren mit beliebiger Tiefe referenziert filtern. Sie können auch die Anzahl der Objekte gesetzt, die Sammlungen, die das Objekt zu machen zurückzukehren. Bereich id von Objekten immer zurückgegeben und müssen nicht angegeben werden.

Zum Beispiel, fields=name,place{name,photos(10)},photos(10){id} werden die Felder id . name . place.id und place.name , Und Feld 10 id Fotos des Schicksals und Gasthaus.

Um alle Objekte in einer Sammlung Einsatz bringen * , Feststellend, dass dies auf eine beliebige Größe Sammlungen vermieden werden.

12. Simulationslauf

Durch Die Pousadinhas API Sie können die Ausführung (Trockenlauf) von POST / PUT ohne tatsächlich Änderung der Datenanforderungen zu simulieren, aber es ist möglich, Validierungsfehler zu erkennen. Dazu einfach die URL Variable dryrun=1 in der Anforderung.

13. Standardparameter

Die Die Pousadinhas API unterstützt einige URL-Muster-Parameter (GET-Variablen), die symmetrisch zu den verschiedenen API-Dienstleistungen.

  • access_token - Diese Variable muss die gültige Zugriffstoken durch den Authentifizierungsmechanismus erhalten werden, enthalten OAuth 2.0 ;
  • callback - Diese Variable gibt den Namen der Funktion, die im Gegenzug in JSONP Format verwendet werden begrenzt auf Anfragen Typ GET werden;
  • hashkey - Diese Variable enthält den erwarteten Hash-Schlüssel an den Daten, wenn der Wert des zurückzugebenden Wert übereinstimmt, werden die Daten nicht an den Client gesendet wird;
  • fields - Diese Variable beschreibt die Struktur von Daten, die zurückgegeben werden, hierarchisch anzeigt, die Felder, die zurückgeführt werden;
  • dryrun - Diese Variable legt fest, dass die POST / PUT-Methode sollte nur die Anforderung zu simulieren, ohne tatsächlich die Änderung der Daten; für Testzwecke verwendet und auch die Datenüberprüfung vor der Vorlage;
  • sortby - Diese Variable legt fest, welche Felder der Sammlung zu verwenden, um das Ergebnis zu sortieren;
  • offset - Diese Variable gibt die Auslagerungsausgangspunkt;
  • limit - Diese Variable gibt die Größe der Seite;

14. Beschränkung der Ratenanfragen

Um Missbrauch vorzubeugen, Die Pousadinhas API hält eine Aufzeichnung der Zugriff auf die API, die innerhalb der vorgegebenen Quote von der Client-Anwendung vorzunehmen sind.

Die Quote hängt von der Art der Anfrage und Zugriffstoken, die auch von der API-Service variieren kann. GET-Anfragen Typ hat eine höhere Dimension, Typ POST / PUT / DELETE anfordert. Anfahrt mit dem Token durch die Vergabe erhalten client_credentials geben Sie die Anwendung des Kontingents, die von allen Instanzen gemeinsam genutzt. Haben Zugriff durch Token durch die Vergabe erhalten password Geben Quote des Benutzers, die von anderen Client-Anwendungen, die die gleiche verwenden geteilt.

Die Größe des Kontingents und die Anzahl der verbleibenden Anfragen werden in der Rückkehr von jedem API-Anforderung durch die Überschriften berichtet X-RateLimit-Limit und X-RateLimit-Remaining Jeweils.

Um das Kontingent übersteigen, wird der API an den Client-Anwendungscode 429 zurück, und in der Kopfzeile Retry-After Die Anzahl der Sekunden die Anwendung wartet, bevor sie einen neuen Versuch.

Die Client-Anwendung muss der Benutzer einen Timer an, wenn Sie durch die darauf warten, das Platzen der Quote und ermöglicht den Rücktritt der Operation. Es wird auch empfohlen, dass die Client-Anwendung schlägt dem Benutzer, melden Sie sich an, um die temporären Quotenbeschränkung zu beseitigen, wenn sie nicht authentifiziert finden.

Die Grenzen für die Anwendung von Ratenanfragen können von Fall zu Anfrage an unser Team überprüft werden.

15. Lage

Die Lage, in Bezug auf Sprache, Währung und Zeitzone, die Anrufe vonDie Pousadinhas APIerfolgt über die folgende URL-Parameter (GET-Variablen):

  • language-Diese Variable gibt die Sprache, die in den Nachrichten, die von der API zurückgegebene verwendet werden;
  • currency-Diese Variable gibt die Währung, die im Preis von der API zurückgegebene verwendet werden;
  • timezone-Diese Variable gibt die Zeitzone, die in den von der API zurückgegebene Datum/Uhrzeit-Codierungen verwendet wird;

DieDie Pousadinhas APIgibt immer die Daten entsprechend dieser Parameter, unabhängig von der Einstellung des Benutzerkontos in der Anforderung verwendete Zugriffstoken zugeordnet.

16. Rückgabecodes

Hier ist eine Liste von Rückgabecodes für Erfolg oder Fehler von der API zurückgegeben und die Situationen, in denen sie vorkommen:

  • 200 - Erfolg der Durchführung der Operation;
  • 201 - Erfolg bei der Schaffung eines neuen Objekts;
  • 304 - Der Erfolg bei der Umsetzung der Operation, aber der informierte Objekt Raute-Taste zusammenfiel und die Daten wurden weggelassen;
  • 400 - Nicht sichere HTTP-Zugriff; Obligatorische Parameter oder Variablen nicht berichtet; Zusätzliche Parameter oder Variablen nicht erkannt; Ungültige Parameter oder Variablen; Kein solches Objekt oder ungültig JSON; Feld-Upgrade, das ermöglicht schreibgeschützt; Trockenlauf nicht unterstützt;
  • 401 - Fehlender Zugang Token; Token Unzulässiger Zugriff, abgelaufen oder widerrufen; Zugriff verweigert die Anwendung;
  • 403 - Unzureichende Berechtigungen, um den Antrag zu stellen;
  • 404 - Ressource (Sammlung, Objekt, etc.) gibt;
  • 405 - Anforderungstyp nicht unterstützt;
  • 409 - Fehlgeschlagen / update / Entfernung eines Objekts zu erzeugen;
  • 429 - Überschritten Quote Zugang;

17. Konsolenzugriff

Um mit dem vertraut machen Die Pousadinhas API , Besuch API Console angetrieben durch Apigee.

Die Environment Tests POUSADINHAS.COM.BR fiktiven Umwelt ist ein vollständig in sich geschlossenes und dieselbe Funktion wie die Produktionsumgebung. Durch sie können Sie alle Funktionen unserer Plattform in einer völlig von der Realität isoliert und ohne Beeinträchtigung seiner Funktionsweise zu testen.

Wenn Sie Interesse an dem Zugriff auf unsere Testumgebung sind, senden Sie bitte eine E-Mail an recursos@pousadinhas.com.br Identifizierung und Beschreibung der Gründe für Ihre Anfrage.