Ü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/seeblickAlle 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
| Endpunkt | Zugang | Liefert |
|---|---|---|
| GET /sites/{slug} | offen | Marke, Farben, Schriften, Logo, Titelbilder, Texte („Über uns“ mit Bild, eigene Abschnitte), Kontakt, Rechtstexte und die Apartment-Kacheln. |
| GET /sites/{slug}/listings/{listingId} | offen | Texte, Eckdaten, Bilder, Ausstattung und Lage eines Apartments. |
| GET /sites/{slug}/listings/{listingId}/extras | offen | Zusatzleistungen zum Dazubuchen (ohne Zeitraum) und ob Online-Buchung an ist. |
| GET /sites/{slug}/listings/{listingId}/calendar?from=&to= | Schlüssel | Je Tag: frei, Anreise/Abreise möglich, Mindestnächte, Preis der Nacht. Höchstens 400 Tage. |
| POST /sites/{slug}/quotes | Schlüssel | Preis-Aufstellung für einen Aufenthalt, mit Extras und Rabattcode — oder der Grund, warum nicht buchbar. |
| POST /sites/{slug}/search | Schlüssel | Alle Apartments der Seite für einen Zeitraum: frei oder Grund, Gesamtpreis, Preis je Nacht. |
| POST /sites/{slug}/bookings | Schlüssel | Buchung starten: Zeitraum 31 Minuten reserviert, Antwort mit der Adresse des Stripe Checkouts. |
| GET /sites/{slug}/bookings/{bookingId} | Schlüssel | Stand 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
- Preis holen (
POST …/quotes) und dem Gast zeigen — den Betrag alsexpectedTotalCentsmerken. - Gast gibt Name und E-Mail ein, drückt „Jetzt buchen“ →
POST …/bookingsmit einemIdempotency-Key. Wir rechnen den Preis neu, prüfen den Zeitraum und reservieren ihn 31 Minuten. - Weiter zur Antwort
checkoutUrl(Stripe). Nach dem Bezahlen kommt der Gast aufsuccessUrlzurück —{bookingId}ist dann ersetzt. Ohne Angabe gilt die Adresse aus dem Dashboard. - Die Bestätigungsseite fragt
GET …/bookings/{bookingId}, bis der Standbookedist (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
| Code | Status | Bedeutung |
|---|---|---|
| bad_request | 400 | Eingabe fehlt oder ist ungültig — `message` sagt, welches Feld. |
| unauthorized | 401 | Schlüssel unbekannt, widerrufen oder im falschen Format. |
| forbidden | 403 | Ohne Schlüssel nur über die Adresse der Seite; Org-Schlüssel ohne Recht „Booking Engine“. |
| origin_not_allowed | 403 | Veröffentlichbarer Schlüssel von einer Domain, die nicht eingetragen ist. |
| secret_key_in_browser | 403 | Geheimer Schlüssel aus einem Browser geschickt. Schlüssel im Dashboard neu erzeugen. |
| booking_disabled | 403 | Online-Buchung der Seite ist aus oder die Zahlung nicht eingerichtet. |
| not_found | 404 | Seite, Apartment oder Buchung gibt es nicht — auch, wenn sie nicht zum Schlüssel gehört. |
| not_available | 409 | Zeitraum beim Buchen nicht (mehr) frei. |
| extras_unavailable | 409 | Gewählte Extras nicht (mehr) möglich. |
| discount_code_invalid | 409 | Rabattcode unbekannt oder für diesen Aufenthalt nicht gültig. |
| price_changed | 409 | Preis weicht von `expectedTotalCents` ab — neuer Preis in `details.totalCents`. |
| idempotency_key_reused | 409 | Der Idempotency-Key gehört zu einer abgeschlossenen oder abgelaufenen Buchung. |
| rate_limited | 429 | Zu viele Anfragen — `Retry-After` Sekunden warten. |
| too_many_open_bookings | 429 | Mehr als 3 offene Buchungen von diesem Besucher. |
| server_error | 500 | Bei 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 Minute | Browser (je Besucher-IP) | Server (je geheimem Schlüssel) |
|---|---|---|
| Inhalte (Seite, Apartment, Extras) | 300 | 3.000 |
| Kalender | 120 | 1.500 |
| Preis | 120 | 1.500 |
| Suche | 60 | 600 |
| Buchung starten | 10 | 120 |
| Buchungsstatus | 120 | 1.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 mitimport "server-only"schützen. - Zwischenspeicher: Inhalte mit
revalidate(z. B. 300 s) holen, Kalender, Preise und Buchungsstatus immer mitcache: "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 überDateumrechnen. - Preis nie selbst rechnen: Immer den Preis der API zeigen und
expectedTotalCentsmitschicken. Ändert er sich, kommtprice_changedstatt einer teureren Buchung. - Doppelte Buchungen: Einen
Idempotency-Keyje 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