FeWocation · Entwickler

Booking Engine API

Apartments, freie Tage, Preise und Buchen einer Direktbuchungsseite — auf deiner eigenen Website, frei gestaltet.

Maschinenlesbar: openapi.json (OpenAPI 3.1)

  • Überblick
  • Schlüssel
  • Schnellstart mit Next.js
  • Endpunkte
  • Ablauf einer Buchung
  • Fehler
  • Grenzen
  • Testmodus
  • Fallstricke

Überblick

Jede Direktbuchungsseite im FeWocation-Dashboard hat eine Adresse (slug), z. B. seeblick für seeblick.booking-fewocation.de. Über die API holt deine Website die Inhalte dieser Seite, zeigt freie Tage und Preise und startet Buchungen. Bezahlt wird über Stripe auf dem Konto des Verwalters; danach legt FeWocation die Buchung an und schickt die Bestätigung.

Basis-Adresse: https://platform.fewocation.de/api/public/v1
Beispiel:      GET https://platform.fewocation.de/api/public/v1/sites/seeblick

Alle Antworten sind JSON. Beträge stehen in Cent und brutto (totalCents: 48900 = 489,00 €), Datumsangaben als YYYY-MM-DD in der Ortszeit des Apartments. Fehler haben immer die Form { "error": { "code", "message", "details"? } }. Die Version v1 bleibt stabil: Felder kommen dazu, keine fallen weg.

Schlüssel

Schlüssel legst du im Dashboard an: Direktbuchungsseiten → Seite öffnen → Karte „Eigene Website & API“. Ein Schlüssel gilt nur für seine Seite. Mitgeschickt wird er als Authorization: Bearer ….

fwpk_live_…Veröffentlichbar — für den Browser. Gilt nur von den eingetragenen Domains (Kopf Origin). Darf lesen, Preise rechnen und eine Buchung starten.
fwsk_live_…Geheim — nur auf dem Server der Website. Wird einmal angezeigt. Aus einem Browser geschickt, lehnt die API ihn ab (secret_key_in_browser).
…_test_…Testschlüssel: alles echt, nur Buchen wird simuliert (siehe Testmodus).

Inhalte (Seite, Apartment, Extras) sind auch ohne Schlüssel lesbar. Mit Schlüssel zählen die Grenzen aber je Schlüssel statt je IP — wichtig, wenn dein Server viele Seiten auf einmal baut.

Schnellstart mit Next.js

Bewährt hat sich: Inhalte auf dem Server mit dem geheimen Schlüssel holen (gut für Google, zwischengespeichert), Kalender, Preis und Buchen im Browser mit dem veröffentlichbaren Schlüssel.

# .env.local der Website
FEWOCATION_SITE=seeblick
FEWOCATION_SECRET_KEY=fwsk_live_…          # nur Server — nie NEXT_PUBLIC_
NEXT_PUBLIC_FEWOCATION_SITE=seeblick
NEXT_PUBLIC_FEWOCATION_KEY=fwpk_live_…     # darf in den Browser
// lib/fewocation.ts — nur auf dem Server
import "server-only";

const BASE = "https://platform.fewocation.de/api/public/v1";

async function call<T>(path: string, init: RequestInit = {}): Promise<T> {
  const res = await fetch(`${BASE}/sites/${process.env.FEWOCATION_SITE}${path}`, {
    ...init,
    headers: { ...init.headers, Authorization: `Bearer ${process.env.FEWOCATION_SECRET_KEY}` },
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body;
}

// Inhalte ändern sich selten — 5 Minuten zwischenspeichern.
export const getSite = () => call<{ site: Site }>("", { next: { revalidate: 300 } });
export const getListing = (id: string) => call<{ listing: Listing }>(`/listings/${id}`, { next: { revalidate: 300 } });

// Stand einer Buchung — nie zwischenspeichern.
export const getBooking = (id: string) => call<{ booking: BookingStatus }>(`/bookings/${id}`, { cache: "no-store" });
// Im Browser (Client-Komponente): Preis und Buchen mit dem veröffentlichbaren Schlüssel
const BASE = "https://platform.fewocation.de/api/public/v1/sites/" + process.env.NEXT_PUBLIC_FEWOCATION_SITE;
const headers = {
  "Content-Type": "application/json",
  Authorization: `Bearer ${process.env.NEXT_PUBLIC_FEWOCATION_KEY}`,
};

export async function quote(stay: { listingId: string; checkIn: string; checkOut: string; guests: number; childAges?: number[] }) {
  const res = await fetch(`${BASE}/quotes`, { method: "POST", headers, body: JSON.stringify(stay), cache: "no-store" });
  const body = await res.json();
  if (!res.ok) throw new Error(body.error.message);
  return body; // { available: true, quote, extraOffers, … } oder { available: false, problem }
}

// idempotencyKey EINMAL je Klick auf „Jetzt buchen“ erzeugen (crypto.randomUUID())
// und bei einem neuen Versuch derselben Buchung wiederverwenden.
export async function book(input: BookingInput, idempotencyKey: string) {
  const res = await fetch(`${BASE}/bookings`, {
    method: "POST",
    headers: { ...headers, "Idempotency-Key": idempotencyKey },
    body: JSON.stringify({
      ...input, // listingId, checkIn, checkOut, guests, childAges?, guest: { firstName, lastName, email, phone? }
      expectedTotalCents: input.shownTotalCents,
      successUrl: `${location.origin}/buchung/{bookingId}`,
    }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.error.message); // body.error.code zum Verzweigen
  window.location.href = body.checkoutUrl; // weiter zu Stripe
}
// app/buchung/[id]/page.tsx — Bestätigungsseite auf der eigenen Website
import { getBooking } from "@/lib/fewocation";

export default async function BuchungPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const { booking } = await getBooking(id);
  const pending = ["pending_payment", "paid", "booking"].includes(booking.status);
  return (
    <main>
      {/* Solange die Zahlung verbucht wird: alle paar Sekunden neu laden */}
      {pending && <meta httpEquiv="refresh" content="3" />}
      {booking.status === "booked" && <p>Gebucht! Dein Code: {booking.confirmationCode}</p>}
      {pending && <p>Deine Zahlung wird verbucht …</p>}
      {["failed", "refunded", "expired"].includes(booking.status) && <p>Das hat leider nicht geklappt.</p>}
    </main>
  );
}

Bilder kommen aus unserem Speicher (*.supabase.co). Für next/image diesen Host unter images.remotePatterns eintragen. coverUrl ist 480 px breit, die Galerie im Apartment enthält die Originale.

Endpunkte

EndpunktZugangLiefert
GET /sites/{slug}offenMarke, Farben, Schriften, Logo, Titelbilder, Texte („Über uns“ mit Bild, eigene Abschnitte), Kontakt, Rechtstexte und die Apartment-Kacheln.
GET /sites/{slug}/listings/{listingId}offenTexte, Eckdaten, Bilder, Ausstattung und Lage eines Apartments.
GET /sites/{slug}/listings/{listingId}/extrasoffenZusatzleistungen zum Dazubuchen (ohne Zeitraum) und ob Online-Buchung an ist.
GET /sites/{slug}/listings/{listingId}/calendar?from=&to=SchlüsselJe Tag: frei, Anreise/Abreise möglich, Mindestnächte, Preis der Nacht. Höchstens 400 Tage.
POST /sites/{slug}/quotesSchlüsselPreis-Aufstellung für einen Aufenthalt, mit Extras und Rabattcode — oder der Grund, warum nicht buchbar.
POST /sites/{slug}/searchSchlüsselAlle Apartments der Seite für einen Zeitraum: frei oder Grund, Gesamtpreis, Preis je Nacht.
POST /sites/{slug}/bookingsSchlüsselBuchung starten: Zeitraum 31 Minuten reserviert, Antwort mit der Adresse des Stripe Checkouts.
GET /sites/{slug}/bookings/{bookingId}SchlüsselStand der Buchung für die Bestätigungsseite, ohne Kontaktdaten des Gastes.

„Schlüssel“ heißt: veröffentlichbarer oder geheimer Schlüssel — oder die Anfrage kommt von der gehosteten Seite selbst. Alle Felder und Antworten im Einzelnen stehen in der OpenAPI-Beschreibung.

guests zählt alle Gäste, childAges nennt das Alter der Kinder am Anreisetag (zum Beispiel [8, 1] bei zwei Erwachsenen mit zwei Kindern: guests: 4). Davon hängt die Kurtaxe ab — ohne Alter rechnet sie für jeden Gast mit dem Erwachsenensatz. Fragt eure Buchungsmaske also nach Erwachsenen, Kindern und deren Alter.

POST /sites/seeblick/quotes
{ "listingId": "…", "checkIn": "2026-12-27", "checkOut": "2026-12-30", "guests": 4, "childAges": [8, 1],
  "extras": [{ "productId": "…", "quantity": 1 }], "discountCode": "WINTER10" }

→ { "available": true,
    "quote": { "nights": 3, "accommodationCents": 38700, "cleaningCents": 6500,
               "localTaxes": [{ "name": "Kurtaxe", "amountCents": 1200 }],
               "extrasCents": 2500, "totalCents": 48900, "includedVatCents": 3305, … },
    "extraOffers": [ … ], "extrasProblem": null, "discountCodeProblem": null }

Frühe Anreise und späte Abreise stehen in extraOffers mit kind: "stay_time", der Richtung (direction) und den Preisstufen, die zu diesem Aufenthalt möglich sind (tiers: Stunden, Uhrzeit, Preis). Gewählt wird genau eine Stufe: { "productId": "…", "stayTimeHours": 2 }. Nach der Zahlung gilt die Uhrzeit für die Buchung.

Ablauf einer Buchung

  1. Preis holen (POST …/quotes) und dem Gast zeigen — den Betrag als expectedTotalCents merken.
  2. Gast gibt Name und E-Mail ein, drückt „Jetzt buchen“ → POST …/bookings mit einem Idempotency-Key. Wir rechnen den Preis neu, prüfen den Zeitraum und reservieren ihn 31 Minuten.
  3. Weiter zur Antwort checkoutUrl (Stripe). Nach dem Bezahlen kommt der Gast auf successUrl zurück —{bookingId} ist dann ersetzt. Ohne Angabe gilt die Adresse aus dem Dashboard.
  4. Die Bestätigungsseite fragt GET …/bookings/{bookingId}, bis der Stand booked ist (meist wenige Sekunden). failed/refunded: Die Buchung kam nicht zustande, das Geld geht zurück.

Rücksprung-Adressen müssen auf einer eingetragenen Domain liegen — sonst bad_request. So lässt sich unser Checkout nicht als Umleitung auf fremde Seiten missbrauchen.

Fehler

CodeStatusBedeutung
bad_request400Eingabe fehlt oder ist ungültig — `message` sagt, welches Feld.
unauthorized401Schlüssel unbekannt, widerrufen oder im falschen Format.
forbidden403Ohne Schlüssel nur über die Adresse der Seite; Org-Schlüssel ohne Recht „Booking Engine“.
origin_not_allowed403Veröffentlichbarer Schlüssel von einer Domain, die nicht eingetragen ist.
secret_key_in_browser403Geheimer Schlüssel aus einem Browser geschickt. Schlüssel im Dashboard neu erzeugen.
booking_disabled403Online-Buchung der Seite ist aus oder die Zahlung nicht eingerichtet.
not_found404Seite, Apartment oder Buchung gibt es nicht — auch, wenn sie nicht zum Schlüssel gehört.
not_available409Zeitraum beim Buchen nicht (mehr) frei.
extras_unavailable409Gewählte Extras nicht (mehr) möglich.
discount_code_invalid409Rabattcode unbekannt oder für diesen Aufenthalt nicht gültig.
price_changed409Preis weicht von `expectedTotalCents` ab — neuer Preis in `details.totalCents`.
idempotency_key_reused409Der Idempotency-Key gehört zu einer abgeschlossenen oder abgelaufenen Buchung.
rate_limited429Zu viele Anfragen — `Retry-After` Sekunden warten.
too_many_open_bookings429Mehr als 3 offene Buchungen von diesem Besucher.
server_error500Bei uns ging etwas schief — kurz warten und erneut versuchen.

Nicht buchbar ist beim Preis kein Fehler: { "available": false, "problem": { "code", "message" } } mit einem Grund, den du dem Gast zeigen kannst (z. B. min_nights, closed_to_arrival).

Grenzen

Je MinuteBrowser (je Besucher-IP)Server (je geheimem Schlüssel)
Inhalte (Seite, Apartment, Extras)3003.000
Kalender1201.500
Preis1201.500
Suche60600
Buchung starten10120
Buchungsstatus1201.500

Jede Antwort nennt RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Sekunden). Über der Grenze kommt 429 rate_limited mit Retry-After. Braucht eine große Website dauerhaft mehr, erhöht der FeWocation-Support die Grenzen für alle Schlüssel des Verwalters — im Dashboard unter „Eigene Website & API“ → „Höheres Limit anfragen“. Zusätzlich hat jeder Besucher höchstens 3 offene Buchungen gleichzeitig.

Testmodus

Mit fwpk_test_… und fwsk_test_… funktionieren Inhalte, Kalender und Preise echt. Beim Buchen wird alles geprüft und gerechnet, aber nichts reserviert, nichts bezahlt und nichts beim Verwalter angelegt: checkoutUrl zeigt direkt auf deine successUrl, der Buchungsstatus ist booked mit test: true und einem Code TEST-…. Das geht auch, solange die Online-Buchung noch aus ist.

Fallstricke

  • Geheimer Schlüssel im Browser: In Next.js landet alles mit NEXT_PUBLIC_ im Browser. Den geheimen Schlüssel nie so benennen und Server-Code mit import "server-only" schützen.
  • Zwischenspeicher: Inhalte mit revalidate (z. B. 300 s) holen, Kalender, Preise und Buchungsstatus immer mit cache: "no-store" — sonst sieht der Gast alte freie Tage.
  • Datum um einen Tag daneben: new Date("2026-12-27") ist Mitternacht UTC. Datumsangaben als Text weiterreichen, nicht über Date umrechnen.
  • Preis nie selbst rechnen: Immer den Preis der API zeigen und expectedTotalCents mitschicken. Ändert er sich, kommt price_changed statt einer teureren Buchung.
  • Doppelte Buchungen: Einen Idempotency-Key je Buchungsversuch schicken — ein Doppelklick oder ein neuer Versuch ergibt dann dieselbe Buchung.
  • localhost: Zum Entwickeln im Dashboard „Zum Entwickeln auch localhost erlauben“ einschalten und vor dem Start wieder aus.
  • Datenschutz: Gastdaten gehen von deiner Website an FeWocation und Stripe. Beide gehören in die Datenschutzerklärung der Website.
  • Widerrufen wirkt nach bis zu einer Minute — so lange liegen geprüfte Schlüssel im Speicher unserer Server.

Fragen? Support im Dashboard