Guida all'integrazione

L'API di Airbnb: come funziona l'accesso e cosa ti permette davvero di fare

Scritta per lo sviluppatore o il founder tecnico a cui hanno chiesto di «collegare Airbnb e basta». Spiega come viene concesso l'accesso partner, cosa l'API può e non può cambiare, e i problemi specifici che fanno sembrare sana un'integrazione con Airbnb mentre non fa nulla. Tutto ciò che c'è qui viene dall'aver gestito questa integrazione in produzione.

Cos'è l'API di Airbnb

Non esiste un'unica “API di Airbnb” pubblica. Esiste un'API per partner: una superficie REST che Airbnb apre ad aziende software approvate, così che i loro clienti — host e property manager — possano gestire gli annunci fuori da airbnb.com. Non è aperta a chiunque abbia una carta di credito, e non c'è nessuna sandbox a cui iscriversi un martedì pomeriggio.

La superficie in sé è ampia. Una connessione con autorizzazione completa può leggere e scrivere contenuti dell'annuncio, foto, stanze e letti, servizi, calendario, prezzo per notte, impostazioni di prenotazione, messaggi con gli ospiti, prenotazioni, recensioni, offerte speciali, modifiche delle prenotazioni e transazioni dei pagamenti. I limiti non sono quasi mai “l'endpoint non esiste”. Riguardano chi ha autorizzato cosa, e per quale annuncio.

Come ottengo l'accesso all'API di Airbnb?

Prima della tua prima scrittura riuscita devono verificarsi tre cose, e le concedono tre parti diverse.

1. Airbnb approva la tua azienda come partner software.Invii la candidatura, descrivi il prodotto che stai costruendo e vieni valutato in una categoria di prodotto: software di gestione delle proprietà, strumento di messaggistica, strumento di pricing. L'approvazione porta con sé un client OAuth (un client id e un secret) limitato a quella categoria. È una verifica commerciale e di conformità della tua azienda, non un'iscrizione da sviluppatore, e si misura in settimane o mesi.
2. Ogni host autorizza la tua app.L'approvazione ti dà la possibilità di chiedere; non ti dà dati. Ogni host passa da una schermata di consenso OAuth, sceglie cosa può gestire la tua app e ti concede i token per il suo account. Un host, un'autorizzazione.
3. Ogni annuncio viene aperto all'API.È il passaggio che sorprende tutti, quindi ha una sezione a parte più sotto. Autorizzare l'account non autorizza gli annunci che contiene.

Su Repull l'intero flusso è un'unica sessione ospitata: il tuo server la crea, reindirizzi l'host e ricevi una connessione. Il funzionamento, compresi i parametri di reindirizzamento, è nella guida per collegare Airbnb.

curl -X POST 'https://api.repull.dev/v1/connect/airbnb' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "redirectUrl": "https://yourapp.com/connected", "accessType": "full_access" }'

Quale ambito deve chiedere la tua app?

La schermata di consenso non è un unico sì. L'host concede un livello, e il livello che chiedi decide sia cosa puoi fare sia se la connessione è possibile.

• Gestione delle proprietà (accesso completo): lettura più scrittura di annunci, calendario e prezzi. Quello che serve a un PMS o a un channel manager.
• Messaggistica: lettura di tutto, più invio di messaggi agli ospiti. Nessuna gestione di annunci, calendario o prezzi.
• Sola lettura: annunci, prenotazioni, calendari, messaggi e recensioni. Il livello giusto per analytics, report e BI.

I livelli più ristretti convertono anche meglio, perché la schermata di consenso elenca meno permessi e meno allarmanti. Vedi Collegare Airbnbper fissare un livello per sessione o lasciar scegliere l'host.

Perché un account collegato rifiuta ancora ogni scrittura

Airbnb autorizza la sincronizzazione API un annuncio alla volta, non un account alla volta. Ogni annuncio ha la propria categoria di sincronizzazione. Un annuncio con categoria noneè chiuso all'API e Airbnb rifiuta ogni scrittura, qualunque sia lo stato dell'account.

Le categorie che contano:

• sync_all: contenuti, tariffe e disponibilità sono gestiti tramite l'API.
• sync_rates_and_availability: le scritture di calendario e prezzi funzionano; il contenuto dell'annuncio resta all'host.
• none: ogni scrittura viene rifiutata.

Posso aggiornare prezzi e disponibilità tramite l'API di Airbnb?

Sì, su un annuncio aperto all'API e con un permesso di gestione delle proprietà. È la parte di Airbnb che si comporta come ti aspetteresti: scritture per data, applicate al calendario dell'annuncio e riflesse sull'annuncio.

Prezzo per notte, aperto o chiuso, notti minime e massime, divieto di arrivo e di partenza sono tutti modificabili per data, insieme a regole di disponibilità a livello di annuncio come le notti minime predefinite, l'anticipo di prenotazione e i giorni di preparazione.

# Block a range on Airbnb, saying why it is blocked
curl -X PUT 'https://api.repull.dev/v1/channels/airbnb/listings/4118/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "calendar",
    "operations": [{
      "dates": ["2026-07-01:2026-07-04"],
      "availability": "unavailable",
      "busy_subtype": "OUTSIDE_RESERVATION"
    }]
  }'

Tutti i parametri sono in Inviare la disponibilità ad Airbnb e Aggiornare i prezzi su Airbnb. Se vuoi che una sola scrittura arrivi a tutti i canali collegati insieme e non solo ad Airbnb, quello è PUT /v1/availability/{propertyId}: vedi Aggiornare i prezzi.

Posso modificare il contenuto dell'annuncio?

In parte, ed è qui che un'integrazione con Airbnb fallisce più spesso in silenzio. Due regole spiegano quasi tutto.

Pubblicare non è una sola chiamata

Inviare il contenuto di un annuncio ad Airbnb richiede fino a otto chiamate indipendenti — dettagli, descrizione, servizi, stanze, regole, foto, prezzi, attività di check-out — e ognuna può fallire da sola. Una pubblicazione parziale è il risultato normale, e non c'è rollback: le sezioni andate a buon fine restano applicate. Qualsiasi modello di stato che tratta la pubblicazione come un unico booleano sarà sbagliato entro una settimana. Riportalo per sezione.

Un 200 non prova che la modifica sia stata applicata

Su un annuncio consolidato Airbnb considera alcuni contenuti gestiti dall'host e non accetta modifiche tramite alcuna API. Non risponde con un errore. La richiesta restituisce 200, la risposta indica gli attributi bloccati e su di essi non viene applicato nulla. Quelli bloccati più spesso: titolo, riepilogo e testo dello spazio, categoria del tipo di proprietà, opzione di check-in, campi dell'indirizzo e singoli servizi.

Leggi in anticipo l'insieme dei campi bloccati invece di scoprirlo per confronto. GET /v1/channels/airbnb/listings/{id}/details restituisce lockedFields per l'annuncio, e ogni scrittura restituisce blockedFieldsper ciò che ha toccato la tua richiesta. L'intero contratto — quali sezioni vengono inviate, cosa significa ogni codice di errore, com'è una pubblicazione parziale — è nel contratto di pubblicazione di Airbnb.

Oltre alla pubblicazione, la superficie di contenuti granulare è reale e utile: foto (caricare, riordinare, scegliere la copertina), stanze e letti, servizi, descrizioni per lingua, licenze e codici identificativi, avvisi di sicurezza per gli ospiti e la guida all'arrivo.

Messaggi, prenotazioni, recensioni e modifiche

• Messaggistica: leggere thread e messaggi, inviare, modificare, reagire, segnare come letto. Disponibile nel livello di messaggistica oltre che nell'accesso completo, ed è ciò che rende possibile un prodotto di comunicazione con gli ospiti accanto a un PMS già in uso. Messaggi con gli ospiti.
• Prenotazioni: elencare e leggere, con azioni su un codice di prenotazione. Prenotazioni.
• Modifiche: Airbnb è l'unico grande canale con un vero flusso di modifiche via API: creare una modifica, leggerla, accettarla, rifiutarla o annullarla. I cambi di date e di prezzo su una prenotazione Airbnb passano da lì e non da una modifica diretta. Modifiche.
• Recensioni: elencare, rispondere e modificare una risposta. Recensioni.
• Offerte speciali e pre-approvazioni: creare e ritirare, ed è così che rispondi a una richiesta con un prezzo. Offerte speciali.
• Transazioni: pagamenti e dati finanziari, lettura e aggiornamento. Transazioni.

Per vedere canale per canale cosa è supportato, parziale o non supportato, la matrice delle funzionalità è la versione onesta, e segna come parziale ciò che è parziale.

Trappole che costano giorni a chi integra

Ognuna di queste ci è costata tempo in produzione. Sono in ordine di quando tendono a colpire.

Gli id a 19 cifre diventano in silenzio l'account sbagliato

Gli id moderni di host e annunci Airbnb hanno 19 cifre, oltre 2⁵³, il più grande intero che JavaScript rappresenta con esattezza. Oltre quel valore i double sono distanziati di 256, quindi JSON.parseaggancia il valore a un id vicino, dall'aspetto del tutto valido:

JSON.parse('{"user_id":1693389202618766851}').user_id
// → 1693389202618766800   ← a different account

Le richieste continuano ad autenticarsi, perché l'autenticazione è il bearer token. Ma ogni chiamata basata su quell'id — elenco degli annunci, prenotazioni, disponibilità, messaggi — chiede di un account che non esiste, e Airbnb risponde con un risultato vuoto invece di un errore. Sei host di cinque clienti sono rimasti così da noi, con tutti gli health check verdi e senza mai importare nulla.

Leggi l'id dal testo grezzo della risposta prima che qualcosa lo converta, tienilo come stringa in tutto lo stack e confrontalo come testo nel database. Repull restituisce gli id Airbnb come stringhe ovunque proprio per questo; vedi ID e ID esterni.

Un 200 che non ha applicato nulla

Spiegato sopra. La regola da programmare: il successo è un blockedFields vuoto, non un 2xx.

Un account sano con annunci non scrivibili

Anche questo spiegato sopra. Modella lo stato di sincronizzazione per annuncio, non per account, o la tua dashboard dirà collegato mentre tre annunci si disallineano in silenzio.

Scoprire l'esclusività durante una demo con un cliente

Scopri quale strumento usa il tuo potenziale cliente prima di progettare il flusso di consenso. Chiedere la gestione delle proprietà quando l'host l'ha già concessa altrove significa una connessione fallita davanti al cliente, e la soluzione è un cambio di prodotto, non un nuovo tentativo.

Token, limiti di utilizzo e le parti che non finiscono mai

I token di accesso scadono e si rinnovano, gli host revocano, gli annunci vengono aggiunti e rimossi, Airbnb applica limiti di utilizzo e la forma dell'API cambia. Un'integrazione con Airbnb non è un progetto con una data di fine; è un servizio che ora gestisci tu. Metti a budget il monitoraggio, gli avvisi di ricollegamento e la reperibilità, perché sono la maggior parte del costo nel tempo.

Cosa serve per costruirlo da solo

Onestamente, in ordine:

1. L'approvazione come partner. Da settimane a mesi, con una possibilità reale di un no. Finché non arriva puoi sviluppare solo sulla documentazione, e non puoi promettere una data a nessun cliente.
2. Il ciclo di vita di OAuth e della connessione.Consenso, token, rinnovo, livelli di ambito, revoca, richieste di nuova autorizzazione e un'interfaccia che spieghi un ambito esclusivo a un host non tecnico.
3. La superficie in sé. Annunci, foto, stanze, servizi, descrizioni, impostazioni, calendario, prezzi, messaggi, prenotazioni, recensioni, offerte, modifiche e transazioni, ognuno con la sua forma, il suo comportamento in caso di fallimento parziale e la sua normalizzazione nel modello che il tuo prodotto usa davvero.
4. Lavoro di correttezza invisibile finché non lo è più. Id come stringhe, campi bloccati, stato di sincronizzazione per annuncio, sottotipi di blocco, risultati di pubblicazione per sezione.
5. Rotture continue. Cambiamenti a monte, funzioni dismesse, nuovi limiti di utilizzo, host che revocano, annunci che spariscono. Non arriva mai a zero.

È una cosa del tutto ragionevole da costruire se la connettività con Airbnb èil tuo prodotto. È un cattivo uso dell'anno di un piccolo team se Airbnb è solo un input di qualcos'altro che stai costruendo, e peggiora quando arriva il secondo canale, perché Booking.com non condivide quasi nessuna di queste premesse. La guida all'API di Booking.com è il confronto.

Dove si inserisce Repull

Repull è un'unica API REST e un'unica chiave per Airbnb, Booking.com, Vrbo, Plum Guide e i sistemi di gestione delle proprietà che gli host usano già. Le relazioni con i partner le teniamo noi; i tuoi utenti si collegano da soli tramite un flusso ospitato con il tuo marchio; tu non gestisci mai le loro credenziali.

• Un flusso di connessione per canale. POST /v1/connect/{provider} crea una sessione ospitata e ti restituisce una connessione. Connect.
• Una scrittura di calendario per tutti i canali. PUT /v1/availability/{propertyId} invia prezzo e disponibilità a ogni canale a cui è collegata una proprietà; le rotte per canale servono per le impostazioni che esistono su un solo canale.
• I fallimenti vengono mostrati, non nascosti. Campi bloccati, stato di sincronizzazione per annuncio e risultati di pubblicazione per sezione tornano come dati che puoi mostrare a un utente, perché fingere che una scrittura sia andata a buon fine è peggio che dire che non lo è.
• Webhook con cronologia delle consegne e reinvio. Webhook.

Comincia dalla guida rapida, oppure leggi la panoramica dei canali per la forma della superficie per canale. Se sei una piattaforma che integra tutto questo per i propri clienti e non per sé, la guida per le piattaforme copre quel modello domanda per domanda.

Se le proprietà che stai integrando sono già in un sistema di gestione delle proprietà, quello è un secondo problema, separato: un PMS ti dà la sua versione di una prenotazione, non l'API del canale. Le guide di Guesty, Hostaway, Hospitable, Lodgify e OwnerRez spiegano cosa espone ciascuno, e la matrice di coperturali ha tutti. Un'unica chiave copre insieme una connessione a un PMS e una connessione diretta a un canale.

Domande frequenti