Integrationsleitfaden

Die Airbnb-API: wie der Zugang funktioniert und was sie dir wirklich erlaubt

Geschrieben für Entwickler und technische Gründer, die gebeten wurden, „mal eben Airbnb anzubinden“. Hier geht es darum, wie Partnerzugang vergeben wird, was die API ändern kann und was nicht, und um die konkreten Fehler, durch die eine Airbnb-Integration gesund aussieht, während sie nichts tut. Jede Aussage hier stammt aus dem Betrieb dieser Integration in Produktion.

Was die Airbnb-API ist

Es gibt nicht die eine öffentliche „Airbnb-API“. Was es gibt, ist eine Partner-API: eine REST-Schnittstelle, die Airbnb für freigegebene Softwareunternehmen öffnet, damit deren Kunden – Gastgeber und Ferienhausverwalter – ihre Inserate außerhalb von airbnb.com verwalten können. Sie steht nicht jedem mit einer Kreditkarte offen, und es gibt keine Sandbox, für die du dich an einem Dienstagnachmittag anmelden kannst.

Die Schnittstelle selbst ist breit. Eine voll autorisierte Verbindung kann Inseratsinhalte, Fotos, Zimmer und Betten, Ausstattung, Kalender, Preise pro Nacht, Buchungseinstellungen, Gästenachrichten, Buchungen, Bewertungen, Sonderangebote, Buchungsänderungen und Auszahlungstransaktionen lesen und schreiben. Die Grenzen sind fast nie „den Endpunkt gibt es nicht“. Es geht darum, wer was für welches Inserat autorisiert hat.

Wie bekomme ich Zugang zur Airbnb-API?

Vor deinem ersten erfolgreichen Schreibzugriff müssen drei Dinge erfüllt sein, und sie werden von drei verschiedenen Parteien gewährt.

1. Airbnb gibt dein Unternehmen als Softwarepartner frei. Du bewirbst dich, beschreibst das Produkt, das du baust, und wirst einer Produktkategorie zugeordnet: Property-Management-Software, Messaging-Tool, Pricing-Tool. Mit der Freigabe bekommst du einen OAuth-Client (Client-ID und Secret) für genau diese Kategorie. Das ist eine geschäftliche und Compliance-Prüfung deines Unternehmens, keine Entwickler-Registrierung, und sie dauert Wochen bis Monate.
2. Jeder Gastgeber autorisiert deine App. Die Freigabe gibt dir das Recht zu fragen, aber keine Daten. Jeder Gastgeber geht durch einen OAuth-Zustimmungsbildschirm, wählt, was deine App verwalten darf, und gibt dir Tokens für sein Konto. Ein Gastgeber, eine Autorisierung.
3. Jedes Inserat wird für die API geöffnet. Das ist der Schritt, der alle überrascht, deshalb hat er unten einen eigenen Abschnitt. Das Konto zu autorisieren autorisiert nicht die Inserate darin.

Bei Repull ist dieser ganze Ablauf eine einzige gehostete Session: Dein Server erstellt sie, du leitest den Gastgeber weiter und bekommst eine Verbindung zurück. Die Details, inklusive der Weiterleitungsparameter, stehen im Leitfaden zum Verbinden von 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" }'

Welchen Scope sollte deine App anfragen?

Der Zustimmungsbildschirm ist kein einfaches Ja. Der Gastgeber gewährt eine Stufe, und die Stufe, die du anfragst, entscheidet sowohl, was du tun kannst, als auch, ob die Verbindung überhaupt zustande kommt.

• Property Management (Vollzugriff) – Lesen plus Schreiben von Inseraten, Kalender und Preisen. Das, was ein PMS oder Channel-Manager braucht.
• Messaging – alles lesen, plus Nachrichten an Gäste senden. Keine Verwaltung von Inseraten, Kalender oder Preisen.
• Nur lesen – Inserate, Buchungen, Kalender, Nachrichten und Bewertungen. Die richtige Stufe für Analytics, Reporting und BI.

Engere Stufen konvertieren auch besser, weil der Zustimmungsbildschirm weniger und weniger beunruhigende Berechtigungen zeigt. Unter Airbnb verbinden siehst du, wie du eine Stufe pro Session festlegst oder den Gastgeber wählen lässt.

Warum ein verbundenes Konto trotzdem jeden Schreibzugriff ablehnt

Airbnb gibt die API-Synchronisierung Inserat für Inserat frei, nicht Konto für Konto. Jedes Inserat hat seine eigene Sync-Kategorie. Ein Inserat mit der Kategorie none ist für die API geschlossen, und Airbnb lehnt jeden Schreibzugriff darauf ab, egal wie es um das Konto steht.

Die Kategorien, auf die es ankommt:

• sync_all – Inhalte, Preise und Verfügbarkeit werden über die API verwaltet.
• sync_rates_and_availability – Schreibzugriffe auf Kalender und Preise funktionieren; die Inseratsinhalte bleiben beim Gastgeber.
• none – jeder Schreibzugriff wird abgelehnt.

Kann ich über die Airbnb-API Preise und Verfügbarkeit ändern?

Ja – bei einem Inserat, das für die API geöffnet ist, und mit einer Property-Management-Freigabe. Das ist der Teil von Airbnb, der sich so verhält, wie man es sich wünscht: Schreibzugriffe pro Datum, die im Kalender des Inserats landen und am Inserat sichtbar werden.

Preis pro Nacht, offen oder geschlossen, Mindest- und Höchstaufenthalt sowie Anreise- und Abreisesperren lassen sich pro Datum schreiben, dazu Verfügbarkeitsregeln auf Inseratsebene wie Standard-Mindestaufenthalt, Buchungsvorlauf und Pufferzeiten.

# 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"
    }]
  }'

Alle Parameter findest du unter Verfügbarkeit an Airbnb senden und Airbnb-Preise aktualisieren. Wenn ein einziger Schreibzugriff auf allen verbundenen Kanälen gleichzeitig landen soll statt nur bei Airbnb, ist das PUT /v1/availability/{propertyId} – siehe Preise aktualisieren.

Kann ich Inseratsinhalte ändern?

Teilweise – und genau hier scheitert eine Airbnb-Integration am häufigsten still. Zwei Regeln erklären fast alles.

Veröffentlichen ist kein einzelner Aufruf

Die Inhalte eines Inserats an Airbnb zu senden sind bis zu acht unabhängige Aufrufe – Details, Beschreibung, Ausstattung, Zimmer, Richtlinien, Fotos, Preise, Check-out-Aufgaben –, und jeder kann für sich scheitern. Eine teilweise Veröffentlichung ist das normale Ergebnis, und es gibt kein Rollback: Die Abschnitte, die durchgegangen sind, bleiben übernommen. Jedes Statusmodell, das das Veröffentlichen als einen einzigen Boolean behandelt, ist binnen einer Woche falsch. Melde es pro Abschnitt.

Ein 200 beweist nicht, dass die Änderung übernommen wurde

Bei einem etablierten Inserat behandelt Airbnb einige Inhalte als vom Gastgeber verwaltet und nimmt Änderungen daran über keine API an. Es antwortet nicht mit einem Fehler. Die Anfrage gibt 200 zurück, die Antwort nennt die gesperrten Attribute, und für sie wird nichts übernommen. Häufig gesperrt: der Titel, die Zusammenfassung und die Raumbeschreibung, die Unterkunftskategorie, die Check-in-Option, die Adressfelder und einzelne Ausstattungsmerkmale.

Lies die gesperrten Felder vorab aus, statt sie durch Vergleichen zu entdecken. GET /v1/channels/airbnb/listings/{id}/details liefert lockedFields für das Inserat, und jeder Schreibzugriff liefert blockedFields für das, was deine Anfrage getroffen hat. Den kompletten Vertrag – welche Abschnitte gesendet werden, was jeder Fehlercode bedeutet, wie eine teilweise Veröffentlichung aussieht – findest du im Airbnb-Veröffentlichungsvertrag.

Über das Veröffentlichen hinaus ist die feingliedrige Inhalts-Schnittstelle echt und nützlich: Fotos (hochladen, sortieren, Titelbild setzen), Zimmer und Betten, Ausstattung, Beschreibungen pro Sprache, Registrierungsnummern, Sicherheitshinweise für Gäste und der Check-in-Leitfaden.

Nachrichten, Buchungen, Bewertungen und Änderungen

• Messaging – Unterhaltungen und Nachrichten lesen, senden, bearbeiten, reagieren, als gelesen markieren. Verfügbar in der Messaging-Stufe wie im Vollzugriff, und genau das macht ein Produkt für Gästekommunikation neben einem bestehenden PMS möglich. Gästenachrichten.
• Buchungen – auflisten und lesen, mit Aktionen auf einen Buchungscode. Buchungen.
• Änderungen – Airbnb ist der einzige große Kanal mit einem echten Änderungsablauf über die API: eine Änderung anlegen, lesen, annehmen, ablehnen oder stornieren. Datums- und Preisänderungen an einer Airbnb-Buchung laufen darüber statt über eine direkte Bearbeitung. Änderungen.
• Bewertungen – auflisten, antworten und eine Antwort bearbeiten. Bewertungen.
• Sonderangebote und Vorab-Freigaben – anlegen und zurückziehen; so beantwortest du eine Anfrage mit einem Preis. Sonderangebote.
• Transaktionen – Auszahlungen und Finanzdaten, lesen und aktualisieren. Transaktionen.

Für eine Übersicht pro Kanal, was unterstützt, teilweise oder nicht unterstützt ist, ist die Funktionsmatrix die ehrliche Version – und sie markiert Teilweises als teilweise.

Fallen, die Integratoren Tage kosten

Jede davon hat uns Zeit in Produktion gekostet. Sie stehen in der Reihenfolge, in der sie meist zuschlagen.

19-stellige IDs werden still zum falschen Konto

Moderne Airbnb-IDs für Gastgeber und Inserate haben 19 Stellen, mehr als 2⁵³ – die größte Ganzzahl, die JavaScript exakt darstellt. Darüber liegen Doubles 256 auseinander, also rastet JSON.parse den Wert auf eine benachbarte, völlig gültig aussehende ID ein:

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

Die Anfragen authentifizieren sich weiterhin, denn Authentifizierung ist der Bearer-Token. Aber jeder Aufruf mit dieser ID – Inseratsliste, Buchungen, Verfügbarkeit, Nachrichten – fragt nach einem Konto, das nicht existiert, und Airbnb antwortet mit einem leeren Ergebnis statt mit einem Fehler. Sechs Gastgeber von fünf Kunden standen bei uns so da, alle Health-Checks grün, ohne dass je etwas importiert wurde.

Lies die ID aus dem rohen Antworttext, bevor irgendetwas sie parst, behalte sie in deinem ganzen Stack als String und vergleiche sie in der Datenbank als Text. Repull liefert Airbnb-IDs aus genau diesem Grund überall als Strings; siehe IDs und externe IDs.

Ein 200, das nichts übernommen hat

Oben beschrieben. Die Regel für deinen Code: Erfolg ist ein leeres blockedFields, nicht ein 2xx.

Ein gesundes Konto mit nicht beschreibbaren Inseraten

Ebenfalls oben beschrieben. Modelliere den Sync-Status pro Inserat, nicht pro Konto, sonst zeigt dein Dashboard „verbunden“, während drei Inserate still auseinanderlaufen.

Die Exklusivität während einer Kundendemo entdecken

Find heraus, welches Tool dein potenzieller Kunde nutzt, bevor du den Zustimmungsablauf entwirfst. Property Management anzufragen, wenn der Gastgeber es schon woanders vergeben hat, heißt: eine gescheiterte Verbindung vor dem Kunden – und die Lösung ist eine Produktänderung, kein Retry.

Tokens, Rate Limits und die Teile, die nie aufhören

Access-Tokens laufen ab und werden erneuert, Gastgeber widerrufen, Inserate kommen und gehen, Airbnb drosselt Anfragen, und die Form der API ändert sich. Eine Airbnb-Integration ist kein Projekt mit Enddatum; sie ist ein Service, den du jetzt betreibst. Plan das Monitoring, die Neuverbindungs-Hinweise und die Bereitschaft ein, denn sie machen den Großteil der Kosten über die Lebensdauer aus.

Was es heißt, das selbst zu bauen

Ehrlich und der Reihe nach:

1. Die Partnerfreigabe. Wochen bis Monate, mit einer echten Chance auf ein Nein. Bis sie da ist, kannst du nur gegen die Doku entwickeln und keinem Kunden einen Termin versprechen.
2. Der Lebenszyklus von OAuth und Verbindung. Zustimmung, Tokens, Erneuerung, Scope-Stufen, Widerruf, Aufforderungen zur Neuautorisierung und eine Oberfläche, die einem nicht technischen Gastgeber einen exklusiven Scope erklärt.
3. Die Schnittstelle selbst. Inserate, Fotos, Zimmer, Ausstattung, Beschreibungen, Einstellungen, Kalender, Preise, Nachrichten, Buchungen, Bewertungen, Angebote, Änderungen, Transaktionen – jeweils mit eigener Form, eigenem Verhalten bei Teilfehlern und eigener Normalisierung in das Modell, das dein Produkt tatsächlich nutzt.
4. Korrektheitsarbeit, die unsichtbar ist, bis sie es nicht mehr ist. IDs als Strings, gesperrte Felder, Sync-Status pro Inserat, Sperr-Subtypen, Ergebnisse pro Abschnitt beim Veröffentlichen.
5. Ständige Brüche. Änderungen auf Airbnb-Seite, Abkündigungen, neue Rate Limits, Gastgeber, die widerrufen, Inserate, die verschwinden. Das geht nie auf null.

Es ist absolut vernünftig, das zu bauen, wenn Airbnb-Konnektivität dein Produkt ist. Es ist eine schlechte Verwendung des Jahres eines kleinen Teams, wenn Airbnb nur ein Baustein von etwas anderem ist – und es wird schlimmer, wenn der zweite Kanal dazukommt, weil Booking.com fast keine dieser Annahmen teilt. Der Leitfaden zur Booking.com-API ist der Vergleich.

Wo Repull ins Spiel kommt

Repull ist eine REST-API mit einem Schlüssel für Airbnb, Booking.com, Vrbo, Plum Guide und die Property-Management-Systeme, die Gastgeber bereits nutzen. Wir halten die Partnerbeziehungen; deine Nutzer verbinden sich selbst über einen gehosteten Ablauf mit deinem Branding; ihre Zugangsdaten fasst du nie an.

• Ein Verbindungsablauf pro Kanal. POST /v1/connect/{provider} erstellt eine gehostete Session und gibt dir eine Verbindung zurück. Connect.
• Ein Kalender-Schreibzugriff für alle Kanäle. PUT /v1/availability/{propertyId} schickt Preis und Verfügbarkeit an jeden Kanal, mit dem eine Unterkunft verbunden ist; die Routen pro Kanal gibt es für Einstellungen, die nur auf einem Kanal existieren.
• Fehler werden gezeigt, nicht geglättet. Gesperrte Felder, Sync-Status pro Inserat und Ergebnisse pro Abschnitt kommen als Daten zurück, die du einem Nutzer zeigen kannst – denn so zu tun, als sei ein Schreibzugriff durchgegangen, ist schlimmer, als zu sagen, dass er es nicht ist.
• Webhooks mit Zustellverlauf und Replay. Webhooks.

Fang mit dem Quickstart an oder lies die Kanal-Übersicht für den Aufbau der Schnittstelle pro Kanal. Wenn du eine Plattform bist, die das für ihre eigenen Kunden einbaut statt für sich selbst, deckt der Leitfaden für Plattformen dieses Modell Frage für Frage ab.

Wenn die Unterkünfte, die du integrierst, schon in einem Property-Management-System liegen, ist das ein zweites, eigenes Problem: Ein PMS gibt dir seine Sicht auf eine Buchung, nicht die API des Kanals. Die Leitfäden zu Guesty, Hostaway, Hospitable, Lodgify und OwnerRez zeigen, was jedes davon bereitstellt, und die Abdeckungsmatrix hat sie alle. Ein Schlüssel deckt gleichzeitig eine PMS-Verbindung und eine direkte Kanalverbindung ab.

Häufige Fragen