Guida all'integrazione

L'API di Booking.com: come funziona l'accesso e cosa ti permette davvero di fare

Scritta per lo sviluppatore o il founder tecnico a cui hanno indicato le API di connettività di Booking.com. Spiega come funzionano la designazione come partner e il collegamento di ogni struttura, il modello di dati da cui dipende tutto il resto, e i due o tre comportamenti per cui un aggiornamento delle tariffe su Booking.com riesce sulla carta e non cambia nulla nella pratica.

Cos'è l'API di Booking.com

Le API di Booking.com sono pensate per i provider di connettività: i channel manager e i sistemi di gestione delle proprietà che tengono sincronizzati gli alloggi per conto di molte strutture insieme. Non sono API per consumatori, non c'è una superficie pubblica di ricerca o prenotazione per terzi e non c'è un portale per sviluppatori a cui iscriversi.

In pratica sono diverse superfici di prodotto sotto un'unica partnership: disponibilità e tariffe, prenotazioni, configurazione di strutture e camere, contenuti, messaggi, recensioni e addebiti. Si comportano in modo diverso tra loro, vengono concesse separatamente e parti della superficie più vecchia sono in XML e non in JSON. Se arrivi da Airbnb, quasi nessuna delle tue premesse vale ancora.

Come ottengo l'accesso all'API di Booking.com?

Tre livelli, concessi da tre parti diverse, proprio come con Airbnb ma con una forma diversa.

1. Booking.com designa la tua azienda come provider di connettività.Fai domanda, vieni valutato dal punto di vista commerciale e tecnico, e c'è un passaggio di certificazione per le superfici che intendi usare. È un rapporto a livello aziendale che si misura in mesi.
2. Ricevi le credenziali di un account macchina.A differenza dei token OAuth per host di Airbnb, un solo account macchina agisce per tutte le strutture collegate a te. Quella singola credenziale è il raggio d'impatto di tutto il tuo business, e cambia il modo in cui leggi gli errori: vedi la nota qui sotto.
3. Ogni struttura ti collega dalla propria Extranet.L'host accede all'Extranet di Booking.com, apre l'elenco dei provider di connettività, cerca il tuo provider per nome e clicca Collega. Finché non lo fa, il tuo account macchina non può vedere quella struttura. Gli servirà anche il suo Hotel ID numerico.

Con Repull la parte rivolta all'host è un'unica sessione ospitata con il tuo marchio: l'host completa il passaggio nell'Extranet e incolla il suo Hotel ID, e tu ricevi una connessione. La procedura è in Collegare Booking.com.

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

Strutture, camere e piani tariffari

Se hai capito questo, il resto di Booking.com torna. Se no, ogni endpoint sembra arbitrario.

Booking.com property   "hotel_id": 5432505        ← the building
└── room               "roomBookingId": 543250501 ← what a guest books
    └── rate plan      "rateId": 98765            ← the terms it sells on
        └── price at an occupancy                ← what you actually write

Una struttura è un edificio. Le camere sono ciò che prenotano gli ospiti. I piani tariffari sono le condizioni commerciali con cui si vende una camera, e un prezzo appartiene a una combinazione (camera, piano tariffario, data, occupazione), non a una notte. Una villa con una camera da letto è il caso semplice; un aparthotel con venti unità è un'unica struttura con venti camere, ed è la normalità, non un caso limite.

La stessa unità può anche comparire sotto più strutture Booking.com, di solito perché è stata ripubblicata nel tempo, e una camera non associata a uno dei tuoi annunci non appartiene a nulla: le sue prenotazioni non hanno dove finire. Associa le camere durante il flusso di collegamento, non dopo.

Posso aggiornare le tariffe tramite l'API di Booking.com?

Sì, ed è la superficie più usata di tutta la partnership. Scrivi un prezzo per una camera su un piano tariffario per un intervallo di date, eventualmente con restrizioni di soggiorno e di arrivo nella stessa chiamata.

curl -X PUT 'https://api.repull.dev/v1/channels/booking/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "rates",
    "property_id": "1234567",
    "updates": [{
      "roomId": "123456701",
      "rateId": "98765",
      "dateRange": { "start": "2026-11-04", "end": "2026-11-04" },
      "price": 210,
      "currency": "USD",
      "occupancy": 4
    }]
  }'

roomId e rateId arrivano da GET /v1/channels/booking/properties/{id}/rooms. Tutto il resto della richiesta — e ce n'è più di quanto pensi — è in Aggiornare i prezzi su Booking.com.

Perché il mio aggiornamento di prezzo su Booking.com non ha fatto nulla?

È la domanda che porta le persone su questa pagina, e ha due risposte indipendenti. Entrambe sembrano un successo.

L'occupazione fa parte della chiave, non è una preferenza

Booking.com non salva “il prezzo di questa notte”. Salva un prezzo per una notte per un certo numero di personesu un piano tariffario. Quindi l'occupazione che invii decide quale prezzo stai sovrascrivendo. Ogni importo parte con un'occupazione, che tu la indichi o no.

• Indica un'occupazione oltreil massimo prezzato dal piano e Booking.com accetta la richiesta e scarta l'importo senza dirlo. La notte mantiene il valore di prima — spesso 0.00 — e la conferma è identica, byte per byte, a quella di una scrittura riuscita.
• Indicane una inferiore e ricevi un 400. Il prezzo pubblicato non cambia.
• La capacità del tuo annuncio non è il dato che conta. Conta il numero che Booking.com ha per quel piano tariffario. Leggilo invece di dedurlo.

Repull ricava l'occupazione dai dati di Booking.com per la coppia (camera, piano tariffario) quando non la indichi, ti restituisce il valore usato e da dove viene, e rifiuta la scrittura con un 422 quando non riesce a determinarla. Un importo non viene mai inviato alla cieca.

La ricevuta non è una conferma

Booking.com di solito risponde a una scrittura delle tariffe con una ricevuta senza stato per data. Il corpo è letteralmente:

{"ok": ""}

Intervalli di date e la notte che perdi

Sotto, l'XML di disponibilità e tariffe riceve un intervallo la cui data to non viene scritta: è un limite esclusivo, come la data di check-out esclude l'ultima notte. La maggior parte dei calendari che avrai integrato prima tratta entrambi gli estremi come notti. Quindi la lettura naturale di “dal 1 al 7 agosto” è sette notti, ma nella richiesta sono sei, e la notte che perdi senza accorgertene è l'ultima di ogni intervallo che scrivi.

È una conversione di una riga e un bug di una settimana, perché ti costa solo l'ultima notte: il calendario sembra più o meno giusto, un controllo a campione passa, e il buco si vede come una prenotazione persa invece che come un errore.

L'inventario è una scrittura a parte

Dare un prezzo a una notte non la apre alla vendita, e aprirla non le dà un prezzo. Le camere in vendita e il blocco vendite sono un tipo di aggiornamento a sé; inviarli in un aggiornamento delle tariffe viene rifiutato invece di essere ignorato in silenzio.

# Close a night: zero rooms to sell, stop-sell on
curl -X PUT 'https://api.repull.dev/v1/channels/booking/availability' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "availability",
    "property_id": "1234567",
    "updates": [{
      "roomId": "123456701",
      "rateId": "98765",
      "dateRange": { "start": "2026-11-04", "end": "2026-11-04" },
      "availableRooms": 0,
      "closed": true
    }]
  }'

Dettagli in Inviare la disponibilità a Booking.com. Se preferisci scrivere un calendario una volta sola e farlo arrivare a tutti i canali collegati, quello è PUT /v1/availability/{propertyId}, con PATCH /v1/availability/batch per molte strutture insieme.

Restrizioni che esistono e altre che no

Soggiorno minimo e massimo (in base alla data di soggiorno e alla data di arrivo), divieto di arrivo e divieto di partenza esistono e si possono impostare per camera, piano tariffario e intervallo di date.

Diverse restrizioni che le persone si aspettano semplicemente non sono nella notifica che Booking.com accetta, tra cui una durata esatta del soggiorno all'arrivo e l'anticipo minimo o massimo di prenotazione. Il comportamento giusto è rifiutarle in modo esplicito. Una restrizione accettata e poi non inviata è l'unico errore che non puoi vedere in una risposta, quindi Repull risponde 422 indicando il campo invece di scartarlo. Vedi restriction_not_supported e Soggiorno minimo e restrizioni.

Prenotazioni, messaggi, recensioni e addebiti

• Prenotazioni: elencarle e confermarne la ricezione. La conferma non è una formalità facoltativa: le nuove prenotazioni restano in coda finché non le confermi, e un partner che non conferma mai continua a rileggere le stesse prenotazioni. Prenotazioni.
• Messaggi: elencare le conversazioni e inviare. Più limitata della superficie dei thread di Airbnb; niente modifica, niente reazioni, niente stato di lettura. Messaggi con gli ospiti.
• Recensioni: elencare e rispondere. Recensioni.
• Addebiti e tasse: lettura e scrittura. Addebiti e tasse.
• Configurazione e messa online: creare l'entità legale, verificare che sia tutto pronto, impostare contatti e regole e aprire una struttura alla vendita. Configurazione e messa online.
• Nessuna modifica.Booking.com non ha un equivalente del flusso di modifiche di Airbnb. I cambi di date e di prezzo su una prenotazione esistente non sono un'operazione dell'API.

La matrice delle funzionalità mette Airbnb e Booking.com fianco a fianco, e segna come parziale ciò che è parziale invece di arrotondarlo per eccesso.

Perché la Content API restituisce 403?

Perché i contenuti sono una superficie di prodotto a sé, con un proprio permesso e un proprio percorso base, separata da disponibilità, tariffe e prenotazioni. Una struttura può essere completamente attiva — riceve prenotazioni e accetta ogni scrittura di tariffe e disponibilità — mentre ogni chiamata sui contenuti di quella stessa struttura risponde 403.

Quando succede, l'istinto è sospettare del token, poi dell'id della struttura, poi dei permessi dell'host nell'Extranet. Di solito non è nessuna di queste cose. La funzionalità non ti è stata concessa per quella superficie, e ricollegarsi non cambia nulla. Verifica quali funzionalità include davvero la tua partnership prima di mettere la gestione di foto o descrizioni in una release.

I contenuti, dove sono disponibili, coprono foto, descrizioni, servizi, strutture e regole, a livello di struttura o di camera, e Booking.com revisiona le modifiche ai testi prima di pubblicarle, quindi una scrittura è l'inizio di un processo, non la fine. Contenuti e foto.

Cosa serve per costruirlo da solo

1. Designazione come partner e certificazione. Mesi, con revisione commerciale e una certificazione tecnica per ogni superficie. Non puoi promettere una data a un cliente.
2. Un modello di sicurezza con credenziale condivisa. Un solo account macchina per tutte le strutture che servi. Rotazione, conservazione e un classificatore di errori abbastanza attento da evitare che un 401 globale durante un disservizio scolleghi in massa i tuoi clienti.
3. Il modello e la mappatura. Dalle strutture alle camere, ai piani tariffari e ai tuoi annunci, incluse strutture con più camere, unità ripubblicate e camere non associate le cui prenotazioni non hanno dove andare.
4. Verifica delle scritture.Dato che la ricevuta non prova nulla, un'integrazione corretta rilegge e riconcilia. È una chiamata in più, un tempo di attesa e una macchina a stati, sul percorso più caldo che hai.
5. Convenzioni che non tornano.Limiti di data esclusivi, prezzi legati all'occupazione, inventario separato dalle tariffe, restrizioni che non esistono, XML dove ti aspettavi JSON.
6. Rotture continue. Come per ogni API per partner: non arriva mai a zero.

In sintesi, onestamente: Booking.com è un'integrazione più pesante di Airbnb e non ne condivide quasi nessuna premessa — diverso modello di autenticazione, diverso modello di dati, diversa semantica delle date, diversa definizione di scrittura riuscita. I team che hanno appena finito Airbnb lo sottovalutano sempre. La guida all'API di Airbnb è il confronto.

Dove si inserisce Repull

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

• Un unico flusso di collegamento ospitato. POST /v1/connect/{provider}, con l'associazione delle camere già inclusa. Connect.
• Scritture che ti dicono la verità. Verifica tramite rilettura sulle tariffe, occupazione determinata e restituita, restrizioni non supportate rifiutate invece che scartate, intervalli di date inclusivi a entrambi gli estremi.
• Una scrittura di calendario per tutti i canali. PUT /v1/availability/{propertyId} invia prezzo e disponibilità a ogni canale a cui è collegata una struttura.
• Webhook con cronologia delle consegne e reinvio, invece dell'idraulica delle notifiche di ogni canale. Webhook.

Comincia dalla guida rapida, oppure leggi la panoramica dei canali. 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 strutture 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