Guesty Open API: Guida rapida e risoluzione dei problemi

Questa guida è pensata per gli sviluppatori che si integrano per la prima volta con l'API aperta di Guesty. Per maggiori informazioni, consultare il sito open-api-docs.guesty.com.

Avvio rapido

1. Ottieni le tue credenziali

Innanzitutto, assicurati che il tuo account Guesty abbia accesso alle API aperte. Dovrai ottenere le tue credenziali OAuth: client_id e client_secret. Per istruzioni dettagliate, consulta la sezione 'Per iniziare'.

2. Autenticazione

Scambia le tue credenziali con un token bearer: POST https://open-api.guesty.com/oauth2/token con grant_type=client_credentials, scope=open-api, client_id e client_secret. Il token è valido per 24 ore.

Proteggi il tuo token e monitora la sua scadenza. Ogni client_id può richiedere un nuovo token fino a cinque volte nell'arco di 24 ore. Se raggiungi questo limite, non potrai ottenere un nuovo token finché la finestra temporale non si sarà ripristinata. Per evitare problemi, pianifica di aggiornare il tuo token qualche minuto prima della scadenza. Per esempi di codice in Node.js, Python e PHP, consulta la guida 'Gestione dei token di accesso'. Per maggiori dettagli, consulta la sezione 'Autenticazione'.

3. Fai la tua prima chiamata

Invia il token come intestazione bearer per ogni richiesta:

GET https://open-api.guesty.com/v1/listings
Authorization: Bearer {access_token}

4. Gestire la paginazione

La maggior parte degli endpoint utilizza i parametri di query limit e skip per la paginazione e restituisce items, count, limit e skip nella risposta. Alcuni endpoint potrebbero utilizzare offset o cursor, oppure restituire un formato di risposta diverso. Se i parametri standard non funzionano, rivedi la pagina di riferimento per quello specifico endpoint. Ad esempio:

offset invece di skip: GET /properties-api/groups/group
basato su cursor: GET /communication/conversations, GET /communication/conversations/{conversationId}/posts
results + un oggetto pagination nidificato: GET /reservations-v3/search (lo stesso endpoint di ricerca Prenotazioni v3 utilizzato altrove in questa guida)
results/count invece di items/count: GET /vendors, GET /users, GET /property-logs/{id}

Risoluzione dei problemi e domande frequenti

Prima di riprovare una richiesta, controlla il codice di stato. Solo gli errori 429 e 5xx dovrebbero essere ritentati automaticamente. Altri codici di stato indicano che la richiesta deve essere modificata prima di riprovare.

Tramite codice di risposta

401 / 403 — "Non autorizzato" subito dopo l'autenticazione: il tuo token è scaduto (dura 24 ore) o non è stato inviato correttamente. Nota: L'API di Guesty restituisce un 403 anche quando il messaggio dice "Non autorizzato": questo è previsto, non è un bug da parte tua. Soluzione: riautenticati e memorizza nuovamente il token nella cache; verifica che l'intestazione sia esattamente Authorization: Bearer <token>. L'endpoint del token espone anche le intestazioni x-ratelimit-remaining-day / x-ratelimit-limit-day se desideri monitorare direttamente il tuo budget giornaliero di token. Ulteriori informazioni: Autenticazione.

404 — Risorsa non trovata, ma l'ID sembra corretto: in genere, l'ID appartiene a un account/ambito diverso dal tuo token, oppure il record non è ancora stato sincronizzato, o proviene da un portale con visibilità API limitata. Verifica l'ID confrontandolo con la dashboard dello stesso account a cui appartengono le tue credenziali. Ad esempio, GET /reservations-v3/group/{groupId} restituisce 404 sia per un ID apparentemente valido associato a un account sbagliato, sia per un ID inesistente. Ulteriori informazioni: Codici di risposta.

410 — Preventivo scaduto: I preventivi hanno una data di scadenza fissa. Una volta scaduti, non possono essere modificati o prenotati. Crea un nuovo preventivo anziché riprovare con il vecchio ID.

400 / 422 — errore di validazione: verifica il corpo della richiesta rispetto allo schema di quell'endpoint nella sua pagina di riferimento. Le risposte di errore di Guesty non hanno una struttura uniforme in tutta l'API: alcuni campi sono annidati sotto l'errore, altri no, e i nomi dei campi variano, quindi non dare per scontato che il nome di un campo di errore di un endpoint sia valido anche per un altro. Ad esempio, POST /reservations-v3 (prenotazione rapida) restituisce sia 400 che 422 a seconda che la richiesta stessa sia malformata o violi una regola di prenotazione (ad esempio, date non disponibili): verifica quale errore hai ricevuto prima di presumere la soluzione.

429 — limite di tariffa: significa che hai raggiunto il limite a livello di account di 15 richieste al secondo, 120 al minuto o 5.000 all'ora, condiviso tra tutti i token. Attendi il tempo specificato nell'intestazione Retry-After prima di inviare un'altra richiesta. Monitora le intestazioni X-RateLimit-Remaining-Second, X-RateLimit-Remaining-Minute e X-RateLimit-Remaining-Hour per tenere traccia del tuo utilizzo. Potresti anche visualizzare le intestazioni ratelimit-limit, ratelimit-remaining e ratelimit-reset headers, che riflettono l'intervallo per secondo. Prima di richiedere un limite superiore, valuta la possibilità di utilizzare il batching, la cache, il filtraggio o i webhook per ottimizzare la tua integrazione. Se viene applicato un limite inferiore dopo un superamento prolungato, ciò potrebbe indicare che un precedente aumento è stato annullato. Per maggiori dettagli, consulta Limiti Tariffa.

"Non posso creare un'altra app OAuth /client_id": questo è un limite separato — il numero di applicazioni OAuth per account è cinque — distinto dal limite di frequenza delle richieste menzionato sopra. Se hai bisogno di più richieste, contatta il supporto descrivendo il tuo caso specifico.

5xx — errore del server: riprova con un intervallo esponenziale anziché riavviare immediatamente il ciclo. La maggior parte degli errori 5xx sono temporanei; se un endpoint fallisce ripetutamente, includi l'intestazione di risposta x-request-id quando contatti il supporto. Eccezione: per una richiesta di pagamento o di modifica della prenotazione, verifica prima lo stato effettivo: non riprovare alla cieca, altrimenti rischi di addebitare due volte un ospite. Ulteriori informazioni: Gestione delle richieste non riuscite.

In base al sintomo

Se una prenotazione o un annuncio non compare nei risultati della ricerca o nell'elenco, verifica innanzitutto i parametri filtro e di ambito. Questa è la causa più comune. Per i record recenti, attendi che la sincronizzazione sia completata, soprattutto per le prenotazioni provenienti da piattaforme come Airbnb, Vrbo o Booking.com. È proprio a questo che serve GET /reservations-v3/search: assicurati di utilizzarla (con i parametri filter[...] corretti) anziché un endpoint più vecchio o con funzionalità limitate. Se il record non è ancora presente, contatta il supporto fornendo l'ID specifico e la richiesta esatta che hai utilizzato.

Se il tuo webhook non si attiva o non riesci a iscriverti, verifica quanto segue: (1) Conferma di esserti iscritto al nome evento v2 corretto, poiché i webhook legacy e v2 non sono intercambiabili. (2) Assicurati che il tuo endpoint restituisca una risposta 2xx, poiché Guesty smetterà di riprovare se non la restituisce. (3) Negli account di test o sandbox, verifica che l'iscrizione sia stata creata correttamente. La consegna potrebbe subire ritardi durante i periodi di carico elevato. L' evento listing.calendar.updated si attiva solo per le modifiche dirette al calendario, alla tariffa o al soggiorno minimo, non per le prenotazioni nuove o modificate. Per verificare l'autenticità di un webhook, recupera il segreto di firma del tuo endpoint utilizzando GET /webhooks-v2/secret. Per ulteriori informazioni, consulta la Panoramica sui webhook.

Se hai aggiornato il titolo o la descrizione dell'annuncio tramite API e non vedi la modifica su Airbnb, verifica se il campo è stato modificato direttamente su Airbnb. In tal caso, Airbnb blocca il campo e gli aggiornamenti API non verranno sincronizzati finché non lo sblocchi su Airbnb. Gli aggiornamenti effettuati tramite PUT /marketing/description-sets/{id} o POST /marketing/description-sets non verranno sincronizzati con Airbnb finché il campo non viene sbloccato. Altri canali come Booking.com e Vrbo potrebbero avere requisiti simili. Per ulteriori informazioni, consulta la sezione Campi Marketing e traduzioni.

GuestyPay restituisce 402 ERR_BAD_REQUEST: se la risposta include "La richiesta contraddice la cancellazione della configurazione dell'interfaccia" o "Bad Bin o Host Disconnect", l'account GuestyPay stesso presenta un problema di configurazione o è offline: questo non è un problema che puoi risolvere nella tua integrazione. Contatta Esperienza del cliente.

La struttura dell'errore non corrisponde a quella che ho visto su un altro endpoint: previsto — non esiste un unico tipo di error per l'intera API. Tuttavia, un modello è il più comune: un messaggio annidato sotto una singola chiave di errore, ad esempio, GET /accounting-api/reservations/{id}/balance → {"error": {"message": "...", "status": 404}}. Non è universale, però: alcuni endpoint sono piatti con il messaggio come un array di stringhe ( GET /guest-folio/invoice-items → {"statusCode": 400, "message": [...]} ), e alcuni includono il proprio campo requestId a livello di corpo, separato dall'intestazione x-request-id ( GET /availability-pricing/api/calendar/listings/{id} ). Un buon numero di endpoint non documenta affatto la struttura del corpo dell'errore, ma solo una descrizione testuale. Verifica lo schema di errore documentato dello specifico endpoint anziché inserire una forma predefinita nel codice.

Ho bisogno di un "account di test" o di un account "sandbox"? Ecco una regola generale: usa un account di test per quasi tutte le integrazioni e lo sviluppo iniziali, a meno che tu non stia testando specificamente flussi relativi a Stripe, nel qual caso hai bisogno di un account sandbox. Usa l'ambiente di produzione solo quando sei pronto per andare online con dati reali. Gli account di test sono lo standard per le nuove richieste di integrazione e funzionano esattamente come l'ambiente di produzione, solo con dati di test separati. Gli account sandbox sono ambienti separati (cerca "sandbox" nell'URL) utilizzati per i test di integrazione con Stripe perché Guesty non accetta chiavi di test di Stripe né negli account di produzione né negli account di test standard. GuestyPay non ha alcun ambiente di test: funziona solo in produzione, quindi devi usare una carta reale per testare GuestyPay, indipendentemente dal tipo di account che stai usando.

L'account di prova è un componente aggiuntivo a pagamento ed è separato dall'ambiente di produzione. I dati non vengono trasferiti dall'ambiente di produzione, quindi dovrai configurare da zero annunci, prenotazioni e altre informazioni. Per ottenere un account di prova, contatta il tuo account manager.

Server MCP (Beta)

Il Guesty MCP Server consente agli assistenti IA compatibili con MCP (attualmente Cursor, Claude Desktop, VS Code (Copilot) e Google Antigravity) di leggere i dati Guesty tramite un'interfaccia controllata. In versione beta è in sola lettura: gli assistenti possono cercare e riassumere i dati, ma non possono ancora creare, aggiornare o eliminare record. La compatibilità con altri strumenti potrebbe cambiare prima della disponibilità generale.

Collegamento

Attualmente, è possibile connettersi utilizzando il metodo locale o quello ospitato. Una distribuzione completamente gestita con credenziali già predisposte non è ancora disponibile.

Locale (stdio, consigliato): Eseguire utilizzando npx -y @guestyorg/sdk mcp. È possibile utilizzare una variabile d'ambiente BEARER_TOKEN per un token di accesso statico, oppure le variabili d'ambiente CLIENT_ID e CLIENT_SECRET. Il server MCP scambierà automaticamente queste credenziali, quindi non è necessario alcun passaggio manuale per il token.
Autenticazione ospitata (HTTP, https://mcp.guesty.com/v1): Autenticarsi utilizzando un'intestazione Authorization all'inizio della sessione, oppure utilizzare lo strumento set_token dopo la connessione.

Risoluzione dei problemi

Errore 401 a ogni chiamata dello strumento: questo indica che non è stato impostato alcun token. Per le connessioni ospitate o HTTP, assicurarsi di impostare il token utilizzando set_token o l'intestazione Authorization prima di utilizzare qualsiasi altro strumento.

403, in modo incoerente: questo errore può verificarsi con token scaduti o quando i client OAuth hanno ambiti per l'accesso Open API standard ma non per MCP. Innanzitutto, autenticarsi nuovamente con un nuovo token. Se il problema persiste, verificare che il client OAuth abbia ambiti MCP configurati oltre all'accesso Open API v1.

Connesso tramite Claude.ai (web), ma non vengono visualizzati strumenti: Claude.ai web non è attualmente un client supportato. Aggiungendolo come connettore solo URL, viene utilizzato per impostazione predefinita il rilevamento OAuth , che questo server non supporta. Utilizzare un client supportato tramite stdio per la piena funzionalità.

Si verificano problemi di limitazione delle richieste o errori 401 ripetuti dopo il riavvio dell'MCP: quando si utilizzano CLIENT_ID e CLIENT_SECRET, ogni riavvio richiede un nuovo token, che viene conteggiato nel limite di 5 token ogni 24 ore. Per evitare ciò, riutilizzare un token memorizzato nella cache tra i riavvii oppure utilizzare un BEARER_TOKEN statico, che non richiede un nuovo scambio.

Se i risultati delle prenotazioni o delle registrazioni contabili appaiono incompleti, verifica di utilizzare lo Search Reservations tool v3, che supporta filter[confirmationCode]. Il vecchio strumento di ricerca è in fase di dismissione e potrebbe non restituire tutti i risultati. Per le ricerche di registrazioni contabili ( Get recognized journal entries / Get all journal entries ), se continua a visualizzare risultati imprevisti, apri un ticket di supporto con informazioni dettagliate.

Ho chiesto all'assistente di creare, aggiornare o annullare qualcosa, e non l'ha fatto: previsto nella versione beta: il server MCP è per ora in sola lettura.

Apertura di un ticket di supporto

Innanzitutto, controlla il tuo sistema. Guesty non può diagnosticare problemi in applicazioni esterne. Se il problema potrebbe risiedere nel tuo codice, chiedi al tuo sviluppatore web o fornitore tecnico una revisione prima di contattare Guesty. Se l'integrazione è stata realizzata da un partner del marketplace, contatta prima quest'ultimo. Sarà lui a contattare Guesty, se necessario.

Una volta esclusi eventuali problemi da parte tua, contatta Esperienza del cliente o utilizza la chat in diretta. Entrambe le opzioni sono disponibili tramite la dashboard Guesty e il Centro assistenza. Fornire il contesto ci aiuta a risolvere il problema più velocemente, quindi includi le seguenti informazioni:

Quello che stavi cercando di realizzare (l'obiettivo effettivo, non solo la chiamata fallita, ad esempio "sincronizzare lo stato del pagamento di una nuova prenotazione", non solo "POST ha restituito 422")
I passaggi che hanno portato all'errore, in ordine, in modo che l'assistenza possa riprodurlo, non solo la richiesta finale fallita.
Quando è successo — un'indicazione oraria precisa, se disponibile, altrimenti una data o un intervallo di date; questa è una delle informazioni più utili che puoi fornire.
URL completo della richiesta e metodo in formato cURL
Il messaggio di errore esatto e il codice di stato
Il valore dell'intestazione di risposta x-request-id
L'intestazione x-gst-kong-dc, se presente (aiuta a identificare il data center che ha gestito la richiesta)
Che si tratti di un comportamento nuovo o che il problema si sia sempre presentato
Per i problemi relativi a MCP: quale client e modalità di connessione (stdio/HTTP) e se l'autenticazione è avvenuta tramite BEARER_TOKEN, CLIENT_ID/CLIENT_SECRET, o set_token

Per ulteriori approfondimenti

Correlato a:

GFP: Open Api