Repull dla platform: jak to działa, gdy Twoimi klientami są gospodarze

W praktyce platforma nigdy nie prosi użytkowników o podpisanie czegokolwiek z nami, nie pokazuje im naszej marki poza linkiem atrybucji na stronie Connect i nigdy nie przekazuje im poświadczeń. Twój użytkownik klika „połącz Airbnb” w Twoim produkcie, przechodzi przez hostowany proces z Twoim brandingiem i wraca. Jego konto jest teraz kolejnym połączonym kontem w Twoim workspace’ie.

// One workspace — yours — and one key for every user you onboard.
// 1. Mint a Connect session for this user, with your user id as state.
const res = await fetch('https://api.repull.dev/v1/connect', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.REPULL_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    redirectUrl: 'https://your-product.com/channels/done',
    state: userId,                      // comes back to you
    allowedProviders: ['airbnb', 'booking', 'vrbo-login'],
  }),
})
const { url } = await res.json()

// 2. Redirect the user. They connect on your branded Connect page and
//    come back with ?status=connected&state=<userId>. The
//    connect.session.completed webhook carries the same state and the
//    account they connected — store that account against the user.

• Wiele kont na kanał. Konta gospodarzy Airbnb, obiekty Booking.com i konta Vrbo wszystkich Twoich użytkowników żyją razem w Twoim workspace’ie. GET /v1/connect/{provider} wymienia je w accounts, a DELETE /v1/connect/{provider} przyjmuje accountId, żeby odłączyć konto jednego użytkownika bez ruszania pozostałych.
• Każde zdarzenie wskazuje swoje konto. Dostarczenia webhooków zawierają blok account — provider i externalAccountId, własne id dostawcy — oraz to samo konto w nagłówkach X-Repull-Account i X-Repull-Account-Id.
• Każdy rekord wskazuje swoje konto. GET /v1/reservations, /v1/conversations i /v1/reviews mają account w każdym wierszu, a /v1/properties ma accounts; wszystkie cztery przyjmują ?account=provider:externalAccountId, żeby odczytać dane jednego użytkownika.
• Jeden klucz na cały workspace. Klucz jest Twój i czyta wszystkie połączone konta. Zakresy ograniczają to, co może zrobić, a nie to, co może zobaczyć — dokładnie tego chcesz, gdy klucz żyje tylko na Twoich serwerach.

// Every webhook event names the connected account it came from.
app.post('/repull/webhooks', (req, res) => {
  const event = verify(req)                 // HMAC over the raw body
  const { provider, externalAccountId } = event.account ?? {}
  const userId = accountsToUsers.get(provider + ':' + externalAccountId)
  // …hand event.data to that user's inbox, calendar or CRM
  res.sendStatus(200)
})
// The provider's account id is also on the X-Repull-Account header,
// so you can shard before parsing the body.

Technicznie działają oba. Drugi jest naprawdę lepszy w jednym przypadku: przy kliencie na tyle dużym, że chce własnej relacji, własnej faktury i własnej ciągłości, gdyby kiedyś odszedł z Twojego produktu. Dla wszystkich pozostałych pierwszy oznacza mniej tarcia i mniej poświadczeń w Twojej bazie danych.

Konfigurujesz to raz w /dashboard/settings/connect i działa dla każdego kanału, który łączą Twoi użytkownicy. Sam proces ma ten sam kształt co Stripe Connect czy Plaid Link: Twój serwer tworzy sesję i odczytuje status, i nigdy nie dotyka poświadczeń kanału.

• Stronicuj kursorami. Ciężkie endpointy list są stronicowane po kluczu, więc koszt strony pozostaje stały bez względu na to, jak głęboko wejdziesz. ?offset= istnieje jako alias do krótkiego stronicowania i jest złym narzędziem do pełnego przejścia.
• Zapisuj wsadowo. PATCH /v1/availability/batch dla wartości kalendarza w wielu obiektach, POST /v1/listings/pricing/bulk dla decyzji cenowych i POST /v1/listings/status dla aktywacji. Jedno wywołanie, wiele obiektów, a częściowe błędy są raportowane per pozycja, zamiast wywracać cały wsad.
• Wysyłaj klucz idempotencji. Każdy zapis, który coś tworzy, przyjmuje Idempotency-Key. Przy wolumenie platformy timeout to nie przypadek brzegowy, tylko zwykły wtorek.
• Subskrybuj, nie odpytuj. Jeden endpoint POST /v1/webhooks dla Twojego workspace’u, z dziennikiem dostarczeń, ponowną wysyłką i endpointem testowym dla każdego typu zdarzenia, żebyś zbudował handler, zanim przyjdzie pierwsze prawdziwe zdarzenie.

# What is connected, for a support screen.
curl https://api.repull.dev/v1/connect \
  -H 'Authorization: Bearer sk_live_...'

# What this workspace has consumed, for your own metering.
curl https://api.repull.dev/v1/usage/summary \
  -H 'Authorization: Bearer sk_live_...'

Brak jakiejkolwiek liczby na tej stronie to nie nieśmiałość. Umowy z platformami różnią się o rząd wielkości w zależności od tego, ilu klientów końcowych za nimi stoi, z jakich kanałów korzystają i kto prowadzi wsparcie pierwszej linii, a opublikowana liczba dla jednego z tych przypadków aktywnie wprowadza w błąd w pozostałych. Przed jakąkolwiek rozmową możesz sam sprawdzić zużycie: endpointy usage pokazują, co workspace wykorzystał i do czego ma prawo, więc możesz modelować własną ekonomię na prawdziwych liczbach, a nie na naszych.

1. 1Zarejestruj się raz. Twój workspace i jego klucz API to jedyne poświadczenia Repull w Twoim systemie; trzymaj klucz na swoich serwerach.
2. 2Dla każdego użytkownika utwórz sesję Connect przez POST /v1/connect, ograniczając allowedProviders do kanałów obsługiwanych przez Twój produkt.
3. 3Przekaż swoje id użytkownika jako state. Po zakończeniu connect.session.completed zwraca ten state wraz z połączonym kontem: zapisz konto przy tym użytkowniku.
4. 4Zasubskrybuj endpoint webhook przez POST /v1/webhooks i kieruj każde zdarzenie według jego bloku account. Użyj endpointów testowych i ponownej wysyłki, żeby zbudować handler, zanim przyjdzie prawdziwe zdarzenie.
5. 5Czytaj przez endpointy międzykanałowe, gdzie tylko się da, żeby dodanie kanału później było zmianą konfiguracji, a nie przepisywaniem kodu.

Głębsza wersja techniczna — uwierzytelnianie, typy zdarzeń webhook, sandbox, pokrycie per kanał — jest w Q&A dla platform SaaS. Szczegóły dla każdego kanału znajdziesz w przewodnikach po Airbnb, Booking.com i Vrbo, a pełną referencję w dokumentacji.

Większość platform dziedziczy to, czego ich klienci już używają, a w praktyce oznacza to kilka systemów zarządzania obiektami, nie jeden. Każdy ma własny model uwierzytelniania, własne nazwy pól i własne limity: przewodniki po Guesty, Hostaway, Hospitable, Lodgify, OwnerRez, Smoobu i Beds24 wyjaśniają, co udostępnia każdy system i ile kosztuje Cię jego utrzymanie, a macierz pokrycia porównuje je obok siebie.