Risorse per gli sviluppatori

Aggiungere un widget di ricerca sul tuo sito web o blog per inviare i visitatori direttamente al nostro sistema di prenotazione.

Il widget di ricerca è stato sviluppato per avere uno sguardo neutrale e standardizzato, mescolando delicatamente per la tua pagina e facilitando il riconoscimento dai visitatori.

Per ottenere i migliori risultati, applicare il widget di ricerca nella parte superiore della pagina, in una barra laterale.

Se il vostro sito si basa sulla piattaforma WordPress.org Abbiamo creato un plugin per un facile inserimento widget di ricerca.

Per installarlo, scaricalo da pagina dei plugin su WordPress.org ; o - tramite l'interfaccia di amministrazione - clicca su "Plugins" / "Aggiungi nuovo" menu e cercare "pousadinhas". Assicurarsi di selezionare il plugin " Pousadinhas Search Widget "!

Se il vostro sito si basa sulla piattaforma Joomla! Abbiamo creato un plugin per un facile inserimento widget di ricerca.

Per installarlo, scaricalo qui e - attraverso l'interfaccia amministrativa - clicca su "Estensioni" Menu / "Installa / Disinstalla" proseguire con l'installazione. Per ulteriori informazioni, visitare il sito pagina dei plugin nella directory delle estensioni Joomla.org .

Se avete intenzione di usarlo "in situ" - cioè senza aggancio al bordo della finestra - aggiungere il seguente {pousadinhas} il contenuto desiderato.


a) Configurazione

Qui di seguito, usa il modulo a sinistra per impostare il widget di ricerca e visualizzare in anteprima il risultato nel riquadro di destra.

Opzioni WidgetAnteprima
Elaborazione in corso ...
Selezionare la destinazione per le ricerche effettuate utilizzando il widget.?
Deselezionare questa opzione per i campi data non vengono inizializzati con i valori predefiniti.?
Selezionare la lingua della tua pagina.?
Selezionare l'angolo dello schermo in cui si desidera ancorare il widget.?
Selezionare questa opzione se non vi è vincolo di spazio nel layout della pagina.?
Se la pagina è sicura (protocollo https) è necessario selezionare questa opzione.?

b) Attuazione

Passo 1. Il seguente codice deve essere inserito nella pagina, appena sopra il tag </HEAD> chiusura intestazione.

Passo 2. Il seguente codice deve essere inserito nella pagina, esattamente dove si desidera far apparire il widget di ricerca.

1. Registrazione applicazione

Per utilizzare il Il Pousadinhas API è necessario che l'applicazione client è registrato sulla nostra piattaforma. Vi preghiamo di contattarci via e-mail recursos@pousadinhas.com.br e fornire il nome e una descrizione dettagliata della domanda o integrazione che vogliono sviluppare, indicando le caratteristiche che si intende utilizzare.

2. Sviluppo e approvazione

Approvando la tua richiesta di registrazione applicazione, creeremo un account per voi nel nostro ambiente di test e expediremos accedere alle credenziali per l'utilizzo in fase di sviluppo.

Completato lo sviluppo, è necessario contattarci di nuovo, con le istruzioni per l'accesso all'applicazione, quindi il nostro team può condurre test. Solo dopo l'approvazione della domanda, expediremos accesso credenziali per l'ambiente di produzione.

3. Credenziali di accesso

Le credenziali di accesso di applicazioni client nella nostra piattaforma sono composti da due pezzi di informazione:

  • client_id - Identificatore dell'applicazione client, pubblico;
  • client_secret - Segretezza dell'applicazione client, privato;

Le credenziali di accesso non possono essere utilizzati per l'accesso diretto Il Pousadinhas API . Ma sono necessarie per ottenere un token di accesso ( access_token ), Con il meccanismo di autenticazione API; allora questo token verrà utilizzato per accedere all'API.

L'applicazione client deve mantenere client_secret in assoluta segretezza e chiede la restituzione dello stesso ogni volta che si sospetta compromesso.

In caso di applicazioni che saranno distribuite su dispositivi non attendibili (ad esempio applicazioni mobili), il client_secret deve essere conservato in ombra. Inoltre, l'applicazione client dovrebbe chiedere all'utente di fare l'aggiornamento viene applicata ogni volta che vi sia un'indicazione dello scambio errore client_secret .

4. La crittografia dei dati

Tutte le richieste e le risposte inviate e ricevute in entrambi meccanismo di autenticazione e API, utilizzano codifica UTF-8.

5. Meccanismo di autenticazione

Il meccanismo di autenticazione Il Pousadinhas API è basato sullo standard OAuth 2.0 . Tutti gli accessi alle API deve essere realizzato con un token di accesso ( access_token ) Precedentemente ottenuti attraverso questo meccanismo.

Le routine di ottenere e rinnovare i token di accesso vengono effettuate tramite POST tipo richieste al seguente URL:

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

Le credenziali di applicazioni dovrebbero essere informati di queste richieste attraverso URL autenticazione di base, o attraverso le variabili POST client_id e client_secret .

I tipi di sovvenzioni ( grant_type ) Supportato dal meccanismo di autenticazione OAuth 2.0 implementate sono: client_credentials , password e refresh_token . Si prega di fare riferimento alle istruzioni OAuth 2.0 per parametri aggiuntivi per ogni tipo di sovvenzione.

In caso di successo il meccanismo di autenticazione restituisce il codice 200 e il risultato in formato JSON, contenente il token di accesso ( access_token ), La sua validità ( expires_in ) Il campo di applicazione di accesso ( scope ) Ed eventualmente la sostituzione del token ( refresh_token ).

In caso di errore del meccanismo di autenticazione restituisce il codice 400 e il risultato in formato JSON, contenente il codice OAuth 2.0 errore ( error ) E una descrizione errore più dettagliato in lingua inglese ( error_description ).

Ottenere un token di accesso

Per ottenere un token di accesso è necessario per presentare una richiesta POST per l'autenticazione URL utilizzando i tipi di concessione client_credentials o password .

Per tipo di sovvenzione client_credentials È possibile ottenere un token per accedere alla piattaforma di dati pubblici.

Per tipo di sovvenzione password È possibile ottenere un token di accesso ai dati pubblici e la piattaforma di dati utente il cui accesso credenziali sono state fornite nella domanda.

Nel concedere password Oltre al token di accesso, viene anche restituito un rinnovamento gettone ( refresh_token ) Per essere memorizzati dall'applicazione e utilizzato per ottenere un nuovo token di accesso in modo che il token di accesso in uso scade.

Se la domanda sta facendo la richiesta da parte di un utente autenticato, si dovrebbe utilizzare il token di accesso ottenuta concedendo password . Questo dovrebbe essere osservato anche quando i dati accessibili possono essere ottenuti anche mediante un token ottenuto attraverso il tipo di borsa client_credentials .

In nessun caso l'applicazione deve memorizzare le credenziali di accesso fornite da persistentemente dall'utente. L'applicazione deve garantire che le credenziali fornite dall'utente vengono scartate immediatamente dopo l'autenticazione e non sono inclusi per errore nei registri o in virtù di file di debug.

Il tipo di sovvenzione password viene rilasciato solo per il client piattaforma applicativa socio dato l'alto livello di fiducia richiesto da utenti di fornire le proprie credenziali di accesso.

Rinnovare un token di accesso

Per un token di nuovo accesso, che andrà a sostituire un token scaduto, è necessario inviare una richiesta POST per l'autenticazione URL utilizzando il tipo di concessione refresh_token .

Per ottenere un nuovo token di accesso, il token vecchio rinnovamento sarà abrogata e deve essere sostituito da nuovo token aggiornamento rilasciato.

Prima di qualsiasi accesso Il Pousadinhas API , L'applicazione client deve prima verificare la validità del token di accesso, rinnovando se necessario. L'uso di un token scaduto genera un errore nella chiamata API (codice 401) che dovrebbero essere trattati, ottenendo un nuovo token e il successivo tentativo.

6. Struttura API

Accesso Il Pousadinhas API è calcolato utilizzando il seguente URL di base:

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

La struttura degli URL di accesso API dalla base URL, segue un modello che si divide in 4 gradi:

  • /collection - L'accesso alla collezione di oggetti;
  • /collection/{id} - L'accesso a un oggetto da collezione di identificazione;
  • /collection/{id}/property - L'accesso a una proprietà di un oggetto della collezione per l'identificatore e il nome della proprietà;
  • /collection/name - L'accesso a un'operazione relativa a uno o più oggetti della collezione;

Il Il Pousadinhas API segue i principi REST e modelli di accesso di protocollo HTTP. L'accessibilità è organizzato come segue:

  • GET richieste per leggere gli oggetti;
  • Richieste PUT per la scrittura di oggetti;
  • Richieste POST per creare oggetti;
  • DELETE richieste di rimozione di oggetti;

Vedere l'elenco completo dei Risorse API .

7. Formato dati

Il Il Pousadinhas API lavorare con il formato JSON e JSONP opzionalmente a richieste GET tipo (restituito quando si fa uso del parametro callback ).

Tutte le richieste di ritorno, oltre al codice appropriato HTTP, un oggetto JSON con campi sequintes:

  • meta - Contiene il codice di ritorno HTTP ( code ) E, in caso di errore, la descrizione di errore in inglese ( error_detail ) E messaggi di errore sul set della lingua nella richiesta ( error_messages ) Indicando il campo che è associato con l'errore;
  • data - Contiene i dati richiesti;
  • caching - Contiene l'oggetto chiave di identificazione ( hashkey ) E il tempo di scadenza dei dati ( expires_in ) Permette di ottimizzare il traffico tra l'applicazione client e il Il Pousadinhas API nella GET e PUT tipo richieste;

POST e PUT richieste, essi presentano il contenuto richiesta in formato JSON nel corpo della richiesta e informa l'intestazione "Content-Type" e "application / json".

8. Dati Caching

Il Il Pousadinhas API implementa un semplice meccanismo di caching ispirata al meccanismo di caching nativo del protocollo HTTP.

Nelle richieste GET e PUT, di informare il parametro hashkey (O intestazione If-None-Match ) Il servizio metterà a confronto con il tasto cancelletto risultato e tornare solo quando non corrisponde; salvando così le informazioni sul traffico per l'applicazione client.

Queste richieste servizio restituisce il campo caching contenente la chiave oggetto hash da restituire ( hashkey ) E i dati temporali di scadenza ( expires_in ). Se la richiesta è stata fatta utilizzando l'intestazione If-None-Match , Queste informazioni vengono restituite attraverso il collettore Etag e la politica max-age intestazione Cache-Control Rispettivamente.

Quando c'è corrispondenza tra la chiave hash e ha informato il tasto cancelletto restituito, il servizio restituisce il codice 304 e omette il campo data .

L'applicazione client non dovrebbe presentare una seconda richiesta GET, per la stessa API URL, con esattamente gli stessi parametri quando i dati non ci sono scaduti in base al campo expires_in .

9. Paginatura

I dati paging tramite l'API devono essere effettuate utilizzando i parametri URL offset e limit . Parametro offset imposta il punto di pagina iniziale. Parametro limit imposta le dimensioni della pagina. Per passare alla pagina successiva dei risultati, invia la stessa richiesta applicazione, ma aumentando il valore del campo offset il valore del campo limit .

Per portare tutti i dati utilizzano il formato della pagina * , Rilevando che questo dovrebbe essere evitato per i dati di lunghezza arbitraria.

10. Ordinazione

I risultati delle richieste API possono essere ordinati tramite il parametro URL sortby . Questo parametro definisce quali campi dovrebbe essere utilizzato al fine, secondo la sequenza in cui sono specificate. L'uso del suffisso "-" provoca l'ordinamento avviene in ordine decrescente.

Per esempio, sortby=price-,name ordinerà una raccolta di dati di input per il prezzo, più alto al più basso, e se due oggetti hanno lo stesso prezzo, il nome dell'oggetto.

11. Filtro Campi

Via parametro fields è possibile definire i campi da restituire dall'API.

È possibile definire non solo i campi per filtrare l'oggetto restituito, ma anche gli oggetti di riferimento da quest'ultimo con profondità arbitraria. È anche possibile impostare il numero di oggetti di restituire le collezioni che compongono l'oggetto. Campo id di oggetti è sempre tornato e non deve essere specificata.

Per esempio, fields=name,place{name,photos(10)},photos(10){id} Will i campi id , name , place.id e place.name E campo 10 id foto di destino e inn.

Per portare tutti gli oggetti in un uso collezione * , Rilevando che questo dovrebbe essere evitato a raccolte di dimensioni arbitrarie.

12. Run di simulazione

Attraverso Il Pousadinhas API È possibile simulare l'esecuzione (funzionamento a secco) di POST / PUT senza effettivamente modificare le richieste di dati, ma è possibile rilevare errori di convalida. Per questo è sufficiente specificare la variabile URL dryrun=1 nella richiesta.

13. Parametri standard

Il Il Pousadinhas API supporta alcuni parametri del modello URL (GET variabili) che si applicano simmetricamente ai vari servizi API.

  • access_token - Questa variabile deve contenere il token di accesso valido ottenuto attraverso il meccanismo di autenticazione OAuth 2.0 ;
  • callback - Questa variabile specifica il nome della funzione che verrà utilizzato nel ritorno in formato JSONP è limitato a GET tipo richieste;
  • hashkey - Questa variabile contiene la chiave hash attesa per i dati, se il valore corrisponde al valore da restituire, i dati non viene inviato al cliente;
  • fields - Questa variabile descrive la struttura dei dati da restituire, gerarchicamente indicando i campi da restituire;
  • dryrun - Questa variabile stabilisce che il metodo POST / PUT deve solo simulare la richiesta senza modificare i dati; utile per test e anche la convalida dei dati prima della presentazione;
  • sortby - Questa variabile indica quali campi della collezione dovrebbero essere utilizzati per ordinare il risultato;
  • offset - Questa variabile specifica il punto di partenza di paging;
  • limit - Questa variabile specifica la dimensione della pagina;

14. Limitazione delle richieste di tasso

Per prevenire gli abusi, Il Pousadinhas API mantiene un record di accesso alle API che deve essere effettuato entro la quota pre-set dell'applicazione client.

La quota varia dal tipo di richiesta e token di accesso, che può variare anche dal servizio API. GET tipo richieste ha una dimensione superiore che richiede tipo POST / PUT / DELETE. Accesso con gettone ottenuto concedendo client_credentials inserire l'applicazione del contingente, condivisa da tutte le istanze. Hanno accesso con gettone ottenuto concedendo password immettere quota dell'utente, condiviso da altre applicazioni client che utilizzano lo stesso.

La dimensione della quota e il numero di richieste rimanenti sono riportati nella ritorno di ciascuna richiesta API attraverso le intestazioni X-RateLimit-Limit e X-RateLimit-Remaining Rispettivamente.

Per superare la quota, l'API tornerà al codice dell'applicazione client 429 e, nell'intestazione Retry-After Il numero di secondi che l'applicazione attende prima di presentare un nuovo tentativo.

L'applicazione client deve mostrare all'utente un timer quando si è in attesa a causa della rottura della quota, che consente la cancellazione dell'operazione. Si raccomanda inoltre che l'applicazione client suggerisce all'utente di accedere a porre rimedio alla limitazione quota temporanea, se non trovare autenticato.

I limiti all'applicazione delle richieste dei tassi possono essere rivisti su un caso su richiesta al nostro team.

15. Posizione

La posizione, in termini di lingua, valuta e fuso orario, le chiamate daIl Pousadinhas APIdevono essere effettuati tramite i seguenti parametri URL (variabili GET):

  • language-Questa variabile indica la lingua che verrà utilizzata per i messaggi restituiti dall'API;
  • currency-Questa variabile indica la moneta che verrà utilizzata nel prezzo restituito dall'API;
  • timezone-Questa variabile indica il fuso orario che verrà utilizzato nella codifica data e ora restituita dall'API;

IlIl Pousadinhas APIrestituisce sempre i dati in base a questi parametri, indipendentemente dall'impostazione dell'account utente associato al token di accesso utilizzato nella richiesta.

16. Codici di ritorno

Di seguito è riportato un elenco di codici di ritorno di successo o di errore restituito dal API e le situazioni in cui si verificano:

  • 200 - Il successo nella realizzazione dell'operazione;
  • 201 - Il successo nella creazione di un nuovo oggetto;
  • 304 - Il successo nel realizzare l'operazione, ma l'oggetto hash informato chiave coinciso e dati sono stati omessi;
  • 400 - Non sicuro accesso HTTP; Parametri obbligatori o variabili non segnalati; Parametri o variabili aggiuntive non riconosciute; Parametri o variabili non validi; Nessun tale oggetto o JSON valido; Aggiornamento campo che consente di sola lettura; Il funzionamento a secco non supportato;
  • 401 - La mancanza di token di accesso; Accesso non valido Token, scaduto o revocato; Accesso negato l'applicazione;
  • 403 - Autorizzazioni insufficienti per fare la richiesta;
  • 404 - Risorse (raccolta, oggetti, etc.) là;
  • 405 - Tipo di requisizione non supportato;
  • 409 - Impossibile creare / aggiornare / rimozione di un oggetto;
  • 429 - Superato l'accesso quota;

17. Accesso Console

Per acquisire familiarità con il Il Pousadinhas API , Visita API Console powered by Apigee.

Le prove ambientali POUSADINHAS.COM.BR ambiente fittizia è completamente autonomo e identico nella funzionalità per l'ambiente di produzione. Attraverso di esso, è possibile testare tutte le funzionalità della nostra piattaforma in maniera del tutto isolato dalla realtà e senza compromettere il suo funzionamento.

Se siete interessati ad accedere ai nostro ambiente di test, si prega di inviare una mail a recursos@pousadinhas.com.br identificare e descrivere le ragioni della vostra richiesta.