FeWocation · Entwickler

Open API

Apartments, Buchungen, Kalender, Raten, Aktionen, Rechnungen und Eigentümer einer ganzen Organisation — für Revenue Management, Buchhaltung und andere angebundene Systeme.

Maschinenlesbar: openapi.json (OpenAPI 3.1) · Eigene Website bauen? Booking Engine API

  • Überblick
  • Schlüssel und Rechte
  • Schnellstart
  • Endpunkte
  • Seitenweise lesen
  • Buchungen abgleichen
  • Beträge
  • Kalender
  • Preis anfragen
  • Kalender schreiben
  • Buchungen anlegen
  • Webhooks
  • Apartments verwalten
  • Texte, Ausstattung, Räume, Bilder
  • Buchungsregeln und Preise
  • Auswahllisten, Standorte, Anlagen
  • Raten
  • Stornobedingungen
  • Raten und Stornobedingungen ändern
  • Kanäle, Verpflegung und Einordnung
  • Raten aus einem angebundenen PMS
  • Aktionen
  • Aktionsarten
  • Aktionen anlegen und ändern
  • Stand bei den Portalen
  • Rechnungen lesen
  • Rechnungen anlegen, senden, stornieren
  • Zahlungserinnerung
  • Gutschriften
  • Eigentümer
  • Kontakte eines Eigentümers
  • Abrechnung je Eigentümer
  • Provisionspläne
  • Aufenthalte des Eigentümers
  • Eigentümerportal
  • Werkzeuge (MCP)
  • Fehler
  • Grenzen
  • Was noch kommt

Überblick

Die Open API liest die Kernobjekte einer Organisation: ihre Apartments, ihre Buchungen und den Kalender mit Preisen, dazu Raten mit Stornobedingungen, Aktionen, Rechnungen, Gutschriften und Eigentümer. Mit eigenen Rechten schreibt sie auch: Preise, Mindestnächte und Sperren im Kalender, Buchungen anlegen und stornieren, Apartments verwalten, Raten und Aktionen pflegen, Rechnungen und Gutschriften ausstellen, Eigentümer pflegen. Sie ist für Systeme gedacht, die von einem Server aus arbeiten.

Basis-Adresse: https://platform.fewocation.de/api/public/v1

Alle Antworten sind JSON mit Feldnamen in camelCase. Ein einzelnes Objekt steht unter data, eine Liste unter data mit nextCursor daneben. Datumsangaben sind YYYY-MM-DD in der Ortszeit des Apartments, Zeitpunkte ISO 8601 mit Zeitzone, Beträge ganze Cent. Die Version v1 bleibt stabil: Felder kommen dazu, keine fallen weg.

Schlüssel und Rechte

Den Schlüssel legt der Verwalter im Dashboard an: Integrationen → API-Keys. Er beginnt mit fw_, wird einmal angezeigt und gilt für die ganze Organisation. Mitgeschickt wird er als Authorization: Bearer fw_…. Der Schlüssel gehört nur auf einen Server: Eine Anfrage aus einem Browser (Kopf Origin) lehnt die API ab.

Ein neuer Schlüssel trägt keines dieser Rechte. Der Verwalter schaltet sie im Rechte-Fenster des Schlüssels frei:

listings:readApartments mit Texten, Bildern und Ausstattung, dazu der Kalender.
reservations:readBuchungen mit Zeitraum, Stand, Kanal und Gästezahl — ohne Gastdaten.
guests:readZusätzlich das Objekt guest an jeder Buchung: Name, E-Mail, Telefon, Anschrift, Sprache.
finances:readZusätzlich das Objekt amounts an jeder Buchung: Gastpreis, Übernachtung, Reinigung, Gebühren, Steuern, Provision des Portals.
calendar:writePreise, Mindestnächte, An- und Abreisesperren setzen und Zeiträume sperren. Die Änderungen gehen an die Buchungsportale.
reservations:writeBuchungen ohne Zahlung anlegen und stornieren — mit allen Folgen einer Buchung von Hand (Reinigung, Nachrichten an den Gast).
webhooksWebhooks anlegen und verwalten: neue, geänderte und stornierte Buchungen kommen sofort an deine Adresse.
listings:readApartments mit Texten in allen Sprachen, Ausstattung, Räumen, Bildern, Buchungsregeln, Preisen, Mehrwertsteuer und Hausregeln, dazu der Kalender, Standorte und Anlagen.
listings:writeApartments anlegen und ihre Stammdaten, Texte, Ausstattung, Räume, Bilder, Buchungsregeln, Preise und Mehrwertsteuer ändern. Die Änderungen gehen an die Buchungsportale.
rates:readEigene Raten mit Preis-Abweichung, Verpflegung, Kanälen, Geltungsbereich und Bedingungen, die Stornobedingungen mit ihren Stufen, die Auswahllisten dazu, die Raten aus einem angebundenen PMS und der Stand der Übertragung an die Buchungsportale.
rates:writeRaten und Stornobedingungen anlegen, ändern und löschen. Jede Änderung geht an die Buchungsportale und ändert, was Gäste dort buchen können. Stornobedingungen nur mit einem Schlüssel ohne Apartment-Begrenzung.
promotions:readAktionen (Rabatte auf den Buchungsportalen) mit Rabatt, Zeiträumen, Bedingungen, Apartments, Portalen und dem Stand der Übergabe, dazu die Aktionsarten je Portal.
promotions:writeAktionen anlegen, ändern, ein- und ausschalten. Eine aktive Aktion senkt die Preise der Apartments auf den Buchungsportalen wirklich.
invoices:readRechnungen mit Positionen, Summen und Empfänger, dazu ein Link zum PDF mit eingebetteter E-Rechnung.
invoices:writeRechnungen anlegen und als Entwurf ändern, per E-Mail senden, an die Zahlung erinnern, als versendet oder bezahlt markieren und stornieren (es entsteht eine Stornorechnung).
credit_notes:readGutschriften mit Positionen, Summen und Empfänger, dazu ein Link zum PDF.
credit_notes:writeGutschriften ausstellen, per E-Mail senden und als erstattet bzw. ausgezahlt markieren. Geld bewegt die API dabei nicht.
owners:readEigentümer mit Stammdaten, Kontaktdaten, Anschrift und Apartments, ihre Kontaktpersonen, die Monatsabrechnung (Umsatz, Provision, Auszahlung), Provisionspläne und der Stand des Eigentümerportals. Bankdaten nie — nur die letzten vier Stellen der IBAN.
owners:writeEigentümer und Kontaktpersonen anlegen und ändern, Apartments einem Provisionsplan zuordnen, Aufenthalte des Eigentümers eintragen, das Eigentümerportal schalten und Zugänge einladen (verschickt eine Mail). Nur mit einem Schlüssel ohne Apartment-Begrenzung.

Der Verwalter kann einen Schlüssel außerdem auf einzelne Apartments begrenzen. Für so einen Schlüssel gibt es nur diese Apartments: Listen enthalten nur sie und ihre Buchungen, alles andere antwortet mit 404 oder steht beim Kalender in notFound. GET /me nennt die Apartments in listingIds(null = alle).

Türcodes, WLAN-Passwörter, interne Notizen und Zugangsdaten liefert die API nie, egal mit welchem Recht.

Schnellstart

# Verbindung testen
curl -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/me

# Apartments
curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/listings?limit=50"

# Kalender zweier Apartments für Dezember
curl -H "Authorization: Bearer fw_…" \
  "https://platform.fewocation.de/api/public/v1/calendar?listingIds=<id1>,<id2>&from=2026-12-01&to=2027-01-01"

Endpunkte

EndpunktRechtLiefert
GET /mejeder SchlüsselOrganisation, Rechte des Schlüssels, Demo-Kennzeichen. Zum Testen der Verbindung.
GET /listingslistings:readAlle Apartments, seitenweise. Filter status.
GET /listings/{id}listings:readEin Apartment mit deutschen Texten, Galerie und Ausstattung.
GET /reservationsreservations:readBuchungen, seitenweise, sortiert nach der letzten Änderung. Filter nach Apartment, Zeitraum, Anreise, Abreise und updatedSince.
GET /reservations/{id}reservations:readEine Buchung über ihre id, die Kennung im PMS oder den Buchungscode.
GET /calendar?listingIds=&from=&to=listings:readJe Apartment und Tag: frei oder belegt, Nachtpreis, Mindestnächte, An- und Abreise-Sperren. Bis 50 Apartments und 400 Tage.
POST /quoteslistings:readWas ein Gast für einen Aufenthalt zahlen würde — oder der Grund, warum der Zeitraum nicht buchbar ist.
PUT /listings/{id}/calendarcalendar:writePreise (netto), Mindestnächte und An-/Abreisesperren je Tag oder Zeitraum setzen.
GET /listings/{id}/blockscalendar:writeAktive Sperren eines Apartments ab heute.
POST /listings/{id}/blockscalendar:writeZeitraum sperren (from und to inklusive).
DELETE /listings/{id}/blocks/{blockId}calendar:writeEine über die API angelegte Sperre aufheben.
POST /reservationsreservations:writeBuchung ohne Zahlung anlegen. Pflicht-Kopf Idempotency-Key.
POST /reservations/{id}/cancelreservations:writeEine bei uns geführte Buchung stornieren.
GET /webhookswebhooksDie Webhooks dieses Schlüssels.
POST /webhookswebhooksWebhook anlegen. Die Antwort nennt einmal das Geheimnis für die Signatur.
GET /webhooks/{id}webhooksEin Webhook mit den letzten 20 Zustellungen.
PATCH /webhooks/{id}webhooksAdresse oder Ereignisse ändern, an- oder ausschalten.
DELETE /webhooks/{id}webhooksWebhook löschen.
POST /webhooks/{id}/testwebhooksSofort ein Probe-Ereignis an die Adresse senden.
POST /listingslistings:writeApartment anlegen (Stand onboarding). Pflicht-Kopf Idempotency-Key.
PATCH /listings/{id}listings:writeName, Art, Größe, Gästezahl, Anschrift, Standort und Lage ändern.
GET /listings/{id}/descriptionslistings:readTexte des Inserats in allen gepflegten Sprachen.
PUT /listings/{id}/descriptions/{language}listings:writeTitel, Kurzbeschreibung, Unterkunft und Umgebung einer Sprache setzen.
GET /listings/{id}/amenitieslistings:readAusstattung des Apartments.
PUT /listings/{id}/amenitieslistings:writeAusstattung durch eine Liste von Katalog-Namen ersetzen.
GET /listings/{id}/roomslistings:readRäume mit Betten, in ihrer Reihenfolge.
POST /listings/{id}/roomslistings:writeRaum anlegen.
PATCH /listings/{id}/rooms/{roomId}listings:writeName, Typ und Betten eines Raums ändern.
DELETE /listings/{id}/rooms/{roomId}listings:writeRaum löschen; seine Bilder bleiben.
GET /listings/{id}/imageslistings:readDie ganze Galerie mit Bildunterschrift, Raum und Reihenfolge.
POST /listings/{id}/imageslistings:writeBild von einer öffentlichen Adresse übernehmen.
PUT /listings/{id}/images/orderlistings:writeReihenfolge festlegen; das erste Bild wird das Titelbild.
PATCH /listings/{id}/images/{imageId}listings:writeBildunterschrift und Raum eines Bildes setzen.
DELETE /listings/{id}/images/{imageId}listings:writeBild endgültig löschen.
GET /listings/{id}/booking-ruleslistings:readMindest- und Höchstnächte, Vorlaufzeit, Buchungsfenster, Vorbereitungszeit, übliche Zeiten.
PATCH /listings/{id}/booking-ruleslistings:writeBuchungsregeln ändern. Mindest- und Höchstnächte gehen kurz darauf an die Buchungsportale.
GET /listings/{id}/pricinglistings:readGrundpreise, Endreinigung, Zusatzgäste, Gebühren, Mehrwertsteuer und Preisgrenzen.
PATCH /listings/{id}/pricinglistings:writeGrundpreis, Wochenendpreis, Endreinigung, Zusatzgäste, Wochen- und Monatsfaktor setzen.
GET /listings/{id}/vatlistings:readGeltender Mehrwertsteuersatz je Umsatzart und woher er kommt.
PATCH /listings/{id}/vatlistings:writeMehrwertsteuersatz am Apartment setzen oder wieder erben lassen.
GET /listings/{id}/house-ruleslistings:readDer Hausregel-Text, der für das Apartment gilt.
GET /listing-optionslistings:readAuswahllisten: Arten, Raum- und Bettentypen, Sprachen, Stufen des Buchungsfensters.
GET /listing-options/amenitieslistings:readKatalog der Ausstattungsmerkmale.
GET /locationslistings:readStandorte der Organisation.
GET /multi-unitslistings:readAnlagen mit Zimmerkategorien und ihren Apartments.
GET /rate-plansrates:readEigene Raten, vollständig in einer Antwort. Filter active und listingId.
GET /rate-plans/{id}rates:readEine Rate mit Preis, Verpflegung, Kanälen, Geltungsbereich und Bedingungen.
POST /rate-plansrates:writeRate anlegen. Geht an die Buchungsportale. Pflicht-Kopf Idempotency-Key.
PATCH /rate-plans/{id}rates:writeRate ändern. Fehlende Felder bleiben. Geht an die Buchungsportale.
DELETE /rate-plans/{id}rates:writeRate löschen — auch bei den Buchungsportalen.
GET /rate-plans/sync-statusrates:readStand der letzten Übertragung an die Buchungsportale.
GET /rate-plans/pmsrates:readRaten aus einem angebundenen PMS, wie sie an Buchungen gesehen wurden. Nur lesbar.
GET /cancellation-policiesrates:readStornobedingungen mit Stufen und Zahlungsvorgabe. Filter active.
GET /cancellation-policies/{id}rates:readEine Stornobedingung.
POST /cancellation-policiesrates:writeStornobedingung anlegen. Pflicht-Kopf Idempotency-Key.
PATCH /cancellation-policies/{id}rates:writeStornobedingung ändern — gilt für jede Rate, die sie trägt.
DELETE /cancellation-policies/{id}rates:writeStornobedingung löschen, solange keine Rate sie benutzt.
GET /rate-optionsrates:readAuswahllisten: Kanäle, Verpflegungen, Einordnungen, Einheiten, Grenzen.
GET /promotion-typespromotions:readAktionsarten je Portal mit erlaubtem Rabatt, Pflichtfeldern und Bedingungen. Filter channel.
GET /promotionspromotions:readAktionen, seitenweise. Filter status, listingId, channel, type.
GET /promotions/{id}promotions:readEine Aktion mit Rabatt, Zeiträumen, Bedingungen, Apartments und dem Stand je Portal.
POST /promotionspromotions:writeAktion anlegen und an die Portale senden. Pflicht-Kopf Idempotency-Key.
PATCH /promotions/{id}promotions:writeAktion ändern und erneut senden. Fehlende Felder bleiben.
POST /promotions/{id}/activatepromotions:writeAktion bei allen Portalen einschalten.
POST /promotions/{id}/deactivatepromotions:writeAktion bei allen Portalen ausschalten (beenden oder pausieren). Gelöscht wird nie.
GET /promotions/{id}/delivery?listingId=promotions:readOb die Aktion an einem Apartment beim Portal angekommen ist, je Portal.
GET /invoicesinvoices:readRechnungen, seitenweise, sortiert nach der letzten Änderung. Filter status, overdue, from/to, listingId, reservationId, number und updatedSince.
GET /invoices/{id}invoices:readEine Rechnung mit Positionen, Summen, Empfänger und Buchungen.
GET /invoices/{id}/documentinvoices:readLink zum PDF (ZUGFeRD mit eingebetteter E-Rechnung), 30 Minuten gültig.
POST /invoicesinvoices:writeEntwurf mit laufender Nummer anlegen. Pflicht-Kopf Idempotency-Key.
PATCH /invoices/{id}invoices:writeEinen Entwurf ändern. Ausgestellte Rechnungen sind unveränderlich.
POST /invoices/{id}/sendinvoices:writeAls PDF per E-Mail senden; ein Entwurf ist danach ausgestellt. Pflicht-Kopf Idempotency-Key.
POST /invoices/{id}/remindersinvoices:writeZahlungserinnerung mit der Rechnung als PDF senden. Pflicht-Kopf Idempotency-Key.
POST /invoices/{id}/mark-sentinvoices:writeFesthalten, dass die Rechnung auf anderem Weg hinausging. Pflicht-Kopf Idempotency-Key.
POST /invoices/{id}/mark-paidinvoices:writeZahlungseingang festhalten.
POST /invoices/{id}/cancelinvoices:writeStornieren: Es entsteht eine Stornorechnung. Pflicht-Kopf Idempotency-Key.
GET /credit-notescredit_notes:readGutschriften, seitenweise. Filter status, from/to, listingId, reservationId, number und updatedSince.
GET /credit-notes/{id}credit_notes:readEine Gutschrift mit Positionen und Summen.
GET /credit-notes/{id}/documentcredit_notes:readLink zum PDF, 30 Minuten gültig.
POST /credit-notescredit_notes:writeKorrektur-Gutschrift zu einer Rechnung oder Buchung ausstellen. Pflicht-Kopf Idempotency-Key.
POST /credit-notes/self-billingcredit_notes:writeAbrechnungs-Gutschrift (Empfehlungsprovision) ausstellen. Pflicht-Kopf Idempotency-Key.
POST /credit-notes/{id}/sendcredit_notes:writeAls PDF per E-Mail senden. Pflicht-Kopf Idempotency-Key.
POST /credit-notes/{id}/mark-paidcredit_notes:writeFesthalten, dass erstattet bzw. ausgezahlt wurde.
GET /ownersowners:readEigentümer, seitenweise. Filter status und q (Name, Firma, E-Mail).
GET /owners/{id}owners:readEin Eigentümer mit Stammdaten, Kontaktdaten, Anschrift und seinen Apartments (listingIds).
POST /ownersowners:writeEigentümer anlegen — ohne Bankdaten, ohne Mail.
PATCH /owners/{id}owners:writeStammdaten, Kontaktdaten und Anschrift ändern. Fehlende Felder bleiben.
GET /owners/{id}/contactsowners:readKontaktpersonen des Eigentümers mit Kanal und Meldungen.
POST /owners/{id}/contactsowners:writeKontaktperson anlegen.
PATCH /owners/{id}/contacts/{contactId}owners:writeKontaktperson ändern. Fehlende Felder bleiben.
DELETE /owners/{id}/contacts/{contactId}owners:writeKontaktperson löschen.
GET /owners/{id}/statements?from=&to=owners:readMonatsabrechnungen: Umsatz, Provisionen, Auszahlung. Höchstens 24 Monate.
POST /owners/{id}/staysowners:writeAufenthalt des Eigentümers eintragen. Pflicht-Kopf Idempotency-Key.
GET /owners/{id}/portalowners:readEigentümerportal: eingeschaltet, sichtbare Apartments, Zugänge.
PATCH /owners/{id}/portalowners:writeEigentümerportal ein- oder ausschalten.
POST /owners/{id}/portal/invitationsowners:writeZugang einladen — verschickt eine Mail. Pflicht-Kopf Idempotency-Key.
DELETE /owners/{id}/portal/members/{memberId}owners:writeZugang entziehen oder offene Einladung zurückziehen.
GET /commission-plansowners:readProvisionspläne mit zugeordneten Apartments. Filter ownerId, listingId, includeArchived, on.
GET /commission-plans/{id}owners:readEin Provisionsplan.
PUT /commission-plans/{id}/assignments/{listingId}owners:writeApartment dem Plan zuordnen oder die Preise der Zuordnung ändern.
DELETE /commission-plans/{id}/assignments/{listingId}owners:writeZuordnung aufheben.

Alle Felder und Antworten im Einzelnen stehen in der OpenAPI-Beschreibung (Abschnitt „Organisation“).

Seitenweise lesen

Listen kommen in Seiten: limit Zeilen (Standard 100, höchstens 200). Steht in der Antwort ein nextCursor, gibt es eine weitere Seite — den Wert unverändert als cursor mitschicken und die übrigen Parameter gleich lassen. nextCursor: null heißt: letzte Seite.

Buchungen abgleichen

Die Liste der Buchungen ist immer nach updatedAt sortiert und enthält jeden Stand, auch stornierte (status: "ended"). So gleichst du ab: einmal alles lesen, das größte updatedAt merken, danach regelmäßig mit updatedSince nachfragen. Die Grenze ist inklusive — die zuletzt gesehene Buchung kommt noch einmal. Speichere deshalb nach id (einfügen oder überschreiben).

// Alle Buchungen lesen, die sich seit dem letzten Lauf geändert haben (Node 18+)
const BASE = "https://platform.fewocation.de/api/public/v1";
const headers = { Authorization: `Bearer ${process.env.FEWOCATION_API_KEY}` };

export async function syncReservations(lastSeen: string | null, save: (reservation: Reservation) => Promise<void>) {
  let cursor: string | null = null;
  let newest = lastSeen;
  do {
    const url = new URL(`${BASE}/reservations`);
    if (lastSeen) url.searchParams.set("updatedSince", lastSeen);
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers });
    const body = await res.json();
    if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
    for (const reservation of body.data) {
      await save(reservation);            // nach id einfügen oder überschreiben
      newest = reservation.updatedAt;     // die Liste ist nach updatedAt sortiert
    }
    cursor = body.nextCursor;
  } while (cursor);
  return newest;                          // für den nächsten Lauf merken
}

status hat vier Werte: inquiry (Anfrage), hold (auf Zeit reserviert), confirmed (verbindlich — auch eingecheckt und abgereist) und ended (storniert, abgelehnt, abgelaufen). Zum Verzweigen immer status nehmen, nicht statusRaw. checkOut ist der Abreisetag: Die Nacht ab diesem Tag gehört nicht mehr zur Buchung.

Quelle ist der Stand der Plattform. Buchungen aus einem angebundenen PMS sind so frisch wie dessen letzter Abgleich, in der Regel wenige Minuten.

Beträge

Mit dem Recht finances:read trägt jede Buchung das Objekt amounts. Alle Werte sind ganze Cent in der Währung der Buchung (currency, meist EUR). Liegen für eine Buchung keine Beträge vor — etwa bei Anfragen, vielen Stornos und Buchungen vor 2026 — steht dort null, nie eine Schätzung.

guestTotalCentsWas der Gast insgesamt zahlt, mit Steuern und lokaler Abgabe. null = unbekannt.
accommodationNetCents / …GrossCentsÜbernachtung ohne und mit Mehrwertsteuer.
cleaningNetCents / …GrossCentsEndreinigung ohne und mit Mehrwertsteuer.
otherFeesNetCents / …GrossCentsZwischenreinigung, Frühstück und weitere Gebühren.
vatCentsMehrwertsteuer auf Übernachtung, Reinigung und Gebühren (Summe brutto minus Summe netto).
localTaxCentsLokale Abgabe im Gastpreis (Kurtaxe, City Tax), soweit das Portal sie eingezogen hat.
channelCommissionCentsProvision des Buchungsportals.
sourcepms = aus dem angebundenen PMS bzw. vom Portal; platform = Direktbuchung der Plattform.

Die Werte kommen so, wie das angebundene PMS bzw. das Buchungsportal sie liefert; spätere Handkorrekturen aus der Eigentümerabrechnung stecken nicht darin. Die Auszahlung des Portals ist bewusst nicht enthalten. Ändert sich ein Betrag, gilt die Buchung als geändert — sie kommt beim nächsten Abgleich mit updatedSince wieder.

Kalender

GET /calendar liefert für bis zu 50 Apartments die Tage from (inklusive) bis to (exklusiv), höchstens 400 Tage und nicht in der Vergangenheit. Je Tag:

available / statusIst die Nacht ab diesem Tag frei? status nennt den Grund: available, booked, blocked oder no_data (für den Tag steht nichts im Kalender — er gilt als nicht frei).
priceCentsNachtpreis, wie er im Kalender steht: netto, ohne Mehrwertsteuer. Derselbe Wert geht an die Buchungsportale. null = kein Preis hinterlegt.
minNightsMindestnächte bei Anreise an diesem Tag.
closedToArrival / closedToDepartureAn diesem Tag ist keine Anreise bzw. keine Abreise möglich.

Vorlaufzeit und Buchungsfenster stehen einmal je Apartment (earliestCheckIn, latestCheckIn), nicht an jedem Tag. Apartments, die es nicht gibt oder die nicht in Betrieb sind, stehen in notFound statt in data.

Preis anfragen

POST /quotes rechnet, was ein Gast für einen Aufenthalt zahlen würde: Nächte, Aufschlag für weitere Gäste, Langzeit-Rabatt, Endreinigung und lokale Abgaben — in Cent und brutto. guests zählt alle Gäste;childAges nennt das Alter der Kinder am Anreisetag und wirkt nur auf die lokale Abgabe. Ist der Zeitraum nicht buchbar, antwortet der Endpunkt trotzdem mit 200 und nennt den Grund.

curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"listingId":"<id>","checkIn":"2026-12-27","checkOut":"2027-01-02","guests":4,"childAges":[8]}' \
  https://platform.fewocation.de/api/public/v1/quotes

# Buchbar:
# { "data": { "available": true, "quote": { "nights": 6, "accommodationCents": 96300, "cleaningCents": 8900,
#     "localTaxes": [{ "name": "Kurtaxe", "amountCents": 5400 }], "totalCents": 110600, "currency": "EUR", … } } }
# Nicht buchbar:
# { "data": { "available": false, "problem": { "code": "min_nights", "message": "…" } } }

Der Kalender nennt Nachtpreise netto, die Preisanfrage den Gastpreis brutto. Extras und Rabattcodes gehören zu einer Direktbuchungsseite und stehen in der Booking Engine API.

Kalender schreiben

PUT /listings/{id}/calendar setzt je Tag den Nachtpreis (netto, in Cent — derselbe Wert wie priceCents beim Lesen), die Mindestnächte und die An- und Abreisesperre. Ein Eintrag nennt einen Tag (date) oder einen Zeitraum (from und to, beide inklusive) und mindestens einen Wert. Felder, die fehlen, bleiben, wie sie sind. Nennt ein späterer Eintrag denselben Tag noch einmal, gewinnen seine Felder. Höchstens 730 Tage im Voraus; Tage vor heute werden gezählt (skippedPast), nicht geschrieben.

# Dezember: 129 € netto je Nacht, mindestens 3 Nächte — Heiligabend 199 € und keine Anreise
curl -X PUT -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"days":[
        {"from":"2026-12-01","to":"2026-12-31","priceCents":12900,"minNights":3},
        {"date":"2026-12-24","priceCents":19900,"closedToArrival":true}]}' \
  https://platform.fewocation.de/api/public/v1/listings/<id>/calendar

# { "data": { "listingId": "…", "written": 31, "skippedPast": 0, "from": "2026-12-01", "to": "2026-12-31" } }

# Zeitraum sperren (beide Tage gehören dazu) und wieder aufheben
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"from":"2027-01-10","to":"2027-01-14","note":"Renovierung"}' https://platform.fewocation.de/api/public/v1/listings/<id>/blocks
curl -X DELETE -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/listings/<id>/blocks/<blockId>

Schreiben geht nur für Apartments, deren Kalender die Plattform führt. Führt ihn ein angebundenes PMS, antwortet die API mit 409 pms_managed. Setzt ein Preistool die Preise des Apartments, lehnt sie Preise mit 409 price_source_conflict ab; Mindestnächte und Sperren gehen weiter. Die Buchungsportale bekommen die Änderung kurz darauf. Hat der Verwalter einen Mindest- oder Höchstpreis hinterlegt, wirkt er beim Senden an die Portale.

Frei oder belegt ändert der Kalender-Endpunkt nie. Dafür gibt es Sperren: POST /listings/{id}/blocks sperrt einen Zeitraum, belegte Nächte bleiben unberührt. Derselbe Zeitraum zweimal ergibt dieselbe Sperre (created: false). GET zeigt alle aktiven Sperren, auch die aus dem Dashboard. Aufheben lassen sich über die API nur Sperren, die über die API angelegt wurden (viaApi: true) — alle anderen und Sperren, deren Zeitraum eine weitere Sperre berührt, antworten mit 409 block_conflict.

Buchungen anlegen

POST /reservations legt eine Buchung ohne Zahlung an — so, als trüge der Verwalter sie von Hand in den Kalender ein. Sie hat deshalb alle Folgen einer Buchung: Reinigungsauftrag, automatische Nachrichten an den Gast, Belegung auf den Buchungsportalen. Ohne Preisangabe gilt der Preis aus dem Kalender; mit accommodationNetCents und cleaningNetCents gibst du ihn netto vor.

curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f0c1a52-6f0e-4c0b-9a3e-0d6f2f1c9b77" \
  -d '{"listingId":"<id>","checkIn":"2027-02-12","checkOut":"2027-02-15","guests":2,
       "guest":{"firstName":"Anna","lastName":"Beispiel","email":"anna@example.com"}}' \
  https://platform.fewocation.de/api/public/v1/reservations

# { "data": { "id": "…", "confirmationCode": "FW-…", "status": "confirmed", "channel": "direct", … } }

# Stornieren
curl -X POST -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/reservations/<id>/cancel

Der Kopf Idempotency-Key ist Pflicht: ein eigener, eindeutiger Wert je Buchung. Kommt nach einer Zeitüberschreitung keine Antwort, schick dieselbe Anfrage mit demselben Schlüssel noch einmal — du bekommst die erste Antwort, keine zweite Buchung (24 Stunden lang). Derselbe Schlüssel mit anderem Inhalt antwortet mit 409 idempotency_key_reused.

Geprüft wird, dass der Zeitraum frei ist (sonst 409 not_available). Mindestnächte und Vorlaufzeit prüft die API hier nicht — frag vorher POST /quotes, wenn sie gelten sollen. Anlegen geht nur für Apartments, deren Kalender die Plattform führt. POST /reservations/{id}/cancel storniert Buchungen, die bei uns geführt werden; Buchungen aus einem Portal oder PMS storniert man dort (409 pms_managed). Erstattet wird über die API nichts.

Webhooks

Statt regelmäßig nachzufragen, lass dir Änderungen melden: Ein Webhook ist eine Adresse bei dir, an die die Plattform jede neue, geänderte oder stornierte Buchung sendet. Es gibt drei Ereignisse: reservation.created, reservation.updated (Zeitraum, Gäste, Apartment, Bestätigung) und reservation.cancelled. Der Inhalt ist die Buchung im Stand der Zustellung — mit genau den Feldern, die dein Schlüssel auch lesen darf (guest nur mit guests:read, amounts nur mit finances:read) und nur für Apartments in seinem Bereich.

# Webhook anlegen — das secret steht nur in dieser Antwort
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"url":"https://partner.example.com/hooks/fewocation",
       "events":["reservation.created","reservation.updated","reservation.cancelled"]}' \
  https://platform.fewocation.de/api/public/v1/webhooks

# { "data": { "id": "…", "url": "…", "events": […], "active": true, … }, "secret": "whsec_…" }

# Das sendet die Plattform an deine Adresse (POST, JSON):
#   FeWocation-Event: reservation.updated
#   FeWocation-Delivery: <id des Ereignisses>
#   FeWocation-Signature: t=1794450000,v1=5f2c…
# { "id": "…", "type": "reservation.updated", "createdAt": "2026-12-01T10:15:00Z",
#   "data": { "reservation": { "id": "…", "status": "confirmed", "checkIn": "2027-02-12", … } } }

# Probe-Ereignis senden
curl -X POST -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/webhooks/<id>/test

Die Adresse muss mit https:// beginnen und öffentlich erreichbar sein. Antworte innerhalb von 10 Sekunden mit einem Status 2xx und verarbeite danach; Weiterleitungen folgt die Plattform nicht. Jede Zustellung ist signiert: Prüf den Kopf FeWocation-Signature mit dem Geheimnis aus der Antwort beim Anlegen. Es wird nur dieses eine Mal angezeigt.

// Signatur prüfen (Node 18+). rawBody = Inhalt der Anfrage als Text, unverändert.
import crypto from "node:crypto";

function isFromFewocation(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=")));
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!(ageSeconds <= 300)) return false; // älter als 5 Minuten: ablehnen
  const expected = crypto.createHmac("sha256", secret).update(parts.t + "." + rawBody).digest("hex");
  if (!parts.v1 || parts.v1.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Zugestellt wird mindestens einmal — dieselbe Meldung kann doppelt ankommen. Entdopple über id (steht auch im Kopf FeWocation-Delivery) und verlass dich nicht auf die Reihenfolge; der Stand in data.reservation ist immer der aktuelle. Schlägt eine Zustellung fehl, versucht es die Plattform mehrfach über gut zwei Stunden. Ereignisse, die älter als 24 Stunden sind, liefert sie nicht nach — hol sie nach einem längeren Ausfall mit updatedSince. Nach drei Tagen ohne eine erfolgreiche Zustellung schaltet die Plattform den Webhook ab (active: false, Grund in disabledReason); mit PATCH und active: true schaltest du ihn wieder ein.

GET /webhooks/{id} zeigt die letzten 20 Zustellungen mit Status und Fehler, POST /webhooks/{id}/test sendet sofort ein Ereignis webhook.test. Ein Webhook gehört zu dem Schlüssel, der ihn angelegt hat: Wird der Schlüssel deaktiviert oder gelöscht, endet auch der Webhook. Je Schlüssel sind fünf Webhooks möglich. In einem Demo-Konto wird nichts gesendet.

Apartments verwalten

Mit dem Recht listings:write legst du Apartments an und pflegst alles, was ein Inserat ausmacht: Stammdaten, Texte, Ausstattung, Räume, Bilder, Buchungsregeln und Preise. Jeder Schreib-Endpunkt antwortet mit dem neuen Stand in data und einer Liste warnings — Hinweise, die das Speichern nicht aufgehalten haben, zum Beispiel wenn sich die Lage nicht aus der Anschrift ermitteln ließ. Meist ist sie leer. Felder, die die API nicht kennt, lehnt sie mit 400 ab; so bleibt ein Tippfehler nicht ohne Wirkung.

curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f0c1e-5a43-4d0e-9a39-2f8f6d1b9e11" \
  -d '{"name":"Hafenblick 3","address":{"street":"Am Hafen 12","zip":"12345","city":"Musterstadt","country":"DE","state":"DE-MV"},
       "propertyType":"Apartment","roomType":"Entire home/apt","maxGuests":4,"sizeSqm":62}' \
  https://platform.fewocation.de/api/public/v1/listings

# { "data": { "id": "9b2f…", "name": "Hafenblick 3", "status": "onboarding", "operative": true,
#             "propertyType": "Apartment", "maxGuests": 4, "locationId": null,
#             "address": { "street": "Am Hafen 12", "zip": "12345", "city": "Musterstadt", "state": "DE-MV", "country": "DE" },
#             "location": { "latitude": 51.1657, "longitude": 10.4515 }, "description": null, "gallery": [], "amenities": [], … },
#   "warnings": [] }

# Später ändern — nur die genannten Felder:
curl -X PATCH -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"maxGuests":5,"address":{"street":"Am Hafen 14"}}' \
  https://platform.fewocation.de/api/public/v1/listings/<id>

POST /listings braucht einen Namen (je Organisation eindeutig) und die vollständige Anschrift, dazu den Kopf Idempotency-Key wie bei Buchungen. Das Apartment entsteht im Stand onboarding und steht auf keinem Buchungsportal. Im Dashboard bekommt es eine Checkliste; dort schaltet der Verwalter es aktiv und verknüpft die Portale. Ist die Organisation direkt an die Buchungsportale angebunden, legt die Plattform das Apartment für diese Anbindung von selbst an, sobald die Angaben reichen. Ein Schlüssel, der auf bestimmte Apartments begrenzt ist, kann nichts anlegen (403 forbidden).

Ändern geht nur für Apartments, die die Plattform führt. Wird ein Apartment in einem angebundenen PMS geführt, antwortet jeder Schreib-Endpunkt mit 409 pms_managed — lesen kannst du es trotzdem. Hängt das Apartment an Buchungsportalen, gehen Änderungen von selbst dorthin: Texte sofort, alles andere kurz darauf. PATCH /listings/{id} ändert Name, Art, Größe, Gästezahl, Anschrift und Standort; nach einer neuen Anschrift ermittelt die Plattform die Lage neu, mit location setzt du sie selbst. Zimmer- und Bettenzahlen ergeben sich aus den Räumen. Status ändern, löschen und alles rund um den Zugang (Türcode, WLAN, Anreise-Hinweise) gibt es über die API bewusst nicht.

Texte, Ausstattung, Räume, Bilder

Texte gibt es je Sprache: title, summary, space und neighborhood. GET /listings/{id}/descriptions liefert alle gepflegten Sprachen, PUT …/descriptions/{language} setzt die genannten Felder einer Sprache (ISO-Code wie de oder en; null löscht ein Feld). Die API übersetzt nicht — setz jede Sprache selbst. Geht das Apartment über die Plattform an die Buchungsportale, prüft sie den Titel vorher: Einer, den die Portale ablehnen würden (zum Beispiel mit Doppelpunkt oder über 50 Zeichen), kommt mit 400 und dem Grund zurück.

# Englische Texte setzen (Sprache als ISO-Code in der Adresse)
curl -X PUT -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"title":"Harbour view apartment with balcony","summary":"Bright two-room apartment, 200 m from the old harbour."}' \
  https://platform.fewocation.de/api/public/v1/listings/<id>/descriptions/en

# { "data": { "language": "en", "title": "Harbour view apartment with balcony",
#             "summary": "Bright two-room apartment, 200 m from the old harbour.",
#             "space": null, "neighborhood": null, "updatedAt": "2026-11-12T09:41:07.113Z" }, "warnings": [] }

# Ausstattung ersetzen (Namen aus /listing-options/amenities)
curl -X PUT -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"amenities":["Wireless Internet","Kitchen","Dishwasher","Balcony"]}' \
  https://platform.fewocation.de/api/public/v1/listings/<id>/amenities

# Raum mit Betten anlegen
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"name":"Schlafzimmer","type":"BEDROOM","beds":{"DOUBLE_BED":1}}' \
  https://platform.fewocation.de/api/public/v1/listings/<id>/rooms

# { "data": { "id": "41c0…", "name": "Schlafzimmer", "type": "BEDROOM", "beds": { "DOUBLE_BED": 1 }, "position": 1 }, "warnings": [] }

# Bild von einer Adresse übernehmen, dann nach vorn stellen
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/fotos/wohnzimmer.jpg","caption":"Wohnzimmer mit Hafenblick","roomId":null}' \
  https://platform.fewocation.de/api/public/v1/listings/<id>/images

curl -X PUT -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"imageIds":["<bild-id>"]}' \
  https://platform.fewocation.de/api/public/v1/listings/<id>/images/order

PUT /listings/{id}/amenities ersetzt die Ausstattung durch deine Liste. Die Namen stammen aus dem Katalog (GET /listing-options/amenities); ein unbekannter Name ist ein Fehler. Merkmale, die aus den Regeln des Apartments folgen — etwa „Pets allowed“ —, lassen sich hier nicht umstellen und bleiben stehen.

Räume tragen einen Typ und ihre Betten als { "BETTENTYP": Anzahl }; die Werte nennt GET /listing-options. beds ersetzt beim Ändern die Betten des Raums ganz. Löschst du einen Raum, bleiben seine Bilder und sind danach keinem Raum zugeordnet.

Bilder holt die Plattform selbst von der Adresse, die du nennst, und speichert sie: JPEG, PNG oder WebP bis 20 MB, öffentlich erreichbar. Lässt sich das Bild nicht holen, antwortet die API mit 409 conflict. Ein neues Bild steht am Ende der Galerie; PUT …/images/order stellt die genannten Bilder nach vorn, das erste ist das Titelbild. Eine wiederholte Anfrage legt ein zweites Bild bzw. einen zweiten Raum an — prüf nach einer Zeitüberschreitung erst mit GET. Löschen ist endgültig und gilt auch auf den Buchungsportalen.

Buchungsregeln und Preise

Buchungsregeln gelten für jede Buchung des Apartments: Mindest- und Höchstnächte, Vorlaufzeit in Stunden, Buchungsfenster in Tagen (nur die Stufen aus GET /listing-options, -1 = unbegrenzt), Vorbereitungszeit und die üblichen Zeiten für An- und Abreise. Mindestnächte an einzelnen Tagen setzt du im Kalender. Die Vorlaufzeit sperrt zusätzlich die Anreisetage, die zu nah liegen, auf der eigenen Buchungsseite.

# Buchungsregeln
curl -X PATCH -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"minNights":2,"advanceNoticeHours":24,"bookingWindowDays":365,"checkInTime":"16:00"}' \
  https://platform.fewocation.de/api/public/v1/listings/<id>/booking-rules

# { "data": { "minNights": 2, "maxNights": null, "advanceNoticeHours": 24, "bookingWindowDays": 365,
#             "preparationDays": null, "preparationWhen": null, "allowRequestToBook": null,
#             "checkInTime": "16:00", "checkInUntil": null, "checkOutTime": "11:00", "managedBy": "platform" },
#   "warnings": [] }

# Preise: netto, in Cent
curl -X PATCH -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"basePriceCents":9500,"cleaningFeeCents":6500,"cleaningFeeBasis":"PER_STAY","guestsIncluded":2,"extraGuestFeeCents":1500}' \
  https://platform.fewocation.de/api/public/v1/listings/<id>/pricing

# { "data": { "currency": "EUR", "basePriceCents": 9500, "weekendBasePriceCents": null,
#             "cleaningFeeCents": 6500, "cleaningFeeBasis": "PER_STAY", "guestsIncluded": 2, "extraGuestFeeCents": 1500,
#             "weeklyPriceFactor": null, "monthlyPriceFactor": null, "updatedAt": "2026-11-12T09:44:30.501Z",
#             "fees": [ { "id": "c7e1…", "name": "Haustier", "type": "PET", "amountCents": 1500, "percent": null,
#                         "basis": "PER_STAY", "optional": false } ],
#             "vat": { "accommodationPercent": 7, "cleaningPercent": 7, "breakfastPercent": 19, "extrasPercent": 19,
#                      "sources": { "accommodation": "organization", "cleaning": "organization",
#                                   "breakfast": "default", "extras": "default" } },
#             "priceLimits": { "currency": "EUR", "minimum": { "priceCents": 7000, "validFrom": null, "validUntil": null },
#                              "maximum": null } },
#   "warnings": [] }

Alle Beträge sind netto und in ganzen Cent, wie der Nachtpreis im Kalender. Der Grundpreis gilt für Nächte, für die der Kalender keinen eigenen Preis nennt; Tagespreise schreibst du mit PUT /listings/{id}/calendar. null heißt „nicht gepflegt“, nicht 0. Die Wochen- und Monatsfaktoren sind Multiplikatoren: 0.9 bedeutet 10 % Rabatt. fees und priceLimits (Mindest- und Höchstpreis des Verwalters) sind nur lesbar; die Preisgrenzen wirken beim Senden an die Portale.

PATCH /listings/{id}/vat setzt den Mehrwertsteuersatz je Umsatzart am Apartment: accommodationPercent, cleaningPercent, breakfastPercent, extrasPercent. Mit null erbt das Apartment wieder vom Standort bzw. von der Organisation; sources sagt, woher der geltende Satz kommt. Die Sätze gelten für Preise, Rechnungen und Buchungsportale — ändere sie nur in Absprache mit dem Verwalter.

GET /listings/{id}/house-rules liefert den Hausregel-Text, dem Gäste beim Online-Check-in zustimmen, und die Ebene, auf der er gepflegt ist. Ändern lässt er sich nur im Dashboard.

Auswahllisten, Standorte, Anlagen

Arten, Raum- und Bettentypen und die Stufen des Buchungsfensters sind feste Listen. Hol sie einmal mit GET /listing-options und übernimm die Werte unverändert — ein erfundener Wert wird abgelehnt. Die Beschriftungen sind deutsch.

curl -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/listing-options

# { "data": {
#     "propertyTypes":        [ { "value": "Apartment", "label": "Wohnung", "common": true }, … ],
#     "listingRoomTypes":     [ { "value": "Entire home/apt", "label": "Ganze Unterkunft" }, … ],
#     "roomTypes":            [ { "value": "BEDROOM", "label": "Schlafzimmer", "group": "schlafen" }, … ],
#     "bedTypes":             [ { "value": "DOUBLE_BED", "label": "Doppelbett" }, … ],
#     "descriptionLanguages": [ { "code": "de", "label": "Deutsch", "offered": true }, … ],
#     "bookingWindowDays":    [ { "value": -1, "label": "Unbegrenzt" }, { "value": 30, "label": "30 Tage (~1 Monat)" }, … ],
#     "cleaningFeeBases":     [ "PER_STAY", "PER_NIGHT", "PER_GUEST", "PER_GUEST_PER_NIGHT" ] } }

curl -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/locations

# { "data": [ { "id": "5d0a…", "name": "Musterstadt Altstadt",
#               "address": { "street": "Am Hafen 12", "zip": "12345", "city": "Musterstadt", "state": "DE-MV", "country": "DE" },
#               "timezone": "Europe/Berlin" } ], "nextCursor": null }

GET /locations nennt die Standorte der Organisation; ihre id gehört in locationId am Apartment. GET /multi-units liefert Anlagen mit mehreren gleichen Einheiten samt Zimmerkategorien und den Apartments darin — passend zu complexId und unitTypeId am Apartment. Ein Schlüssel, der auf Apartments begrenzt ist, sieht nur die Standorte und Anlagen seiner Apartments.

Raten

Eine Rate ist ein Angebot, zu dem ein Apartment auf den Buchungsportalen buchbar ist: der Tagespreis aus dem Kalender plus eine Abweichung in Prozent (priceAdjustmentPercent, -10 = 10 % günstiger), eine Stornobedingung, wahlweise eine Verpflegung und Bedingungen wie ein Mindestaufenthalt. GET /rate-plans liefert alle Raten der Organisation in einer Antwort; mit listingId bekommst du nur die, die für ein Apartment gelten, mit active nur ein- oder ausgeschaltete.

# Welche Raten gelten für ein Apartment?
curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/rate-plans?listingId=<listingId>&active=true"

# { "data": [
#   { "id": "…", "code": "nicht-erstattbar", "name": "Nicht erstattbar", "description": null, "active": true,
#     "cancellationKind": "non_refundable", "priceKind": "discount",
#     "channels": ["booking", "expedia"], "cancellationPolicyId": "…",
#     "priceAdjustmentPercent": -10,
#     "mealPlan": "breakfast", "mealSurchargeCents": 1500, "mealSurchargeUnit": "per_person_per_night",
#     "bookableFrom": null, "bookableUntil": null, "arrivalsFrom": null, "arrivalsUntil": null,
#     "minimumStay": 2, "minDaysBeforeArrival": null, "maxDaysBeforeArrival": null,
#     "scope": { "mode": "include", "listingIds": ["…"], "locationIds": [] },
#     "restrictions": [],
#     "firstSyncedAt": "2026-10-13T09:41:07+00:00", "createdAt": "…", "updatedAt": "…" } ],
#   "nextCursor": null }

cancellationKind und priceKind ordnen die Rate auf einen Blick ein: kostenlos stornierbar (flexible), mit Gebühr ab Buchung (partial) oder nicht erstattbar (non_refundable); Tagespreis (standard), günstiger (discount) oder teurer (markup). Die Regeln selbst stehen an der Stornobedingung (cancellationPolicyId). Kostet die Verpflegung extra, nennt mealSurchargeCents den Aufpreis in Cent und mealSurchargeUnit, ob er je Nacht oder je Person und Nacht gilt; null heißt: im Preis enthalten.

scope sagt, für welche Apartments die Rate gilt: all (alle), include (nur die genannten Apartments und Standorte) oder exclude (alle außer den genannten). Ein Standort steht für alle seine Apartments. channels nennt die Kanäle als Codes — die Namen dazu liefert GET /rate-options. bookableFrom/bookableUntil begrenzen, wann gebucht werden kann, arrivalsFrom/arrivalsUntil den Zeitraum der Anreise, minDaysBeforeArrival/maxDaysBeforeArrival den Abstand zwischen Buchung und Anreise. restrictions sind Einschränkungen für einzelne Zeiträume; sie sind über die API nur lesbar.

Diese Raten gelten für Apartments, die über die Plattform an den Buchungsportalen hängen. firstSyncedAt zeigt, wann eine Rate dort erstmals ankam; den Stand der letzten Übertragung liefert GET /rate-plans/sync-status. Ist dein Schlüssel auf einzelne Apartments begrenzt, siehst du nur Raten, die für mindestens eines davon gelten, und in scope.listingIds nur deine Apartments.

Stornobedingungen

GET /cancellation-policies liefert den Katalog der Stornobedingungen. Eine Bedingung gilt für alle Kanäle der Raten, die sie tragen. summary fasst die Regeln in einem deutschen Satz zusammen, rules enthält sie zum Rechnen.

curl -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/cancellation-policies

# { "data": [
#   { "id": "…", "name": "Flexibel bis 5 Tage", "guestDescription": null, "isDefault": true, "active": true,
#     "kind": "flexible",
#     "summary": "kostenlos bis 5 Tage vor Anreise · weniger als 5 Tage vorher: 100 % · Nichterscheinen 100 %",
#     "rules": {
#       "beforeArrival": [ { "hours": 120, "amount": 100, "amountType": "percent" } ],
#       "afterBooking": null,
#       "noShow": { "amount": 100, "amountType": "percent" } },
#     "prepayment": null,
#     "channelPolicies": [ { "channel": "booking", "code": "…", "chosenBy": "suggested" } ],
#     "createdAt": "…", "updatedAt": "…" },
#   { "name": "Nicht erstattbar", "kind": "non_refundable",
#     "rules": { "beforeArrival": [], "afterBooking": { "hours": 0, "amount": 100, "amountType": "percent" },
#                "noShow": { "amount": 100, "amountType": "percent" } }, … } ],
#   "nextCursor": null }

So liest du rules: beforeArrival sind bis zu drei Stufen, die früheste zuerst. Eine Stufe heißt: Wer weniger als hours Stunden vor der Anreise storniert, zahlt amount. Vor der ersten Stufe ist das Stornieren kostenlos; jede weitere Stufe liegt näher an der Anreise und löst die vorige ab. afterBooking ist eine Gebühr, die hours Stunden nach der Buchung fällig wird — hours: 0 mit 100 percent heißt nicht erstattbar. noShow gilt, wenn der Gast nicht erscheint. amountType ist percent (Prozent des Aufenthaltspreises) oder nights (der Preis so vieler Nächte).

prepayment ist die Zahlungsvorgabe: afterBooking eine Anzahlung so viele Stunden nach der Buchung, beforeArrival die Restzahlung so viele Stunden vor der Anreise — in Prozent ist das der Rest nach der Anzahlung. channelPolicies zeigt für Kanäle mit fester Liste (Booking.com, Airbnb, Agoda, Marriott), welche ihrer eigenen Bedingungen dieser entspricht; die Plattform wählt sie passend zu den Regeln, der Verwalter kann sie im Dashboard von Hand ändern.

Raten und Stornobedingungen ändern

Mit dem Recht rates:write legst du Raten und Stornobedingungen an (POST, Pflicht-Kopf Idempotency-Key), änderst sie (PATCH, fehlende Felder bleiben) und löschst sie (DELETE). Eine neue Rate braucht name, channels und cancellationPolicyId; ohne code schlägt die Plattform einen aus dem Namen vor. Eine neue Stornobedingung braucht name und rules.

# Stornobedingung anlegen: kostenlos bis 14 Tage vor Anreise, danach 50 %, in den letzten 3 Tagen 100 %
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c2a8e-7b1d-4c59-a2f0-9d4e1b7c5a20" \
  -d '{"name":"Flexibel bis 14 Tage",
       "rules":{"beforeArrival":[{"hours":336,"amount":50,"amountType":"percent"},
                                 {"hours":72,"amount":100,"amountType":"percent"}],
                "noShow":{"amount":100,"amountType":"percent"}}}' \
  https://platform.fewocation.de/api/public/v1/cancellation-policies

# { "data": { "id": "<policyId>", "kind": "flexible", … }, "sync": "queued" }

# Rate dazu: 5 % günstiger, mit Frühstück im Preis, auf Booking.com, nur für zwei Apartments
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b9e4d17-52c3-4f8a-b6e1-7a2c9d3f1e55" \
  -d '{"name":"Frühbucher mit Frühstück","channels":["booking"],"cancellationPolicyId":"<policyId>",
       "priceAdjustmentPercent":-5,"mealPlan":"breakfast","minimumStay":2,
       "scope":{"mode":"include","listingIds":["<listingId>","<listingId>"]}}' \
  https://platform.fewocation.de/api/public/v1/rate-plans

# { "data": { "id": "<ratePlanId>", "code": "fruehbucher-mit-fruehstueck", "active": true, … }, "sync": "queued" }

# Rate von den Buchungsportalen nehmen, ohne sie zu löschen
curl -X PATCH -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"active":false}' https://platform.fewocation.de/api/public/v1/rate-plans/<ratePlanId>

# Ist die Änderung angekommen?
curl -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/rate-plans/sync-status

# { "data": { "connected": true, "state": "ok", "requestedAt": "2026-11-12T10:02:11.000Z",
#     "attemptedAt": "2026-11-12T10:03:04.000Z", "succeededAt": "2026-11-12T10:03:19.000Z", "willRetry": false } }

Was eine Änderung auslöst: Nach jedem Speichern sendet die Plattform alle Raten und Stornobedingungen der Organisation neu an die Buchungsportale — etwa eine Minute später, mit bis zu vier Versuchen. Eine aktive Rate wird damit auf ihren Kanälen buchbar, für alle Apartments ihres Geltungsbereichs (Kanäle mit ratePlansSupported: false ausgenommen, siehe unten). Eine geänderte Abweichung ändert den Preis, den Gäste dort sehen. active: false oder DELETE nimmt die Rate von den Portalen. Eine geänderte Stornobedingung gilt für jede Rate, die sie trägt, und für neue Buchungen auf allen ihren Kanälen. Bestehende Buchungen bleiben bestehen. Die Verpflegung wirkt auch im Betrieb: Buchungen auf einer Rate mit Frühstück (includesBreakfast in GET /rate-options) gelten als Frühstücksbuchungen.

sync in der Antwort sagt, was mit der Übertragung geschah: queued (eingereiht), not_connected (die Organisation ist an kein Buchungsportal angebunden — gespeichert, aber nichts zu senden) oder failed (gespeichert, die Übertragung ließ sich nicht einreihen). Ob sie ankam, zeigt GET /rate-plans/sync-status für die ganze Organisation: pending, ok oder error, mit willRetry. Den Fehlertext sieht der Verwalter im Dashboard.

Die Plattform prüft jede Eingabe und antwortet bei einem Verstoß mit 400 und dem Grund im Klartext, zum Beispiel: unbekannter Kanal, Stornobedingung ausgeschaltet oder ohne Zuordnung für einen Kanal mit fester Liste, mehr als drei Stufen, Stufen nicht von früh nach spät, mehr als sieben aktive Bedingungen, Aufpreis ohne Verpflegung, Anreise-Zeitraum zusammen mit „Tage vor Anreise“. Der code einer Rate ist nach der ersten Übertragung fest. Eine Stornobedingung lässt sich nur löschen, solange keine Rate sie benutzt (sonst 409 conflict). rules, prepayment und scope ersetzen jeweils das Ganze; ein unbekanntes Feld lehnt die API ab, statt es still zu übergehen.

Ist dein Schlüssel auf einzelne Apartments begrenzt, schreibst du nur Raten, die ausschließlich für deine Apartments gelten (scope.mode: include mit listingIds aus deinem Bereich, ohne Standorte). Stornobedingungen gelten für die ganze Organisation und brauchen einen Schlüssel ohne Begrenzung. In beiden Fällen antwortet die API sonst mit Status 403.

Kanäle, Verpflegung und Einordnung

GET /rate-options liefert die Werte, die Raten und Stornobedingungen annehmen können — für jede Organisation gleich, du kannst sie zwischenspeichern.

curl -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/rate-options

# { "data": {
#   "channels": [ { "id": "booking", "label": "Booking.com", "requiresRatePlan": true, "ratePlansSupported": true,
#                   "cancellationPolicyMode": "fixed" },
#                 { "id": "airbnb", "label": "Airbnb", "requiresRatePlan": false, "ratePlansSupported": false,
#                   "cancellationPolicyMode": "fixed" }, … ],
#   "mealPlans": [ { "id": "breakfast", "label": "Frühstück", "description": "…", "includesBreakfast": true }, … ],
#   "mealSurchargeUnits": [ { "id": "per_night", "label": "je Nacht" }, { "id": "per_person_per_night", "label": "je Person und Nacht" } ],
#   "cancellationKinds": [ { "id": "flexible", "label": "Kostenlos stornierbar" }, { "id": "non_refundable", "label": "Nicht erstattbar" }, … ],
#   "priceKinds": [ … ], "amountTypes": [ … ], "scopeModes": [ … ],
#   "limits": { "maxActiveCancellationPolicies": 7, "maxBeforeArrivalTiers": 3 } } }

Die Portale heißen wie channel an einer Buchung (booking, airbnb, vrbo, expedia), dazu kommen agoda, marriott, trip, reconline, holidu und die drei Direktkanäle direct_onsite, direct_phone und direct_email. Ein unbekannter Name in channels gibt 400. Die Liste nennt alle Werte, die die API kennt; an welche Portale deine Apartments angebunden sind, sagt sie nicht.

Bei den Kanälen sagt requiresRatePlan, ob sich der Kanal erst mit mindestens einer aktiven Rate freischalten lässt. ratePlansSupported: false heißt: Der Kanal führt keine eigenen Raten und verkauft zum Tagespreis — eine Rate wird dorthin nicht übertragen, auch wenn der Kanal in channels steht. cancellationPolicyMode sagt, wie der Kanal Stornobedingungen nimmt: own und custom übernehmen deine Regeln, fixed nimmt nur Bedingungen aus seiner eigenen Liste — dafür braucht die Stornobedingung eine Zuordnung in channelPolicies, sonst lehnt die Plattform die Rate für diesen Kanal ab. limits nennt die Grenzen der Buchungsportale: höchstens sieben aktive Stornobedingungen und drei Stufen vor Anreise.

Raten aus einem angebundenen PMS

Führt der Verwalter Apartments in einem angebundenen PMS, pflegt er deren Raten dort. GET /rate-plans/pms zeigt, welche dieser Raten die Plattform an Buchungen gesehen hat: Kanal, Name und ob der Verwalter die Rate als „mit Frühstück“ eingestuft hat. Gleicher Name auf demselben Kanal ist dieselbe Rate. channel ist hier der Name aus dem PMS (zum Beispiel bookingCom), nicht der Kanal-Name der eigenen Raten (booking).

curl -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/rate-plans/pms

# { "data": [ { "id": "…", "channel": "bookingCom", "name": "Not refundable - Mit Frühstück",
#     "includesBreakfast": true, "classifiedAt": "2026-07-02T08:15:00+00:00",
#     "firstSeenAt": "2026-06-11T04:00:12+00:00", "lastSeenAt": "2026-11-11T22:10:40+00:00" } ],
#   "nextCursor": null }

Diese Raten sind nur lesbar. Nennst du eine ihrer IDs bei PATCH oder DELETE /rate-plans/{id}, antwortet die API mit 409 pms_managed.

Aktionen

Eine Aktion ist ein Rabatt auf den Buchungsportalen: Frühbucher, Last Minute, Mobil-Preis, Länderpreis und ähnliche. Sie hat einen Namen, einen Rabatt in Prozent, Zeiträume und Bedingungen, eine Auswahl Apartments (listingIds) und je Portal genau eine Aktionsart (channels). Es sind dieselben Aktionen wie im Dashboard unter Kalender & Preise → Aktionen. Rabattcodes deiner Direktbuchungsseiten gehören nicht dazu.

# Alle aktiven Aktionen, die für ein Apartment bei Booking.com gelten
curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/promotions?status=active&listingId=<listingId>&channel=booking"

# { "data": [ { "id": "…", "name": "Sommer-Frühbucher", "status": "active", "stayPhase": "upcoming",
#     "discountPercent": 15, "stayFrom": "2027-06-01", "stayTo": "2027-08-31",
#     "bookFrom": null, "bookTo": null, "leadDays": 60, "minNights": 3, "maxNights": null,
#     "excludedDates": [], "additionalDates": [], "weekdays": [],
#     "nonRefundableOnly": false, "allowNoCreditCard": false, "expediaCode": null,
#     "channels": [ { "channel": "booking", "channelName": "Booking.com", "type": "early_booker",
#                     "typeLabel": "Frühbucher", "target": null, "rateplanIds": [],
#                     "transfer": "sent", "error": null } ],
#     "listingIds": ["…", "…"],
#     "createdAt": "2026-11-12T09:30:00+00:00", "updatedAt": "2026-11-12T09:30:00+00:00",
#     "lastSentAt": "2026-11-12T09:30:04+00:00" } ],
#   "nextCursor": null }

GET /promotions liefert die Aktionen seitenweise, sortiert nach id, mit den Filtern status, listingId, channel und type. Zeiträume nennen beide Grenzen inklusive. status ist active oder inactive; stayPhase sagt unabhängig davon, wo der Aufenthaltszeitraum heute steht: running, upcoming, past oder open (kein Zeitraum). Eine abgelaufene Aktion erkennst du also an stayPhase: past. Einen Filter updatedSince gibt es hier nicht — die Liste ist kurz, gleich sie ganz ab.

transfer je Portal sagt, ob die Plattform die Aktion übergeben hat: sent, failed (error trägt dann einen festen Hinweistext, zum Lesen und nicht zum Auswerten) oder not_sent. Ob sie beim Portal wirklich steht, sagt der Abschnitt „Stand bei den Portalen“. Portale heißen wie channel an einer Buchung: booking, airbnb, vrbo, expedia, dazu marriott. Die Liste nennt alle Werte, die die API kennt; an welche Portale deine Apartments angebunden sind, sagt sie nicht.

Ist dein Schlüssel auf einzelne Apartments begrenzt, siehst und änderst du nur Aktionen, deren Apartments alle in deinem Bereich liegen. Eine Aktion, die auch für andere Apartments gilt, siehst du nicht — auch dann nicht, wenn sie den Preis eines deiner Apartments senkt. Brauchst du diese Sicht, nimm einen Schlüssel ohne Begrenzung.

Aktionsarten

Jedes Portal kennt eigene Aktionsarten mit eigenen Regeln. GET /promotion-types nennt sie je Portal: die Kennung (type), den erlaubten Rabatt, Pflichtfelder (requiresStayDates, requiresLeadDays) und welche Bedingungen die Art annimmt (allows…). Die Liste kommt live aus der Anbindung der Portale und kann sich ändern — lies sie, bevor du eine Aktion anlegst, und merk dir die Kennungen nicht fest ein. Es gibt nur Rabatte in Prozent.

curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/promotion-types?channel=booking"

# Die Werte hier sind ein Beispiel — maßgeblich ist, was deine Antwort nennt.
# { "data": [ { "channel": "booking", "channelName": "Booking.com", "types": [
#     { "type": "early_booker", "label": "Frühbucher", "description": "Für Gäste, die früh im Voraus buchen.",
#       "fixedDiscountPercent": null, "minDiscountPercent": 1, "maxDiscountPercent": 99,
#       "requiresStayDates": false, "requiresLeadDays": true,
#       "allowsStayDates": true, "allowsBookDates": true, "allowsMinNights": true, "allowsMaxNights": false,
#       "allowsExcludedDates": true, "allowsAdditionalDates": false, "allowsWeekdays": true,
#       "allowsNonRefundableOnly": true, "allowsNoCreditCard": true, "allowsRateplans": true,
#       "targetOptions": [] },
#     { "type": "new_property_deal", "label": "Neueröffnung", "fixedDiscountPercent": 20, … } ] } ] }

Hat eine Art einen festen Rabatt (fixedDiscountPercent), gilt er an diesem Portal statt deines discountPercent. Nennt sie targetOptions, braucht sie target mit einem dieser Werte. Ein Feld, das eine Art nicht annimmt (allows…: false), darfst du trotzdem senden — es geht an dieses Portal nur nicht hinaus. Dazu drei Regeln der Portale: expedia braucht expediaCode (den sehen Gäste), Airbnb Last Minute höchstens 28 Tage in leadDays, Airbnb Frühbucher Vielfache von 28 oder 30 Tagen.

Aktionen anlegen und ändern

Eine aktive Aktion senkt Preise wirklich. POST /promotions legt die Aktion an und sendet sie sofort an die gewählten Portale; sobald ein Portal sie übernommen hat, sehen Gäste dort den niedrigeren Preis und buchen zu ihm. Ohne status startet die Aktion aktiv, mit status: inactive legst du sie ausgeschaltet an. Der Kopf Idempotency-Key ist Pflicht und wirkt wie bei POST /reservations: Eine wiederholte Anfrage legt keine zweite Aktion an.

# Frühbucher bei Booking.com und Airbnb für zwei Apartments, sofort aktiv
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1c2e-8a57-4d0b-9c1e-5b7a2f4d9e10" \
  -d '{"name":"Sommer-Frühbucher","discountPercent":15,
       "stayFrom":"2027-06-01","stayTo":"2027-08-31","leadDays":60,"minNights":3,
       "channels":[{"channel":"booking","type":"early_booker"},
                   {"channel":"airbnb","type":"basic_early_bird"}],
       "listingIds":["<listingId>","<listingId>"]}' \
  https://platform.fewocation.de/api/public/v1/promotions

# { "data": { "id": "…", "status": "active", "channels": [
#       { "channel": "booking", "transfer": "sent", "error": null, … },
#       { "channel": "airbnb", "transfer": "failed",
#         "error": "Die Übertragung an das Portal ist fehlgeschlagen.", … } ], … },
#   "warnings": [ "Airbnb: Die Übertragung an das Portal ist fehlgeschlagen." ] }

# Rabatt senken — nur das genannte Feld ändert sich, die Aktion geht erneut an die Portale
curl -X PATCH -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"discountPercent":10}' https://platform.fewocation.de/api/public/v1/promotions/<id>

# Beenden oder pausieren, später wieder starten
curl -X POST -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/promotions/<id>/deactivate
curl -X POST -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/promotions/<id>/activate

Die Plattform prüft vor dem Senden Rabatt, Zeiträume und Pflichtfelder jeder gewählten Art und antwortet bei einem Verstoß mit 400 und dem Grund — dann ist nichts gespeichert. Lehnt erst ein Portal ab, ist die Aktion trotzdem gespeichert und bei den übrigen Portalen aktiv: Das betroffene Portal steht mit transfer: failed in channels und mit einer Zeile in warnings. Prüf deshalb nach jedem Schreiben warnings. Die genaue Meldung des Portals nennt die API nicht — sie steht im Dashboard an der Aktion (Kalender & Preise → Aktionen). Beheb die Ursache und sende die Aktion mit PATCH erneut.

PATCH /promotions/{id} ändert nur die genannten Felder; null leert ein Feld. channels und listingIds ersetzen jeweils die ganze Liste. Fällt ein Portal weg oder wechselt seine Art, schaltet die Plattform die bisherige Aktion dort aus und legt für die neue Art eine neue an. Den Stand ändert PATCH nicht: POST …/deactivate schaltet die Aktion bei allen Portalen aus — so beendest oder pausierst du sie —, POST …/activate wieder ein. Löschen gibt es nicht; eine ausgeschaltete Aktion bleibt mit status: inactive stehen. Ist der Aufenthaltszeitraum vorbei, setz vor dem Einschalten neue Daten.

Aktionen wirken nur für Apartments, die über die Plattform an die Buchungsportale angebunden sind. Nennst du ein anderes, antwortet die API mit 409 pms_managed und zählt die Apartments auf; ausschalten geht immer. Und Vorsicht vor doppelten Rabatten: Aktionen, die jemand direkt im Extranet eines Portals angelegt hat, kennt die Plattform nicht — dort kann ein zweiter Rabatt laufen, den du über die API nicht siehst. Ein unbekanntes Feld lehnt die API mit 400 ab, statt es still zu übergehen.

Stand bei den Portalen

transfer: sent heißt nur, dass die Plattform die Aktion übergeben hat. Ob sie an einem Apartment beim Portal steht, fragt GET /promotions/{id}/delivery?listingId=… live ab — je Apartment, weil ein Portal eine Aktion für ein Apartment annehmen und für ein anderes noch prüfen kann. Der Aufruf dauert länger als die übrigen; frag ihn nach dem Anlegen gezielt ab, nicht in einer Schleife über alle Apartments.

curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/promotions/<id>/delivery?listingId=<listingId>"

# { "data": { "promotionId": "…", "listingId": "…", "status": "active", "channels": [
#     { "channel": "booking", "channelName": "Booking.com", "state": "arrived" },
#     { "channel": "airbnb", "channelName": "Airbnb", "state": "channel_off" } ] } }

state je Portal: arrived (steht beim Portal), pending (gesendet, vom Portal noch nicht bestätigt), channel_off (das Portal ist an diesem Apartment nicht freigeschaltet, die Aktion kann dort nicht ankommen), not_sent (noch nicht gesendet oder das Senden ist gescheitert, siehe transfer und error an der Aktion) und not_connected (das Apartment ist nicht über die Plattform an die Portale angebunden). arrived an einer ausgeschalteten Aktion heißt nicht, dass sie läuft — dafür zählt status.

Rechnungen lesen

GET /invoices liefert die Rechnungen der Organisation, sortiert nach updatedAt — gleich du mit updatedSince ab, bekommst du jede Änderung, auch Stornos. Eine Rechnung hat einen von vier Ständen: draft (Entwurf, noch änderbar), sent (ausgestellt), paid (bezahlt) und cancelled (storniert). „Überfällig“ ist kein eigener Stand: overdue ist true, wenn eine ausgestellte Rechnung nicht bezahlt und ihre Fälligkeit vorbei ist; mit ?overdue=true filterst du danach.

# Alle überfälligen Rechnungen
curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/invoices?overdue=true"

# Was sich seit dem letzten Lauf geändert hat
curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/invoices?updatedSince=2026-11-01T00:00:00Z"

# { "data": [ { "id": "…", "number": "RE-2611-014", "kind": "invoice", "status": "sent", "overdue": true,
#     "invoiceDate": "2026-11-02", "dueDate": "2026-11-09", "currency": "EUR",
#     "totals": { "netCents": 46729, "vatCents": 3271, "grossCents": 50000 },
#     "items": [ { "description": "Übernachtung 11.10. – 14.10.2026", "details": null, "quantity": 3,
#                  "unitPriceNetCents": 14019, "vatRate": 7, "netCents": 42057 }, … ],
#     "issuer": { "name": "Muster Ferienwohnungen GmbH" },
#     "recipient": { "name": "Bodenhaus GmbH", "street": "Weg 1", "zip": "12345", "city": "Ort",
#                    "country": "Deutschland", "email": "buchhaltung@example.com", "vatId": null },
#     "listingId": "…", "reservationIds": ["…"], "sentAt": "2026-11-02T09:12:00+00:00", "paidAt": null, … } ],
#   "nextCursor": null }

# Das PDF: erst den Link holen, dann laden (der Link braucht keinen Schlüssel)
curl -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/invoices/<id>/document
# { "data": { "url": "https://…/Rechnung-RE-2611-014.pdf?token=…", "fileName": "Rechnung-RE-2611-014.pdf",
#             "contentType": "application/pdf", "expiresAt": "2026-11-12T10:30:00.000Z", "validMinutes": 30 } }

Alle Beträge sind ganze Cent. totals sind die Summen, wie sie auf der Rechnung stehen; jede Position nennt ihren Betrag in netCents. Eine Stornorechnung ist selbst eine Rechnung mit eigener Nummer (kind: "cancellation", Beträge negativ) und verweist mit cancelsInvoiceId auf das Original; das Original nennt sie in cancellation.cancellationInvoiceId. listingId und reservationIds sagen, zu welchem Apartment und welchen Buchungen die Rechnung gehört.

issuer.name ist, wer ausstellt: die Organisation oder — je nach Vermietungsart des Apartments — der Eigentümer. Anschrift, Steuerangaben und Bankverbindung des Ausstellers stehen im PDF, nicht in der Antwort. GET /invoices/{id}/document gibt einen Link zum PDF zurück; es ist eine E-Rechnung im Format ZUGFeRD/Factur-X, die XML ist eingebettet. Der Link gilt 30 Minuten und braucht keinen Schlüssel — gib ihn nicht weiter. Ist dein Schlüssel auf Apartments begrenzt, siehst du nur Rechnungen, die einem dieser Apartments zugeordnet sind.

Rechnungen anlegen, senden, stornieren

POST /invoices legt einen Entwurf an und vergibt die laufende Rechnungsnummer. Du nennst Empfänger und Positionen (Einzelpreis netto in Cent, Mehrwertsteuersatz in Prozent); die Summen rechnet die Plattform. Mit reservationId oder listingId hängt die Rechnung an Buchung und Apartment. Das Apartment entscheidet auch, wer ausstellt — die Organisation oder der Eigentümer — und welche Rechnungsvorlage (Logo, Farben) gilt. Ohne Apartment stellt die Organisation aus.

# 1. Entwurf anlegen
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1d0c1e-2a54-4f0b-8f43-5a1b9c0d2e11" \
  -d '{"reservationId":"<id oder Buchungscode>",
       "recipient":{"company":"Bodenhaus GmbH","street":"Weg 1","zip":"12345","city":"Ort","email":"buchhaltung@example.com"},
       "items":[{"description":"Übernachtung 11.10. – 14.10.2026","quantity":3,"unitPriceNetCents":14019,"vatRate":7},
                {"description":"Endreinigung","unitPriceNetCents":4672,"vatRate":7}],
       "serviceDescription":"11.10. – 14.10.2026","dueDate":"2026-11-26"}' \
  https://platform.fewocation.de/api/public/v1/invoices

# { "data": { "id": "…", "number": "RE-2611-015", "status": "draft", … } }

# 2. Senden — ohne Inhalt an die E-Mail-Adresse des Empfängers
curl -X POST -H "Authorization: Bearer fw_…" -H "Idempotency-Key: <neuer Wert>" https://platform.fewocation.de/api/public/v1/invoices/<id>/send
# { "data": { "status": "sent", "sentAt": "…", … }, "sentTo": "buchhaltung@example.com" }

# 3. Zahlungseingang festhalten
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"paidOn":"2026-11-20"}' https://platform.fewocation.de/api/public/v1/invoices/<id>/mark-paid

# Stornieren: Es entsteht eine Stornorechnung
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: <neuer Wert>" -d '{"reason":"Falsche Rechnungsadresse"}' https://platform.fewocation.de/api/public/v1/invoices/<id>/cancel
# { "data": { "number": "RE-2611-015", "status": "cancelled", … },
#   "cancellation": { "number": "ST-RE-2611-015", "kind": "cancellation", "totals": { "grossCents": -50000, … }, … } }

Solange die Rechnung ein Entwurf ist, änderst du sie mit PATCH /invoices/{id}. Ausgestellt wird sie mit POST …/send (E-Mail mit PDF an den Empfänger, über den Absender der Organisation für Rechnungen) oder mit POST …/mark-sent, wenn sie auf anderem Weg hinausgeht. Danach ist sie unveränderlich: Ein Fehler wird mit POST …/cancel storniert — es entsteht eine Stornorechnung — und die richtige Rechnung neu angelegt. Nennst du dabei replacesInvoiceId, steht der Verweis auf die stornierte Rechnung auf der neuen, und sie hängt an denselben Buchungen. Versendet wird beim Stornieren nichts; die Stornorechnung schickst du mit POST /invoices/{id der Stornorechnung}/send.

Anlegen, Senden, „als versendet markieren“ und Stornieren verlangen den Kopf Idempotency-Key: ein eigener, eindeutiger Wert je Vorgang. Kommt keine Antwort, schickst du dieselbe Anfrage mit demselben Wert noch einmal und bekommst die erste Antwort — keine zweite Rechnung, keine zweite Mail (24 Stunden lang). Derselbe Wert für einen anderen Vorgang antwortet mit 409 idempotency_key_reused. Geht etwas fachlich nicht — einen Entwurf stornieren, eine ausgestellte Rechnung ändern, eine stornierte senden —, antwortet die API mit 409 conflict und nennt den Grund in message.

POST …/mark-paid hält nur den Zahlungseingang fest, Geld bewegt die API nicht. Das geht auch bei einem Entwurf (etwa wenn das Buchungsportal schon eingezogen hat) — er ist danach nicht mehr änderbar. In einem Demo-Konto geht keine Mail hinaus; sie landet im Postausgang.

Zahlungserinnerung

POST /invoices/{id}/reminders schickt dem Kunden eine Zahlungserinnerung mit der Rechnung als PDF — dieselbe Mail wie „Mahnung senden“ im Dashboard, über den Absender der Organisation für Rechnungen. Ohne Inhalt geht sie an die E-Mail-Adresse des Kunden der Rechnung; mit to und cc nennst du andere Adressen.

# Alle überfälligen Rechnungen holen und je eine Erinnerung senden
curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/invoices?overdue=true"

curl -X POST -H "Authorization: Bearer fw_…" -H "Idempotency-Key: 5d2f8a0e-91b4-4a8e-b0f6-6c1d3e2a7f44" \
  https://platform.fewocation.de/api/public/v1/invoices/<id>/reminders

# { "data": { "number": "RE-2611-014", "status": "sent", "overdue": true, … },
#   "reminder": { "kind": "payment_reminder", "sentTo": "buchhaltung@example.com",
#                 "sentAt": "2026-11-12T09:30:00.000Z", "overdue": true, "daysPastDue": 3 } }

Erinnern lässt sich an jede ausgestellte, unbezahlte Rechnung (status: "sent"). Überfällig muss sie nicht sein: Ist die Fälligkeit vorbei (overdue: true), nennt die Mail „Fällig seit“ mit dem Datum, sonst erinnert sie ohne Hinweis auf Verzug. Entwürfe, bezahlte und stornierte Rechnungen und Stornorechnungen antworten mit 409 conflict. Es gibt eine Art von Erinnerung, keine Mahnstufen — wie oft und in welchem Abstand du erinnerst, bestimmst du selbst; die Liste dafür liefert GET /invoices?overdue=true.

An der Rechnung ändert sich durch die Erinnerung nichts. Der Verwalter sieht sie im Versand-Verlauf der Rechnung im Dashboard. Der Kopf Idempotency-Key ist Pflicht: Dieselbe Anfrage mit demselben Wert sendet nur einmal.

Gutschriften

„Gutschrift“ meint zwei verschiedene Dokumente, type sagt, welches: correction mindert eine eigene Rechnung, etwa wenn ein Gast einen Teil erstattet bekommt. self_billing ist eine Abrechnungs-Gutschrift: Die Organisation rechnet über die Leistung eines anderen ab und zahlt ihm Geld aus — die Empfehlungsprovision an einen Partner (kind: "referral") oder die Abrechnung an einen Eigentümer (kind: "owner_settlement"). Abrechnungs-Gutschriften hängen an keinem Apartment; ein Schlüssel, der auf Apartments begrenzt ist, sieht sie nicht.

# Die Reinigung einer Rechnung gutschreiben — Booking.com hat sie schon erstattet
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f6f6a0b-3c1c-4b61-9c53-2f5c1f3f7a90" \
  -d '{"invoiceId":"<id der Rechnung>",
       "items":[{"description":"Endreinigung","unitPriceNetCents":4672,"vatRate":7}],
       "refundedVia":"Booking.com"}' \
  https://platform.fewocation.de/api/public/v1/credit-notes

# { "data": { "id": "…", "number": "GS-2611-003", "type": "correction", "kind": "guest_refund", "status": "paid",
#     "totals": { "netCents": 4672, "vatCents": 327, "grossCents": 4999 },
#     "correctsInvoice": { "number": "RE-2611-014", "date": "2026-11-02" }, "reservationIds": ["…"], … } }

# Senden und später als erstattet festhalten
curl -X POST -H "Authorization: Bearer fw_…" -H "Idempotency-Key: <neuer Wert>" https://platform.fewocation.de/api/public/v1/credit-notes/<id>/send
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"paidOn":"2026-11-18"}' https://platform.fewocation.de/api/public/v1/credit-notes/<id>/mark-paid

POST /credit-notes stellt eine Korrektur-Gutschrift aus. Mit invoiceId bezieht sie sich auf eine ausgestellte Rechnung: Empfänger und Buchungen kommen von ihr, und der Bezug steht auf dem PDF und in der E-Rechnung. Ohne Rechnung nennst du die Buchung (reservationId). Die Positionen sind die gutgeschriebenen Beträge, positiv und netto. Eine Gutschrift ist sofort ausgestellt (issued) — einen Entwurf gibt es hier nicht. Dazu entsteht ein offener Erstattungs-Vorgang, den der Verwalter im Dashboard sieht; Geld fließt dadurch nicht.

Ist das Geld zurück, hältst du das mit POST …/mark-paid fest. paidOn ist der Tag der Überweisung: Nach ihm ordnet die Eigentümerabrechnung die Erstattung dem Monat zu. Hat ein Buchungsportal erstattet, nennst du es in refundedVia — schon beim Anlegen oder beim Markieren. Die Gutschrift stellt aus, wer auch die Rechnung ausstellt. Hat das Apartment einen Eigentümer, trägt er die Erstattung in der Eigentümerabrechnung; soll die Verwaltung sie tragen, legt der Verwalter die Gutschrift im Dashboard an.

POST /credit-notes/self-billing stellt eine Abrechnungs-Gutschrift über eine Empfehlungsprovision aus. Du nennst den Leistenden (supplier) mit Anschrift, Steuernummer oder USt-IdNr. und der Angabe, ob er Kleinunternehmer ist, dazu die Positionen. Seine Bankverbindung steht auf dem PDF und kommt in keiner Antwort zurück.

Eigentümer

GET /owners liefert die Eigentümer der Organisation, seitenweise und sortiert nach id. Mit status filterst du nach dem Stand, mit q suchst du: Jedes Wort muss in Vorname, Nachname, Firma, Kurzname oder E-Mail vorkommen. listingIds nennt die Apartments des Eigentümers — die Apartments selbst holst du über /listings. Einen Filter updatedSince gibt es hier nicht; gleich die Liste bei Bedarf ganz ab.

# Alle aktiven Eigentümer, deren Name, Firma oder E-Mail „meier“ enthält
curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/owners?status=active&q=meier"

# { "data": [ { "id": "…", "displayName": "Meier Immobilien GmbH", "firstName": "Jana", "lastName": "Meier",
#     "status": "active", "isBusiness": true, "companyName": "Meier Immobilien GmbH", "vatId": "DE123456789",
#     "email": "jana@example.com", "phone": "+49 170 0000000",
#     "address": { "street": "Hafenweg 3", "zip": "12345", "city": "Musterstadt", "country": "DE" },
#     "hasBankDetails": true, "ibanLast4": "4821", "listingIds": ["…", "…"], … } ],
#   "nextCursor": null }

# Anlegen
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"firstName":"Jana","lastName":"Meier","email":"jana@example.com",
       "address":{"street":"Hafenweg 3","zip":"12345","city":"Musterstadt","country":"DE"}}' \
  https://platform.fewocation.de/api/public/v1/owners

# Ändern: nur die genannten Felder, null leert ein Feld
curl -X PATCH -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"phone":"+49 170 1111111","alias":null}' https://platform.fewocation.de/api/public/v1/owners/<id>

Bankdaten gibt die API nicht aus: hasBankDetails sagt, ob eine Bankverbindung hinterlegt ist, ibanLast4 nennt die letzten vier Stellen der IBAN zum Wiedererkennen. BIC, Kontoinhaber und Steuernummer kommen nie, die Umsatzsteuer-ID (vatId) schon. Schreiben lassen sich Name, Firma, Register, Geschäftsführer, E-Mail, Kopie-Adressen, Telefon und Anschrift — Bankdaten, Steuernummer und status pflegt der Verwalter im Dashboard. Ein unbekanntes Feld lehnt die API mit 400 ab, statt es still zu übergehen.

Gibt es beim Anlegen schon einen Eigentümer mit gleichem Namen oder gleicher E-Mail, antwortet POST /owners mit 409 conflict und nennt dessen id. Ist es wirklich ein weiterer, schick allowDuplicate: true mit. Beim Anlegen geht keine Mail hinaus, und es entsteht kein Portal-Zugang.

Ist dein Schlüssel auf einzelne Apartments begrenzt, siehst du nur Eigentümer, denen mindestens eines dieser Apartments gehört, und in listingIds nur diese. Alle schreibenden Aufrufe in diesem Bereich und die Abrechnung brauchen einen Schlüssel ohne Begrenzung, sonst antwortet die API mit 403 forbidden.

Kontakte eines Eigentümers

Ein Eigentümer kann mehrere Kontaktpersonen haben, zum Beispiel ein Ehepaar. Jede hat ihren Kanal (whatsapp, sms oder email) und kann mit notifyNewBooking eine Meldung bei jeder neuen Buchung bekommen — ohne Beträge und ohne Gastnamen. Kontakte sind nicht die Zugänge zum Eigentümerportal; die stehen unter /owners/{id}/portal.

curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"name":"Tom Meier","phone":"+49 171 2222222","preferredChannel":"whatsapp","notifyNewBooking":true}' \
  https://platform.fewocation.de/api/public/v1/owners/<id>/contacts

# { "data": { "id": "…", "ownerId": "…", "name": "Tom Meier", "phone": "+491712222222", "email": null,
#     "preferredChannel": "whatsapp", "active": true, "notifyNewBooking": true, "aiChatEnabled": false } }

WhatsApp und SMS brauchen phone, der Kanal email braucht email. Telefonnummern speichert die Plattform in der Form +49…. Beim Ändern bleiben fehlende Felder, wie sie sind. aiChatEnabled ist nur lesbar: Ob eine Nummer mit dem KI-Assistenten schreiben darf, entscheidet der Verwalter im Dashboard.

Abrechnung je Eigentümer

GET /owners/{id}/statements liefert je Monat eine Zeile aus der Eigentümer-Abrechnung der Plattform — der Abrechnung, die der Verwalter im Dashboard führt und aus der auch das Eigentümerportal seine Zahlen nimmt. Mit from und to (YYYY-MM, beide inklusive) wählst du den Zeitraum, höchstens 24 Monate; ohne Angabe kommen die letzten zwölf.

curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/owners/<id>/statements?from=2026-09&to=2026-10"

# { "data": [
#   { "ownerId": "…", "month": "2026-09", "closed": true, "closedAt": "2026-10-04T08:12:00+00:00",
#     "billingMode": "creditNote", "stays": 7,
#     "revenueGrossCents": 612400, "revenueNetCents": 566800,
#     "channelCommissionCents": 79300, "paymentFeeCents": 6100,
#     "managerCommissionNetCents": 113300, "managerCommissionVatCents": 21527,
#     "cleaningFeeGrossCents": 49000, "midStayCleaningFeeGrossCents": 0, "localTaxDeductionCents": 0,
#     "ownerPayoutCents": 343173, "dueCents": 343173 },
#   { "month": "2026-10", "closed": false, … } ] }

Woher die Zahlen kommen: Eine Buchung zählt im Monat ihrer Abreise. revenueGrossCents und revenueNetCents sind der Umsatz dieser Buchungen (Übernachtung, Reinigung, Gebühren), channelCommissionCents die Provision der Buchungsportale, paymentFeeCents die Zahlungsgebühren. managerCommissionNetCents rechnet die Plattform mit dem Provisionsplan, der am Abreisetag für das Apartment gilt; ohne geltenden Plan ist sie 0. cleaningFeeGrossCents sind die Reinigungspauschalen, die der Verwalter dem Eigentümer berechnet. ownerPayoutCents ist die Summe der Auszahlungen aus den Buchungen des Monats, dueCents der Betrag, der in diesem Monat fällig ist — mit verschobenen Buchungen, Zusatzposten und Korrekturen. Ein negativer Wert heißt: Der Eigentümer zahlt an die Verwaltung.

closed: true heißt, der Verwalter hat den Monat abgeschlossen — das ist der festgehaltene Stand und ändert sich nicht mehr. Ein offener Monat wird bei jedem Aufruf neu gerechnet und kann sich ändern, etwa wenn ein Portal eine Provision nachmeldet. Verbuche deshalb nur abgeschlossene Monate. Einzelne Buchungen mit ihren Beträgen findest du unter /reservations (Recht finances:read).

Provisionspläne

Ein Provisionsplan hält die Konditionen zwischen Verwalter und Eigentümer: Anteil am Umsatz (revenue_share) oder Festbetrag (flat_fee), die Bemessungsgrundlage (basis), Abzüge (deductions) und die Gültigkeit. assignments nennt die Apartments, für die er gilt, mit der Reinigungspauschale je Apartment. Sätze sind Prozent (20 = 20 %), Beträge Cent. Der Katalog kommt vollständig in einer Antwort.

# Welcher Plan gilt für ein Apartment zur Abreise am 14.02.2027?
curl -H "Authorization: Bearer fw_…" "https://platform.fewocation.de/api/public/v1/commission-plans?listingId=<listingId>&on=2027-02-14"

# { "data": [ { "id": "…", "name": "Hauptlaufzeit", "ownerId": "…", "validFrom": "2026-01-01", "validUntil": null,
#     "active": true, "model": "revenue_share", "commissionRate": 20, "commissionVatRate": 19,
#     "calculationBasis": "gross", "basis": { "nightly": true, "cleaning": false, "localTax": false, "otherFees": false },
#     "deductions": { "platformFees": true, "paymentFees": false }, "commissionOnOwnerStays": false,
#     "flatFee": { "amountCents": null, "perApartment": false, "interval": "monthly", "vatRate": null },
#     "summary": "20 % brutto · MwSt 19 % · …",
#     "assignments": [ { "listingId": "…", "cleaningFeeNetCents": 6500, "cleaningFeeVatRate": 19,
#                        "midStayCleaningFeeNetCents": null, "midStayCleaningFeeVatRate": null } ], … } ],
#   "nextCursor": null }

# Apartment zuordnen, Reinigungspauschale 65 € netto zzgl. 19 %
curl -X PUT -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"cleaningFeeNetCents":6500,"cleaningFeeVatRate":19}' \
  https://platform.fewocation.de/api/public/v1/commission-plans/<planId>/assignments/<listingId>

# { "data": { "id": "…", "assignments": [ … ] }, "created": true }

Die Gültigkeit steht am Plan, nicht an der Zuordnung; zwei Pläne eines Apartments überschneiden sich nie. Der geltende Plan ist deshalb der mit active: true — zum Stichtag on, sonst heute. Für die Abrechnung zählt der Tag der Abreise.

PUT /commission-plans/{id}/assignments/{listingId} ordnet ein Apartment zu oder ändert die Preise einer bestehenden Zuordnung (created: false); der Inhalt darf fehlen. Der Plan muss demselben Eigentümer gehören wie das Apartment. Überschneidet sich seine Gültigkeit mit einem anderen Plan des Apartments, antwortet die API mit 409 conflict. Achtung: Eine Zuordnung wirkt in der Abrechnung auf alle Buchungen in noch offenen Monaten, deren Abreise in die Gültigkeit fällt; hebst du sie mit DELETE auf, rechnet die Plattform für das Apartment keine Provision mehr. Jede Änderung steht im Änderungsprotokoll des Plans. Konditionen anlegen oder ändern geht über die API nicht.

Aufenthalte des Eigentümers

POST /owners/{id}/stays trägt ein, dass der Eigentümer selbst in seinem Apartment wohnt: eine Buchung ohne Geld (kind: owner). Sie belegt den Kalender, geht als Belegung an die Buchungsportale und kann wie jede Buchung einen Reinigungsauftrag auslösen. Automatische Nachrichten an Gäste gehen nicht hinaus.

curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8d1f4c0e-5b7a-4f3d-9a61-2c0e7b5a1f44" \
  -d '{"listingId":"<listingId>","checkIn":"2027-03-05","checkOut":"2027-03-09","guests":2,"note":"Osterputz"}' \
  https://platform.fewocation.de/api/public/v1/owners/<id>/stays

# { "data": { "id": "…", "kind": "owner", "status": "confirmed", "checkIn": "2027-03-05", "checkOut": "2027-03-09", … } }

Das Apartment muss dem Eigentümer gehören, und seinen Kalender muss die Plattform führen — sonst 409 pms_managed. Ist der Zeitraum belegt oder gesperrt, antwortet die API mit 409 not_available. Der Kopf Idempotency-Key ist Pflicht und wirkt wie bei POST /reservations. Die Antwort ist die Buchung; du findest sie danach unter /reservations und stornierst sie mit POST /reservations/{id}/cancel (Recht reservations:write).

Eigentümerportal

Im Eigentümerportal sieht ein Eigentümer seine Apartments, Buchungen und Abrechnungen. GET zeigt, ob es eingeschaltet ist, welche Apartments es zeigt und wer Zugang hat. status eines Zugangs: signed_in (hat sich angemeldet), invite_open, invite_expired, existing_account (hatte schon ein Konto und bekam nur die Login-Adresse), sent, not_invited.

# Stand lesen
curl -H "Authorization: Bearer fw_…" https://platform.fewocation.de/api/public/v1/owners/<id>/portal

# { "data": { "ownerId": "…", "active": false, "listingIds": ["…"],
#     "members": [ { "id": "…", "email": "jana@example.com", "name": "Jana", "status": "invite_open",
#                    "lastInvitedAt": "2026-11-12T09:30:00+00:00", "activatedAt": null,
#                    "inviteExpiresAt": "2026-11-26T09:30:00+00:00" } ] } }

# Einladen (verschickt eine Mail) und das Portal einschalten
curl -X POST -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5a0b9d6e-0c1f-4e55-8b1d-7f3c2a9e6d10" \
  -d '{"email":"jana@example.com","name":"Jana"}' https://platform.fewocation.de/api/public/v1/owners/<id>/portal/invitations
curl -X PATCH -H "Authorization: Bearer fw_…" -H "Content-Type: application/json" \
  -d '{"active":true}' https://platform.fewocation.de/api/public/v1/owners/<id>/portal

POST …/portal/invitations verschickt eine Mail im Namen des Verwalters: Wer noch kein Konto hat, bekommt einen Aktivierungslink (14 Tage gültig), wer schon eines hat, die Login-Adresse. Eine zweite Einladung an dieselbe Adresse entwertet den alten Link. Der Kopf Idempotency-Key ist Pflicht, damit eine wiederholte Anfrage keine zweite Mail auslöst. Die Einladung schaltet das Portal nicht ein — das macht PATCH …/portal mit active. Sichtbar ist das Portal nur für Eigentümer mit dem Stand active. DELETE …/portal/members/{memberId} entzieht einen Zugang ohne Mail; das Konto der Person bleibt bestehen.

Werkzeuge (MCP)

Die Endpunkte oben sind der feste Kern: Sie bleiben stabil. Alles Weitere, was die Plattform kann — Nachrichten, Aufgaben, Rechnungen, Gästemappe, Zugänge und mehr —, steht als Werkzeug über den MCP-Server bereit. Er ist für KI-Assistenten gebaut, lässt sich aber von jedem Programm aufrufen: JSON-RPC 2.0 per POST an /api/mcp.

# Welche Werkzeuge sind erlaubt?
curl -X POST -H "Authorization: Bearer fwoa_…" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://platform.fewocation.de/api/mcp

# Ein Werkzeug aufrufen
curl -X POST -H "Authorization: Bearer fwoa_…" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_apartments","arguments":{}}}' \
  https://platform.fewocation.de/api/mcp

Verbunden wird über die Anmeldung im Browser (OAuth 2.1): Ein Admin der Organisation bestätigt die Verbindung und wählt eine Berechtigung, die festlegt, welche Werkzeuge erlaubt sind. Namen, Eingaben und Ausgaben der Werkzeuge sind für eine KI geschrieben und können sich ändern — bau darauf nur, was du leicht anpassen kannst. Brauchst du etwas davon als festen Endpunkt, sag es uns.

Fehler

Fehler haben immer die Form { "error": { "code", "message" } }. Verzweige auf code; der Text in message ist deutsch und für Menschen.

codeStatusBedeutung
bad_request400Parameter fehlt oder ist ungültig — message sagt, welcher.
unauthorized401Schlüssel fehlt, ist unbekannt, abgelaufen oder deaktiviert.
forbidden403Dem Schlüssel fehlt das Recht für diesen Endpunkt — oder er ist auf einzelne Apartments begrenzt und der Vorgang geht nur ohne Begrenzung (Eigentümer pflegen, Apartment anlegen).
secret_key_in_browser403Der Schlüssel kam aus einem Browser. Er gehört nur auf einen Server.
not_found404Apartment oder Buchung gibt es nicht — auch dann, wenn sie zu einer anderen Organisation gehören.
pms_managed409Schreiben: Kalender, Buchung, Apartment, Rate oder Aktion gehört zu etwas, das in einem angebundenen PMS oder Portal geführt wird — dort ändern.
price_source_conflict409Preis schreiben, obwohl ein Preistool die Preise des Apartments setzt.
block_conflict409Die Sperre wurde nicht über die API angelegt, oder eine weitere Sperre berührt denselben Zeitraum.
not_available409Buchung anlegen: Zeitraum nicht frei oder Apartment nicht in Betrieb.
idempotency_key_reused409Der Idempotency-Key gehört zu einer anderen Anfrage.
request_in_progress409Eine Anfrage mit demselben Idempotency-Key läuft noch oder wurde unterbrochen.
conflict409Der Vorgang passt nicht zum aktuellen Stand — z. B. eine ausgestellte Rechnung ändern, einen Entwurf stornieren oder ein Bild, das sich nicht laden lässt. message nennt den Grund.
rate_limited429Zu viele Anfragen — Retry-After Sekunden warten.
server_error500Bei uns ging etwas schief — kurz warten und erneut versuchen.

Grenzen

Je Schlüssel und Minute: 3.000 Anfragen an Apartments und Buchungen, 1.500 an den Kalender, 120 schreibende Aufrufe. Jede Antwort nennt die Grenze, den Rest und die Sekunden bis zum nächsten Fenster (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset). Darüber antwortet die API mit 429 und Retry-After. Brauchst du dauerhaft mehr, erhöht der FeWocation-Support das Limit der Organisation.

Was noch kommt

Geplant sind das Ändern von Buchungen (Zeitraum, Gäste) und ein Ereignis bei Kalenderänderungen. Fragen oder Wünsche? Support im Dashboard