Przewodnik integracji

API Airbnb: jak działa dostęp i co naprawdę pozwala zrobić

Napisany dla programisty albo technicznego foundera, którego poproszono, żeby „po prostu podłączył Airbnb”. Wyjaśnia, jak przyznawany jest dostęp partnerski, co API może, a czego nie może zmienić, i jakie konkretne błędy sprawiają, że integracja z Airbnb wygląda na zdrową, nic nie robiąc. Każde stwierdzenie pochodzi z prowadzenia tej integracji na produkcji.

Czym jest API Airbnb

Nie ma jednego publicznego „API Airbnb”. Istnieje API dla partnerów: interfejs REST, który Airbnb otwiera dla zatwierdzonych firm tworzących oprogramowanie, żeby ich klienci – gospodarze i zarządcy najmu – mogli prowadzić oferty poza airbnb.com. Nie jest dostępne dla każdego z kartą kredytową i nie ma sandboxa, do którego można się zapisać we wtorek po południu.

Sam interfejs jest szeroki. Połączenie z pełną autoryzacją może czytać i zapisywać treść oferty, zdjęcia, pokoje i łóżka, udogodnienia, kalendarz, cenę za noc, ustawienia rezerwacji, wiadomości od gości, rezerwacje, opinie, oferty specjalne, zmiany rezerwacji i transakcje wypłat. Ograniczenia prawie nigdy nie brzmią „ten endpoint nie istnieje”. Chodzi o to, kto co autoryzował i dla której oferty.

Jak uzyskać dostęp do API Airbnb?

Zanim twój pierwszy zapis się powiedzie, muszą zostać spełnione trzy warunki, a przyznają je trzy różne strony.

1. Airbnb zatwierdza twoją firmę jako partnera software. Składasz zgłoszenie, opisujesz produkt, który budujesz, i jesteś oceniany w ramach kategorii produktu: oprogramowanie do zarządzania obiektami, narzędzie do wiadomości, narzędzie do wyceny. Zatwierdzenie daje klienta OAuth (client id i secret) ograniczonego do tej kategorii. To biznesowa i formalna weryfikacja twojej firmy, a nie rejestracja dewelopera, i trwa od tygodni do miesięcy.
2. Każdy gospodarz autoryzuje twoją aplikację. Zatwierdzenie daje ci prawo do pytania, nie daje danych. Każdy gospodarz przechodzi przez ekran zgody OAuth, wybiera, czym twoja aplikacja może zarządzać, i przyznaje ci tokeny do swojego konta. Jeden gospodarz, jedna autoryzacja.
3. Każda oferta zostaje otwarta dla API. Ten krok zaskakuje wszystkich, więc ma poniżej osobną sekcję. Autoryzacja konta nie autoryzuje ofert, które się w nim znajdują.

Po stronie Repull cały ten proces to jedna hostowana sesja: twój serwer ją tworzy, przekierowujesz gospodarza i dostajesz z powrotem połączenie. Szczegóły, w tym parametry przekierowania, są w przewodniku po łączeniu 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" }'

O jaki zakres powinna prosić twoja aplikacja?

Ekran zgody to nie jedno „tak”. Gospodarz przyznaje poziom, a poziom, o który prosisz, decyduje zarówno o tym, co możesz robić, jak i o tym, czy połączenie w ogóle jest możliwe.

• Zarządzanie obiektami (pełny dostęp) – odczyt oraz zapis ofert, kalendarza i cen. To, czego potrzebuje PMS albo channel manager.
• Wiadomości – odczyt wszystkiego plus wysyłanie wiadomości do gości. Bez zarządzania ofertami, kalendarzem czy cenami.
• Tylko odczyt – oferty, rezerwacje, kalendarze, wiadomości i opinie. Właściwy poziom dla analityki, raportowania i BI.

Węższe poziomy lepiej też konwertują, bo ekran zgody pokazuje mniej uprawnień i mniej niepokojących. W Łączeniu Airbnb zobaczysz, jak ustalić poziom dla sesji albo pozwolić gospodarzowi wybrać.

Dlaczego połączone konto wciąż odrzuca każdy zapis

Airbnb autoryzuje synchronizację API oferta po ofercie, a nie konto po koncie. Każda oferta ma własną kategorię synchronizacji. Oferta z kategorią none jest zamknięta dla API i Airbnb odrzuca każdy zapis do niej, niezależnie od stanu konta.

Kategorie, które mają znaczenie:

• sync_all – treść, stawki i dostępność są zarządzane przez API.
• sync_rates_and_availability – zapisy kalendarza i cen działają; treść oferty zostaje w rękach gospodarza.
• none – każdy zapis jest odrzucany.

Czy mogę zmieniać ceny i dostępność przez API Airbnb?

Tak – w ofercie otwartej dla API i przy uprawnieniu do zarządzania obiektami. To ta część Airbnb, która zachowuje się tak, jak byś chciał: zapisy na konkretne daty, trafiające do kalendarza oferty i widoczne w ofercie.

Cenę za noc, otwarcie lub zamknięcie, minimalną i maksymalną liczbę nocy oraz zakazy przyjazdu i wyjazdu można zapisywać na każdą datę, razem z regułami dostępności na poziomie oferty, takimi jak domyślna minimalna liczba nocy, wyprzedzenie rezerwacji i dni przerwy między pobytami.

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

Wszystkie parametry są w Wysyłaniu dostępności do Airbnb i Aktualizacji cen w Airbnb. Jeśli chcesz, żeby jeden zapis trafił naraz do wszystkich podłączonych kanałów, a nie tylko do Airbnb, służy do tego PUT /v1/availability/{propertyId} – zobacz Aktualizację cen.

Czy mogę zmieniać treść oferty?

Częściowo – i właśnie tu integracja z Airbnb najczęściej po cichu zawodzi. Dwie zasady wyjaśniają prawie wszystko.

Publikacja to nie jedno wywołanie

Wysłanie treści oferty do Airbnb to nawet osiem niezależnych wywołań – szczegóły, opis, udogodnienia, pokoje, zasady, zdjęcia, ceny, zadania przy wymeldowaniu – i każde może się nie udać samo. Częściowa publikacja to normalny wynik i nie ma wycofania: sekcje, które przeszły, zostają zastosowane. Każdy model stanu, który traktuje publikację jako jedną wartość logiczną, w ciągu tygodnia będzie błędny. Raportuj per sekcja.

200 nie dowodzi, że zmiana została zastosowana

W ugruntowanej ofercie Airbnb traktuje część treści jako zarządzaną przez gospodarza i nie przyjmuje jej zmian przez żadne API. Nie odpowiada błędem. Żądanie zwraca 200, odpowiedź wymienia zablokowane atrybuty i nic dla nich nie zostaje zastosowane. Najczęściej blokowane: tytuł, podsumowanie i opis przestrzeni, kategoria typu obiektu, opcja zameldowania, pola adresu i pojedyncze udogodnienia.

Odczytaj zestaw zablokowanych pól z góry, zamiast odkrywać go przez porównywanie. GET /v1/channels/airbnb/listings/{id}/details zwraca lockedFields dla oferty, a każdy zapis zwraca blockedFields dla tego, w co trafiło twoje żądanie. Pełny kontrakt – które sekcje są wysyłane, co oznacza każdy kod błędu, jak wygląda częściowa publikacja – jest w kontrakcie publikacji Airbnb.

Poza publikacją szczegółowy interfejs treści jest prawdziwy i przydatny: zdjęcia (wgrywanie, kolejność, zdjęcie główne), pokoje i łóżka, udogodnienia, opisy w różnych językach, numery rejestracyjne, informacje o bezpieczeństwie dla gości i przewodnik po zameldowaniu.

Wiadomości, rezerwacje, opinie i zmiany

• Wiadomości – czytanie wątków i wiadomości, wysyłanie, edycja, reakcje, oznaczanie jako przeczytane. Dostępne na poziomie wiadomości oraz przy pełnym dostępie – i to właśnie umożliwia produkt do komunikacji z gośćmi obok istniejącego PMS. Wiadomości od gości.
• Rezerwacje – lista i odczyt, z akcjami na kodzie rezerwacji. Rezerwacje.
• Zmiany rezerwacji – Airbnb to jedyny duży kanał z prawdziwym procesem zmian przez API: utworzenie zmiany, odczyt, akceptacja, odrzucenie lub anulowanie. Zmiany dat i ceny w rezerwacji Airbnb idą tą drogą, a nie przez bezpośrednią edycję. Zmiany rezerwacji.
• Opinie – lista, odpowiedź i edycja odpowiedzi. Opinie.
• Oferty specjalne i wstępne zatwierdzenia – tworzenie i wycofywanie; tak odpowiadasz na zapytanie ceną. Oferty specjalne.
• Transakcje – wypłaty i dane finansowe, odczyt i odświeżanie. Transakcje.

Żeby zobaczyć kanał po kanale, co jest obsługiwane, obsługiwane częściowo albo nieobsługiwane, macierz możliwości to uczciwa wersja – i oznacza częściowe jako częściowe.

Pułapki, które kosztują dni pracy

Każda z nich kosztowała nas czas na produkcji. Są w kolejności, w jakiej zwykle dają o sobie znać.

19-cyfrowe identyfikatory po cichu stają się złym kontem

Nowe identyfikatory gospodarzy i ofert Airbnb mają 19 cyfr, ponad 2⁵³ – największą liczbę całkowitą, którą JavaScript przedstawia dokładnie. Powyżej tej wartości liczby double są rozmieszczone co 256, więc JSON.parse dociąga wartość do sąsiedniego, w pełni poprawnie wyglądającego identyfikatora:

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

Żądania nadal się uwierzytelniają, bo uwierzytelnienie to bearer token. Ale każde wywołanie z tym identyfikatorem – lista ofert, rezerwacje, dostępność, wiadomości – pyta o konto, które nie istnieje, a Airbnb odpowiada pustym wynikiem zamiast błędem. Sześciu gospodarzy od pięciu klientów tkwiło u nas w takim stanie, z zielonymi health checkami i bez żadnego importu.

Odczytuj identyfikator z surowego tekstu odpowiedzi, zanim cokolwiek go sparsuje, trzymaj go jako tekst w całym stacku i porównuj jako tekst w bazie danych. Repull z tego powodu wszędzie zwraca identyfikatory Airbnb jako tekst; zobacz Identyfikatory i identyfikatory zewnętrzne.

200, które niczego nie zastosowało

Opisane wyżej. Zasada do zakodowania: sukces to puste blockedFields, a nie 2xx.

Zdrowe konto z ofertami, do których nie da się zapisać

Również opisane wyżej. Modeluj stan synchronizacji per oferta, a nie per konto, bo inaczej twój panel pokaże „połączono”, podczas gdy trzy oferty po cichu się rozjadą.

Odkrycie wyłączności w trakcie demo u klienta

Dowiedz się, z jakiego narzędzia korzysta potencjalny klient, zanim zaprojektujesz proces zgody. Prośba o zarządzanie obiektami, gdy gospodarz przyznał je już gdzie indziej, to nieudane połączenie na oczach klienta, a rozwiązaniem jest zmiana produktu, nie ponowna próba.

Tokeny, limity zapytań i rzeczy, które nigdy się nie kończą

Tokeny dostępu wygasają i się odnawiają, gospodarze cofają zgody, oferty przybywają i znikają, Airbnb ogranicza liczbę zapytań, a kształt API się zmienia. Integracja z Airbnb to nie projekt z datą końca; to usługa, którą teraz prowadzisz. Zaplanuj budżet na monitoring, prośby o ponowne połączenie i dyżury, bo to one stanowią większość kosztów w całym okresie życia.

Co oznacza zbudowanie tego samemu

Szczerze i po kolei:

1. Zatwierdzenie partnera. Od tygodni do miesięcy, z realną szansą na odmowę. Do tego czasu możesz programować tylko na podstawie dokumentacji i nie możesz obiecać klientowi żadnej daty.
2. Cykl życia OAuth i połączenia. Zgoda, tokeny, odświeżanie, poziomy zakresu, cofanie zgód, prośby o ponowną autoryzację i interfejs, który wyjaśni wyłączny zakres nietechnicznemu gospodarzowi.
3. Sam interfejs. Oferty, zdjęcia, pokoje, udogodnienia, opisy, ustawienia, kalendarz, ceny, wiadomości, rezerwacje, opinie, oferty specjalne, zmiany rezerwacji i transakcje – każde z własnym kształtem, własnym zachowaniem przy częściowych błędach i własną normalizacją do modelu, z którego naprawdę korzysta twój produkt.
4. Praca nad poprawnością, niewidoczna, dopóki nie wyjdzie na jaw. Identyfikatory jako tekst, zablokowane pola, stan synchronizacji per oferta, podtypy blokad, wyniki publikacji per sekcja.
5. Ciągłe awarie. Zmiany po stronie Airbnb, wycofywane funkcje, nowe limity zapytań, gospodarze cofający zgody, oferty, które znikają. To nigdy nie spada do zera.

To całkiem rozsądna rzecz do zbudowania, jeśli łączność z Airbnb jest twoim produktem. To kiepski sposób na wykorzystanie roku pracy małego zespołu, jeśli Airbnb jest tylko jednym elementem czegoś innego, co budujesz – a robi się gorzej, gdy dochodzi drugi kanał, bo Booking.com nie dzieli prawie żadnego z tych założeń. Przewodnik po API Booking.com to porównanie.

Gdzie pasuje Repull

Repull to jedno API REST i jeden klucz dla Airbnb, Booking.com, Vrbo, Plum Guide i systemów do zarządzania obiektami, z których gospodarze już korzystają. To my utrzymujemy relacje z partnerami; twoi użytkownicy łączą się sami przez hostowany proces z twoją marką; nigdy nie dotykasz ich danych logowania.

• Jeden proces łączenia na kanał. POST /v1/connect/{provider} tworzy hostowaną sesję i oddaje ci połączenie. Connect.
• Jeden zapis kalendarza dla wszystkich kanałów. PUT /v1/availability/{propertyId} wysyła cenę i dostępność do każdego kanału, do którego podłączony jest obiekt; trasy dla poszczególnych kanałów są dla ustawień, które istnieją tylko w jednym kanale.
• Błędy są pokazywane, a nie wygładzane. Zablokowane pola, stan synchronizacji per oferta i wyniki publikacji per sekcja wracają jako dane, które możesz pokazać użytkownikowi, bo udawanie, że zapis się udał, jest gorsze niż powiedzenie, że się nie udał.
• Webhooki z historią dostarczeń i ponownym wysłaniem. Webhooki.

Zacznij od szybkiego startu albo przeczytaj przegląd kanałów, żeby zobaczyć kształt interfejsu per kanał. Jeśli jesteś platformą, która wbudowuje to dla własnych klientów, a nie integruje dla siebie, przewodnik dla platform omawia ten model pytanie po pytaniu.

Jeśli obiekty, które integrujesz, są już w systemie do zarządzania obiektami, to drugi, osobny problem: PMS daje ci własny obraz rezerwacji, a nie API kanału. Przewodniki po Guesty, Hostaway, Hospitable, Lodgify i OwnerRez opisują, co każdy z nich udostępnia, a macierz pokrycia zawiera je wszystkie. Jeden klucz obejmuje jednocześnie połączenie z PMS i bezpośrednie połączenie z kanałem.

Najczęstsze pytania