Integrazione gestionale alberghiero con PayTourist tramite API

Puoi integrare il tuo gestionale alberghiero tramite API (Application Programming Interface).

Contatta la tua software house e fornisci la seguente documentazione.

Documentazione PayTourist API

Reservations 

Tramite L’API “RESERVATIONS” il sistema permette l’inserimento, l’aggiornamento, l’eliminazione o il recupero massivo di prenotazioni generate da gestionali alberghieri di terze parti.

 

Le operazioni supportate sono “INSERT”, “UPDATE”, “DELETE” , “RETRIEVE”.

 

Per poter utilizzare il servizio, si necessita prima di tutto di un utente di tipo Booking. L'amministratore della struttura ricettiva dovrà aggiungere su PayTourist un utente con permessi di tipo booking. Questo utente all'interno del profilo deve essere associato al software del gestionale prescelto, tramite il selettore presente all'interno del suo profilo.

Una volta creato questo nuovo utente, si dovrà creare un Token di accesso che avrà validità 12 mesi, scaduti i quali si dovrà provvedere alla generazione di un nuovo Token.

Rimandiamo alla guida su come creare un Token utente.

 

Headers

Tutte le chiamate api (comprese quelle per il reperimento dei dati accessori) richiedono le seguenti opzioni nel proprio header.

 

Chiave	Valore	Da utilizzare
Authorization	Bearer TOKEN (Rilasciato dall’Utente)	Sempre
Accept	application/json	Sempre
Content-Type	multipart/form-data	Nel caso si invii un unico nodo "data" contenete "software_id", "structure_id", "reservations"

 

 

 

 

Gestione Reservations

Il parser PayTourist distingue automaticamente le prenotazioni da inserire, modificare o eliminare dal medesimo endpoint.

Nel caso di un nuovo id verrà effettuato un create di reservation, nel caso venga utilizzato un id pregresso, l'applicazione procede ad effettuare un update della reservation indicata.

Attenzione!!! E' possibile invocare autonomamente fino ad un massimo di 3 update sulla medesima prenotazione (richiamando lo stesso id) ed aggiornando la data di check-out, superato tale numero di chiamate l'operazione sarà identificata come "Non Autorizzata" (403).

 

Endpoint di accesso

Url	Metodo
https://nomecomune.paytourist.com/api/v1/reservations	POST

Struttura del contenuto

Il corpo della request dovrà contenere un solo field (dal nome data) con all'interno l’elenco delle “reservations” in formato JSON (UTF-8).

E’ possibile visionare un esempio completo della “REQUEST” nel file in basso.

REQUEST DI JSON

 

{
 "structure_id": "[int]",
 "software_id": "[int]",
 "reservations": [
 {
 "partner_id": "[string unique]",
 "check_in_date": "[date Y-m-d]",
 "check_out_date": "[date T-m-d]",
 "amount_paid": "[float]",
 "send_copy_by_email_to_master_guest": "[enum {0,1}]",
 "online_portal": "[int - facoltativo - solo se portale abilitato]"
 "total_from_online_portal": "[float - facoltativo - solo se portale abilitato]"
 "guests": [
 {
 "partner_id": "[string]",
 "partner_room_id": "[string]",
 "name": "[string]",
 "surname": "[string]",
 "email": "[string]",
 "check_in_date": "[date Y-m-d]",
 "check_out_date": "[date Y-m-d]",
 "type_id": "[enum {16,17,18,19,20}]",
 "document_type_id": "[int]",
 "document_number": "[string]",
 "document_released_by_country": "[int (Vedi Tabella nazioni)]",
 "document_released_by_city": "[int (Vedi Tabella città )]",
 "sex": "[int]",
 "nationality": "[int (Vedi Tabella nazioni)]",
 "residence_country": "[int (Vedi Tabella nazioni)]",
 "residence_city": "[int (Vedi Tabella città )]",
 "date_of_birth": "[date Y-m-d]",
 "birth_country": "[int (Vedi Tabella nazioni)]",
 "birth_city": "[int (Vedi Tabella città )]",
 "tax_refused": "[enum {0,1}]",
 "reduction_id": "[int (Vedi tabella riduzioni)]"
 },
 {
 "partner_id": "[string]",
 "partner_room_id": "[string]",
 "name": "[string]",
 "surname": "[string]",
 "check_in_date": "[date Y-m-d]",
 "check_out_date": "[date Y-m-d]",
 "type_id": "[enum {16,17,18,19,20}]",
 "sex": "[int]",
 "nationality": "[int (Vedi Tabella nazioni)]",
 "residence_country": "[int (Vedi Tabella nazioni)]",
 "residence_city": "[int (Vedi Tabella città )]",
 "date_of_birth": "[date Y-m-d]",
 "birth_country": "[int (Vedi Tabella nazioni)]",
 "birth_city": "[int (Vedi Tabella città )]",
 "tax_refused": "[enum {0,1}]",
 "reduction_id": "[int (Vedi tabella riduzioni)]"
 }
 ]
 }
 ]
}

 

Di seguito la descrizione dei campi e le rispettive caratteristiche:

 

Nodo “data” 

Attenzione! Nel caso si decida l'invio di un unico nodo "data", che contenga al suo interno il json di "software_id", "structure_id", "reservations", sarà necessario specificare nell'header "Content-Type: multipart/form-data". In questo modo la variabile input sarà una sola, così strutturata:

CASO 1 -> CURLOPT_POSTFIELDS => (['data' => json_encode($data)])

Se al contrario si sceglie di costruire la chiamata passando nella request direttamente "software_id", "structure_id", "reservations" (annidate), la request sarà dipendente dal numero massimo di variabili in input, con il rischio di un eventuale truncate per il raggiungimento massimo del valore consentito.

In questo caso comunque nell'header non bisognerà passare il "Content-Type: multipart/form-data".

CASO 2 -> CURLOPT_POSTFIELDS => http_build_query($data)

 

In fase di implementazione si consiglia uno sviluppo approntato sul CASO 1.

 

Nome Campo	Tipo	Caratteristiche
structure_id	intero	Obbligatorio - Id Paytourist della struttura
software_id	intero	Obbligatorio - Partner Software ID Autorizzato - Rilasciato da PayTourist
reservations	array[reservation]	Obbligatorio - Array di reservations

 

Il software_id identifica il prodotto delle software house che decide di integrare le API. Per ottenerlo basta inviare una email a "sviluppo@paytourist.com". Il software_id, una volta ottenuto ed abilitato in produzione sarà sempre valido su tutti gli ambienti.

Lo structure_id è l'identificativo della struttura su PayTourist.

Come trovarlo? Dal menù di sinistra dell'area riservata PayTourist, basta andare in "Struttura -> Info".

 

 

Foto structure_id su area riservata.

 

 

Nodo “reservation”: Da compilare per operazioni di  inserimento e modifica

Nome Campo	Tipo	Caratteristiche
partner_id	alfanumerico	Obbligatorio - Id reservation del gestionale
check_in_date	format: yyyy-mm-dd	Obbligatorio
check_out_date	format: yyyy-mm-dd	Obbligatorio
amount_paid	float	Facoltativo - Obbligatorio solo se la tassa è in percentuale
send_copy_by_email_to_master_guest	enum {0,1}	0 - Nessun invio email con ricevuta tassa, 1 - invio email ricevuta tassa (se accettata privacy cliente)
guests	array[guests]	Obbligatorio

 

 

Nodo “reservation”: da compilare per operazioni di  eliminazione

Nome Campo	Tipo	Caratteristiche
partner_id	alfanumerico	Obbligatorio - Id reservation del gestionale
is_deleted	bool	Obbligatorio

Nodo “reservation”: dati aggiuntivi facoltativi se abilitato un portale online per la tipologia di struttura

 

(OPZIONALE) Se è presente un accordo specifico tra il Comune e un portale di prenotazione online, per una specifica tipologia di struttura (es. Locazione Breve), è possibile arricchire la chiamata fornendo le informazioni relativamente ad un incasso dell'imposta di soggiorno effettuato da un portale online. La movimentazione viene registrata per la struttura, ma l'importo viene addebitato al portale di prenotazione.

 

Nome Campo	Tipo	Caratteristiche
online_portal	Intero	Facoltativo - Id del portale online abilitato
total_from_online_portal	float	Facoltativo - solo se incassato da portale online

 

 

 

Nodo “Guest”

Nome Campo	Tipo	Caratteristiche
partner_id	Stringa	Obbligatorio - Id guest del gestionale
partner_room_id	alfanumerico	Se presente, Obbligatorio - Id room del gestionale
name	Stringa	Obbligatorio solo nell’ospite principale
surname	Stringa	Obbligatorio solo nell’ospite principale
email	Formato aaa@bbb.ccc	Facoltativo
check_in_date	Formato: yyyy-mm-dd	Facoltativo - Se non presente verrà utilizzato il check in della reservation
check_out_date	Formato: yyyy-mm-dd	Facoltativo - Se non presente verrà processato il checkout della reservation
type_id	Intero	Obbligatorio solo per Ospite Principale - Vedi elenco “Guest Types”
document_type	Intero	Vedi elenco “Document Types”
document_number	Stringa	Facoltativo
document_released_by_country	Intero	Vedi elenco “Nations”
document_released_by_city	Intero	Compilabile solo per gli utenti italiani. Vedi elenco “Cities”
sex	enum {1,2}	Facoltativo 1=M, 2=F (Sebbene facoltativo è fortemente consigliato inserirlo)
nationality	Intero	Vedi elenco “Nations”
residence_country	Intero	Vedi elenco “Nations”
residence_city	Intero	Compilabile solo per gli utenti italiani. Vedi elenco “Cities”
date_of_birth	Formato: yyyy-mm-dd	Facoltativo
birth_country	Intero	Vedi elenco “Nations”
birth_city	Intero	Vedi elenco “Cities”
tax_refused	Intero	Valore 1 se rifiuta, 0 o null altrimenti
reduction_id	Intero	Vedi elenco “Reductions”

 

Informazioni aggiuntive nodo Guest 

In caso di aggiornamento di una prenotazione il parser effettuerà la sincronizzazione dei guest per differenza, dunque nel caso si voglia eliminare un ospite basterà non inserirlo nella nuova chiamata di aggiornamento della "reservation".

Limiti al contenuto dei nodi

Attenzione! Ciascuna chiamata potrà contenere all'interno del nodo "data" al massimo:

- 10 nodi "reservations";

Attenzione! Ciascun nodo "reservations" potrà contenere al massimo:

- 160 nodi "guest";

- Non è possibile importare movimenti in cui gli ospiti siano già partiti da 7 giorni rispetto alla data di trasmissione o comunque antecedenti alla registrazione della struttura nel sistema;

- La data di check-out massima accettata sono 120 giorni dalla data di trasmissione. In caso di ospiti la cui data di partenza sia superiore a tale valore, impostare al massimo 120.

Esempio sui nodi trasmessi:

Nodo Reservation: check-in date-> 2020-01-01 -> max check-out date ammesso 2020-04-30;

Nodo Guest: check-in date-> 2020-01-01 -> max check-out date ammesso 2020-04-30;

In questo caso la response restituirà il messaggio di errore e la procedura di store fallirà.

 

Attenzione! E' possibile effettuare una chiamata di store o update al secondo, superato tale limite o inviate chiamate consecutive si attiva in automatico un throttledi blocco. Pertanto è consigliato raggruppare le reservations tutte in una volta (al max 10) e quindi procedere alla chiamata di invio. Attendere sempre la response della chiamata effettuata e poi procedere al successivo invio, fino al termine di tutto il ciclo programmato lato client. 

 

Valorizzazione Campo Email

Attenzione! Valorizzando il campo email il cliente riceverà la ricevuta relativa all'imposta di soggiorno versata e verrà anche inviato il questionario di gradimento sui servizi turistici, in modo da poter ricevere le recensioni. Assicurasi in questo caso che il modulo recensioni sia stato attivato e che gli ospiti siano stati adeguatamente informati in merito.

 

Rooms Store/Update

Questa funzionalità necessità di tre campi obbligatori che sono: structure_id, software_id e data.

Il campo "data" deve contenere i dati delle room in formato json. Di seguito un esempio.

 

REQUEST DI JSON

 "structure_id": "[int]" -> Params
 "software_id": "[int]" -> Params
 "data": [
 {
 "name": "Camera 101", (Obbligatorio)
 "tags": "vista mare, tag1, tag2",
 "beds_number": 4, (Obbligatorio)
 "is_active": 1,
 "partner_id": "ID ROOM GESTIONALE", (Obbligatorio)
 "type": 50 (Obbligatorio)
 },
 {
 "name": "Camera 102", (Obbligatorio)
 "tags": "vista mare, tag1, tag2",
 "beds_number": 5, (Obbligatorio)
 "is_active": 1,
 "partner_id": "ID ROOM GESTIONALE", (Obbligatorio)
 "type": 50 (Obbligatorio)
 },
...
 ]

 

Endpoint di accesso room list

Url	Lista
https://nomecomune.paytourist.com/api/v1/rooms/types	Lista Tipologie di Camere
https://nomecomune.paytourist.com/api/v1/rooms	Lista Camere della Struttura
https://nomecomune.paytourist.com/api/v1/rooms	Creazione e Aggiornamento Camere
https://nomecomune.paytourist.com/api/v1/rooms	Eliminazione Camere

 

Metodo	Params
GET	Obbligatori: software_id, structure_id
GET	Obbligatori: software_id, structure_id | Facoltativi (results for page -> per page) + Eventuali filtri come da view
POST	Obbligatori: software_id, structure_id
DELETE	https://nomecomune.paytourist.com /api/v1/rooms/{paytourist_room_id}? structure_id={structure_id}&partner_id={room_partner_id} &software_id={software_id})

 

Nodo “data” in chiamata di rooms

Nome Campo	Tipo	Caratteristiche
name	alfanumerico	Obbligatorio - Nome Room del gestionale
tags	alfanumerico	Facoltativo - Tag associati alla room
beds_number	Intero	Obbligatorio - Numero posti letto della room
is_active	enum {0,1}	Facoltativo - Se room attiva o no (0 -> NO; 1 -> SI)
partner_id	Stringa	Obbligatorio - Id della room del gestionale
type	Intero	Obbligatorio - Type di Room Type (fetch di type)

 

 

Consigli per l'integrazione 

E' consigliabile, per velocizzare i tempi di risposta, che il software gestionale effettui una routine, con una singola chiamata per reservation. Attendere la response e procedere alla successiva, fino a completamento dell'operazione di sincronizzazione.

Ciascuna chiamata si preoccuperà di sincronizzare tutte le movimentazioni del giorno, raggruppandole per camera o per ricevuta emessa o per prenotazione effettuata (pre-mapping and group by di guests per fattore comune), ricordandosi dei limiti al contenuto dei nodi di cui sopra. Si ricorda inoltre che per motivi contabili ad ogni reservation verrà emessa una ricevuta sui nostri sistemi, pertanto è sconsigliabile raggruppare tra loro ospiti diversi o che non hanno viaggiato insieme.

Bisogna dunque evitare di inserire nelle medesime reservation ospiti che non si conoscono tra di loro.

In alternativa è possibile inviare per ciascun nodo reservation uno ed un solo ospite (tutti gli ospiti partiti nella giornata vengono trasmessi come ospiti singoli), ed in questo caso verrà emessa una singola ricevuta per ciascun ospite.

ATTENZIONE! In questo secondo caso in ciascuna chiamata effettuata, il "partner_id" che identifica quella specifica reservation, dovrà essere sempre UNIQUE. Se l'id non fosse univoco, la procedura effettuerebbe un UPDATE e non un CREATE di reservation, eliminando gli ospiti trasmessi in precedenza. 

ESEMPIO 1

Sincronizzazione di tutte le ricevute emesse oggi dal gestionale ed associate ad una specifica camera di ospiti partiti.

Prenotazione 145 -> Camera 123 -> 3 Ospiti appartenenti a questa camera -> Partiti e Fatturati Oggi;

{
 "structure_id": "ID DELLA STRUTTURA",
 "software_id": "ID DEL SOFTWARE ABILITATO",
 "reservations": [
 {
 "partner_id": "ID DELLA RESERVATION SPECIFICA DEL GESTIONALE, ES. 145",
 "check_in_date": "DATA DI ARRIVO OSPITI",
 "check_out_date": "DATA PARTENZA OSPITI",
 "amount_paid": "IMPORTO TOTALE DELLA PRENOTAZIONE",
 "send_copy_by_email_to_master_guest": "FLAG INVIO RICEVUTA IMPOSTA",
 "guests": [
 {
 "partner_id": "ID DEL GUEST 1 DEL GESTIONALE",
 "partner_room_id": "ID DELLA ROOM 123 DEL GESTIONALE",
 "name": "NOME OSPITE 1",
 "surname": "COGNOME OSPITE 1",
 "email": "EMAIL OSPITE 1",
 "check_in_date": "DATA ARRIVO OSPITE 1 SE DIVERSO DALLA DATA DI ARRIVO GENERALE",
 "check_out_date": "DATA PARTENZA OSPITE 1 SE DIVERSO DALLA DATA DI ARRIVO GENERALE",
 "sex": "SESSO OSPITE 1",
 "nationality": "CITTADINANZA OSPITE 1",
 "residence_country": "NAZIONE RESIDENZA OSPITE 1",
 "residence_city": "CITTA' RESIDENZA OSPITE 1",
 "date_of_birth": "DATA DI NASCITA OSPITE 1",
 "birth_country": "STATO DI NASCITA OSPITE 1",
 "birth_city": "CITTA' DI NASCITA OSPITE 1",
 "tax_refused": "RIFIUTO AL PAGAMENTO DELLA TASSA OSPITE 1",
 "reduction_id": "TIPO RIDUZIONE, SE PRESENTE, OSPITE 1",
 },
 {
 "partner_id": "ID DEL GUEST 2 DEL GESTIONALE",
 "partner_room_id": "ID DELLA ROOM 123 DEL GESTIONALE",
 "name": "NOME OSPITE 2",
 "surname": "COGNOME OSPITE 2",
 "email": "EMAIL OSPITE 2",
 "check_in_date": "DATA ARRIVO OSPITE 2 SE DIVERSO DALLA DATA DI ARRIVO GENERALE",
 "check_out_date": "DATA PARTENZA OSPITE 2 SE DIVERSO DALLA DATA DI ARRIVO GENERALE",
 "sex": "SESSO OSPITE 2",
 "nationality": "CITTADINANZA OSPITE 2",
 "residence_country": "NAZIONE RESIDENZA OSPITE 2",
 "residence_city": "CITTA' RESIDENZA OSPITE 2",
 "date_of_birth": "DATA DI NASCITA OSPITE 2",
 "birth_country": "STATO DI NASCITA OSPITE 2",
 "birth_city": "CITTA' DI NASCITA OSPITE 2",
 "tax_refused": "RIFIUTO AL PAGAMENTO DELLA TASSA OSPITE 2",
 "reduction_id": "TIPO RIDUZIONE, SE PRESENTE, OSPITE 2",
 },
 {
 "partner_id": "ID DEL GUEST 3 DEL GESTIONALE",
 "partner_room_id": "ID DELLA ROOM 123 DEL GESTIONALE",
 "name": "NOME OSPITE 3",
 "surname": "COGNOME OSPITE 3",
 "email": "EMAIL OSPITE 3",
 "check_in_date": "DATA ARRIVO OSPITE 3 SE DIVERSO DALLA DATA DI ARRIVO GENERALE",
 "check_out_date": "DATA PARTENZA OSPITE 3 SE DIVERSO DALLA DATA DI ARRIVO GENERALE",
 "sex": "SESSO OSPITE 3",
 "nationality": "CITTADINANZA OSPITE 3",
 "residence_country": "NAZIONE RESIDENZA OSPITE 3",
 "residence_city": "CITTA' RESIDENZA OSPITE 3",
 "date_of_birth": "DATA DI NASCITA OSPITE 3",
 "birth_country": "STATO DI NASCITA OSPITE 3",
 "birth_city": "CITTA' DI NASCITA OSPITE 3",
 "tax_refused": "RIFIUTO AL PAGAMENTO DELLA TASSA OSPITE 3",
 "reduction_id": "TIPO RIDUZIONE, SE PRESENTE, OSPITE 3",
 }
 ]
....

 

ESEMPIO 2

Sincronizzazione per giorno di tutte le partenze degli ospiti. Tutti gli ospiti sono trasmessi come singoli, giorno per giorno.

- Movimenti dell'altro IERI -> Prenotazione 145 -> Camera 123 -> 3 Ospiti appartenenti a questa camera -> Partito Oggi 1 solo ospite;

- Movimenti di IERI -> Prenotazione 145 ->Camera 123 -> 3 Ospiti appartenenti a questa camera -> Partito Oggi 1 altro ospite;

- Movimenti di OGGI -> Prenotazione 145 ->Camera 123 -> 3 Ospiti appartenenti a questa camera -> Partito Oggi l'ultimo ospite;

In questo caso sebbene tutti e tre gli ospiti trasmessi nei vari giorni appartenevano alla medesima camera e/o prenotazione, non potranno essere trasmessi con il medesimo "ID DI RESERVATION 145".

Questo perché dalla seconda sincronizzazione in poi, passando sempre il medesimo ID -> 145 il sistema non effettuerà più nuovi inserimenti, ma procederà semplicemente ad aggiornare sempre la medesima reservation 145.

Alla trasmissione di oggi risulterebbe non corretto l'aggiornamento della Prenotazione 145 -> Camera 123 -> Con solo 1 ospite trasmesso, gli altri 2 ospiti arrivati precedentemente verrebbero eliminati.

Movimenti dell'altro IERI
{
 "structure_id": "ID DELLA STRUTTURA",
 "software_id": "ID DEL SOFTWARE ABILITATO",
 "reservations": [
 {
 "partner_id": "ID RESERVATION UNIQUE (NO 145, ES. ID OSPITE GESTIONALE + ID PRENOTAZIONE GESTIONALE)",
 "check_in_date": "DATA DI ARRIVO OSPITE 1",
 "check_out_date": "DATA PARTENZA OSPITE 1 (altro ieri)",
 "amount_paid": "IMPORTO TOTALE DELLA PRENOTAZIONE",
 "send_copy_by_email_to_master_guest": "FLAG INVIO RICEVUTA IMPOSTA",
 "guests": [
 {
 "partner_id": "ID DEL GUEST 1 DEL GESTIONALE",
 "partner_room_id": "ID DELLA ROOM 123 DEL GESTIONALE",
 "name": "NOME OSPITE 1",
 "surname": "COGNOME OSPITE 1",
 "email": "EMAIL OSPITE 1",
 "sex": "SESSO OSPITE 1",
 "nationality": "CITTADINANZA OSPITE 1",
 "residence_country": "NAZIONE RESIDENZA OSPITE 1",
 "residence_city": "CITTA' RESIDENZA OSPITE 1",
 "date_of_birth": "DATA DI NASCITA OSPITE 1",
 "birth_country": "STATO DI NASCITA OSPITE 1",
 "birth_city": "CITTA' DI NASCITA OSPITE 1",
 "tax_refused": "RIFIUTO AL PAGAMENTO DELLA TASSA OSPITE 1",
 "reduction_id": "TIPO RIDUZIONE, SE PRESENTE, OSPITE 1",
 },
...
]}
...
]


Movimenti di IERI
{
 "structure_id": "ID DELLA STRUTTURA",
 "software_id": "ID DEL SOFTWARE ABILITATO",
 "reservations": [
 {
 "partner_id": "ID RESERVATION UNIQUE (NO 145, ES. ID OSPITE GESTIONALE + ID PRENOTAZIONE GESTIONALE)",
 "check_in_date": "DATA DI ARRIVO OSPITE 2",
 "check_out_date": "DATA PARTENZA OSPITE 2 (ieri)",
 "amount_paid": "IMPORTO TOTALE DELLA PRENOTAZIONE",
 "send_copy_by_email_to_master_guest": "FLAG INVIO RICEVUTA IMPOSTA",
 "guests": [
 {
 "partner_id": "ID DEL GUEST 2 DEL GESTIONALE",
 "partner_room_id": "ID DELLA ROOM 123 DEL GESTIONALE",
 "name": "NOME OSPITE 2",
 "surname": "COGNOME OSPITE 2",
 "email": "EMAIL OSPITE 2",
 "sex": "SESSO OSPITE 2",
 "nationality": "CITTADINANZA OSPITE 2",
 "residence_country": "NAZIONE RESIDENZA OSPITE 2",
 "residence_city": "CITTA' RESIDENZA OSPITE 2",
 "date_of_birth": "DATA DI NASCITA OSPITE 2",
 "birth_country": "STATO DI NASCITA OSPITE 2",
 "birth_city": "CITTA' DI NASCITA OSPITE 2",
 "tax_refused": "RIFIUTO AL PAGAMENTO DELLA TASSA OSPITE 2",
 "reduction_id": "TIPO RIDUZIONE, SE PRESENTE, OSPITE 2",
 },
...
]}
...
]

Movimenti di OGGI
{
 "structure_id": "ID DELLA STRUTTURA",
 "software_id": "ID DEL SOFTWARE ABILITATO",
 "reservations": [
 {
 "partner_id": "ID RESERVATION UNIQUE (NO 145, ES. ID OSPITE GESTIONALE + ID PRENOTAZIONE GESTIONALE)",
 "check_in_date": "DATA DI ARRIVO OSPITE 3",
 "check_out_date": "DATA PARTENZA OSPITE 3 (oggi)",
 "amount_paid": "IMPORTO TOTALE DELLA PRENOTAZIONE",
 "send_copy_by_email_to_master_guest": "FLAG INVIO RICEVUTA IMPOSTA",
 "guests": [
 {
 "partner_id": "ID DEL GUEST 3 DEL GESTIONALE",
 "partner_room_id": "ID DELLA ROOM 123 DEL GESTIONALE",
 "name": "NOME OSPITE 3",
 "surname": "COGNOME OSPITE 3",
 "email": "EMAIL OSPITE 3",
 "sex": "SESSO OSPITE 3",
 "nationality": "CITTADINANZA OSPITE 3",
 "residence_country": "NAZIONE RESIDENZA OSPITE 3",
 "residence_city": "CITTA' RESIDENZA OSPITE 3",
 "date_of_birth": "DATA DI NASCITA OSPITE 3",
 "birth_country": "STATO DI NASCITA OSPITE 3",
 "birth_city": "CITTA' DI NASCITA OSPITE 3",
 "tax_refused": "RIFIUTO AL PAGAMENTO DELLA TASSA OSPITE 3",
 "reduction_id": "TIPO RIDUZIONE, SE PRESENTE, OSPITE 3",
 },
...
]}
...
]

Dunque sulla base delle indicazioni di cui sopra, consigliamo di adottare la logica più idonea per la trasmissione delle informazioni di integrazione.

 

Recupero Reservations 

Il parser PayTourist recupera la lista delle prenotazioni generate da gestionali alberghieri di terze parti.

 

Endpoint di accesso

Url	Metodo
https://nomecomune.paytourist.com/api/v1/reservations	GET

 

Parametri recupero Reservations (Retrieve)

 

Nome Campo	Tipo	Caratteristiche
Parametri Obbligatori
structure_id	Intero	Obbligatorio ID struttura (paytourist)
software_id	Intero	Obbligatorio - Partner ID Autorizzato - Rilasciato da PayTourist
Parametri Facoltativi
partner_id	Stringa	Filtro per id reservation (Facoltativo)
perpage	Intero	Numero reservations per Pagina (default 10, max 50)
created_at	Tipo:Date format: yyyy-mm-dd	Filtra per reservations create in una specifica data (esempio -> created_at=2022-08-02)
updated_at	Tipo:Date format: yyyy-mm-dd	Filtra per reservations aggiornate in una specifica data(esempio -> updated_at=2022-08-30)
created_start	Tipo:Date format: yyyy-mm-dd	Filtra per reservations create a partire da una specifica data(esempio -> created_start=2022-03-15)
created_end	Tipo:Date format: yyyy-mm-dd	Filtra per reservations create fino ad una specifica data(esempio -> created_end=2022-03-18)
check_in_date	Tipo:Date format: yyyy-mm-dd	Filtra per reservations il cui check in è stato effettuato in una specifica data(esempio -> check_in_date=2022-02-10)
check_in_start_date	Tipo:Date format: yyyy-mm-dd	Filtra per reservations il cui check in è avvenuto a partire da una specifica data (esempio -> check_in_start_date=2022-04-10)
check_in_end_date	Tipo:Date format: yyyy-mm-dd	Filtra per reservations il cui check out è avvenuto entro una specifica data (esempio -> check_in_end_date=2022-04-15)

Chiamate REST delle informazioni accessorie

 

Tramite le seguenti chiamate è possibile ottenere le informazioni utente e le liste dati accessorie alla compilazione dei campi, passando structure_id e sofware_id.

 

Url	Lista	Metodo
https://nomecomune.paytourist.com/api/v1/users/me	Utente proprietario token	GET
https://nomecomune.paytourist.com/api/v1/structures	Strutture associate al token	GET
https://nomecomune.paytourist.com/api/v1/nations	Nazioni	GET
https://nomecomune.paytourist.com/api/v1/cities	Città	GET
https://nomecomune.paytourist.com/api/v1/documents-types	Tipologie di documento	GET
https://nomecomune.paytourist.com/api/v1/guests-types	Tipologie di ospite	GET
https://nomecomune.paytourist.com/api/v1/reductions	Elenco riduzioni	GET
https://nomecomune.paytourist.com/api/v1/online-portals-enabled	Portali Online Abilitati	POST

Tariffazione delle tasse per periodo

Url : https://nomecomune.paytourist.com/api/vi1/tax-rules

 

Nome Campo	Tipo	Caratteristiche
start_date	Formato: yyyy-mm-dd	Obbligatorio
end_date	Formato: yyyy-mm-dd	Obbligatorio
structure_id	Intero	Obbligatorio - Id Paytourist della struttura
software_id	Intero	Obbligatorio - Partner Software ID Autorizzato - Rilasciato da PayTourist

 

Validatori

 

Tutte le richieste vengono validate dalle seguenti regole:

La data di check out della reservations e dei guest deve essere successiva a quella di check in.

 

Lista reservations 

Url : https://nomecomune.paytourist.com/api/vi1/reservations

Metodo GET

 

Nome Campo	Tipo	Caratteristiche
structure_id	Intero	Obbligatorio ID struttura (paytourist)
software_id	Intero	Obbligatorio - Partner Software ID Autorizzato - Rilasciato da PayTourist
partner_id	Stringa	Filtro per id reservation
perpage	Intero	Numero reservations per Pagina (default 10, max 50)

 

 

Area Test

Per l'area test bisogna sostituire il "nomecomune.paytourist.com" con "test.paytourist.com"

 

Per supporto in merito all'integrazione potete scrivere a sviluppo@paytourist.com

 

 

 Questa guida si riferisce alla sezione "ps/import" del portale.