Swoppen Soferu REST API (1.0)

MCP: POST https://{host}/API/mcp Erfordert die Lizenz Soferu AI. Zugang ist der bestehende API-Host. Authorization: Bearer mit dem API-Schlüssel, oder Basic Auth mit Login und Schlüssel. Werkzeuge sind die REST-Endpunkte, die für diesen Zugang freigeschaltet sind.

API-Changesets (neueste zuerst):

2026-10-08 — Nachrichten: Unterhaltungen und E-Mail

Pfade: /messages, /messages/{thread_key}

• GET /messages listet Unterhaltungen. Filter: source (whatsapp, bookingcom, email, nr), cms_address_id, unread=1.
• GET /messages/{thread_key} liefert den Verlauf. thread_key ist source:contact.
• POST /messages antwortet über denselben Kanal. E-Mail braucht subject und eine Adresse als contact.

2026-10-08 — Tickets: Bearbeiter und Benutzer-Login

Pfade: /tickets/{id}, /users

• Tickets: ohne cms_client_id gilt für diesen Zugang cms_client_id=1. Ein gesetzter Wert bleibt gültig.
• GET /users ignoriert cms_client_id. username filtert den Login exakt, ohne Wildcard. Unbekannt ergibt eine leere Liste und HTTP 200.
• PATCH /tickets/{id} setzt den Bearbeiter über genau eines von bv_user_id oder username. Unbekannter Benutzer: HTTP 404, Ticket unverändert.

2026-10-07 — Tickets: Status und interne Notiz

Pfade: /tickets/{id}

• PATCH /tickets/{sp_ticket_id} setzt status und/oder note. Leere Felder bleiben unverändert.
• status: 1 offen, 2 in Bearbeitung, 3 Wiedervorlage, 4 erledigt, 9 abgelehnt. Erledigt und Abgelehnt setzen das Abschlussdatum.
• note ist eine interne Notiz im Ticketverlauf, höchstens 8000 Zeichen, ohne E-Mail an den Kunden.

2026-10-07 — Dienstplan: wer Schicht hat

Pfade: /shifts

• GET /shifts: geplante Schichten eines Tages, gruppiert nach Tätigkeitsbereich. date ist Y-m-d, Standard heute.
• personnel trägt Name und per_personnel_id. Telefon und E-Mail bleiben draussen. Bewerbungen und Tausch zählen nicht.
• published 0 ist ein Entwurf, 1 ist veröffentlicht.
• Optional per_activity_id und st_branch_id. Nur Lesen. Auth: HostLimitation auf die Schnittstelle shifts.

2026-10-07 — Belegungen: Gäste je Zimmer

Pfade: /bookings/{id}

• GET /bookings/{id}: items[].guests mit Name, Geburtsdatum, Land und Meldeschein-Status.
• Der Bucher bleibt cms_address_id. Die Liste GET /bookings enthält keine Gäste.

2026-10-07 — Tagesboard: Anreisen, Abreisen, im Haus, Bleiber, offene Salden

Pfade: /bookings/dayboard

• GET /bookings/dayboard: Zimmerzeilen eines Tages. date ist Y-m-d, Standard heute.
• arrivals: Anreise an diesem Tag. departures: Abreise an diesem Tag.
• in_house: Übernachtung in dieser Nacht (Anreise am oder vor dem Tag, Abreise danach). stayovers: Bleiber, Anreise vor dem Tag und Abreise danach.
• open_balances: Belegungen aus diesen Listen mit sum_open > 0, einmal je Belegung.
• section liefert nur eine Liste. counts bleibt der ganze Tag. Zähler sind Zimmerzeilen, Personen ist quantity.
• Ohne Storno, No-Show, Sperre und Kontingent. Auth: HostLimitation auf die Schnittstelle bookings.

2026-10-06 — Belege: Anlegen mit Positionen

Pfade: /vouchers

• POST /vouchers legt einen Beleg an. Pflicht: st_customer_id, st_voucher_type_id (Belegart des Mandanten, z. B. Angebot).
• positions[]: Artikelzeile mit st_article_id. Ohne price gilt der Preis der Preisliste, mit price der übergebene Stückpreis in der Preisart der Belegart. Textzeile nur mit text.
• Antwort HTTP 201 mit dem Beleg inklusive positions[]. Die Liste GET /vouchers bleibt auf Rechnungen (Belegstufe 5); andere Belegstufen über GET /vouchers/{vk_voucher_no}.

2026-10-02 — Belegungen: Änderungsdatum

Pfade: /bookings

• GET /bookings: jede Zeile enthält created_date und modified_date der Zimmerzeile (Y-m-d H:i:s).
• created_date und modified_date filtern denselben Kalendertag. Erlaubt ist Y-m-d und TT.MM.JJJJ, optional mit Präfix >=, >, <=, < oder !.

2026-10-01 — Belege: Liste ohne Pflichtfilter

Pfade: /vouchers

• rm_booking_id an GET /vouchers ist optional. Ohne den Parameter kommen die Rechnungen (Belegstufe 5) des Mandanten, paginiert über page und limit (Standard 25, höchstens 250).
• pagination.total ist die Trefferzahl des Filters.

2026-10-01 — Belege: Positionen am Einzelabruf

Pfade: /vouchers/{id}

• GET /vouchers/{vk_voucher_no} liefert positions[] aus den Belegzeilen. Die Liste GET /vouchers bleibt ohne Positionen.
• Jede Zeile trägt Artikel, Menge, Preis, Steuer und Summe. vk_position_pool_id verweist auf die Leistung, aus der die Zeile entstanden ist. kind ist A für Artikel und T für Text.

2026-10-01 — Belegungen: Leistungen und Dokumente

Pfade: /bookings/{id}/services, /bookings/{id}/documents

• GET /bookings/{id}/services ist ein Alias für GET /services und liefert die Leistungen dieser Belegung.
• GET|POST /bookings/{id}/documents hängt ein PDF (höchstens 2 MB) an die Dokumente der Belegung.

2026-10-01 — Dokumente: PDF an Belegung

Pfade: /documents, /documents/{id}, /bookings/{id}/documents

• POST /documents speichert ein PDF (Base64, höchstens 2 MB). Für Belegungen: cms_object=rm_booking_id, Datei unter Dokumente der Belegung.
• Alias: POST /bookings/{id}/documents und GET /bookings/{id}/documents.
• request_id ist die Id dieser Anfrage im Zugriffsprotokoll.

2026-10-01 — Leistungen: Abfrage, external_id, Formate

Pfade: /services, /bookings/{id}/services

• GET /services liest Leistungen einer Belegung oder Zimmerposition, einschließlich noch nicht abgerechneter (vk_voucher_no leer). Alias: GET /bookings/{id}/services.
• external_id (max. 50 Zeichen) wird an der Leistung gespeichert. Dieselbe Id legt keine zweite Leistung an und liefert die ursprüngliche vk_position_pool_id (idempotent: true, HTTP 200).
• Menge und Preis akzeptieren Punkt und Dezimalkomma. price ist der Stückpreis in der Preisart des Mandanten. Gespeichert wird auf vier Nachkommastellen gerundet.
• Check-out sperrt die Buchung nicht. warning ist gesetzt, wenn die Zimmerposition bereits ausgecheckt ist.
• Antwort enthält request_id für das Zugriffsprotokoll.

2026-09-17 — FiBu Export: DATEV-Paket Buchungssätze + Belegbilder

Pfade: /fibu/export

• Neues Format datev_both: ein ZIP mit Buchungsstapel.zip und Belege.zip.
• Erlaubte format-Werte: datev, datev_xml, datev_both, diamant.

2026-09-08 — Tisch-Reservierungen

Pfade: /tables, /tables/{id}, /tables/{id}/checkin, /tables/{id}/checkout

• GET/POST /tables: Liste und Anlegen von Tisch-Reservierungen (Katalog TR).
• from/until als DateTime. Ohne until gilt die Reservierungsdauer aus den TR-Einstellungen.
• Ohne rm_resource_id wird ein freier Tisch im Zeitraum zugeordnet (HTTP 409 wenn keiner frei ist).

2026-09-02 — Resources: gesperrte Zeiträume in der Occupancy

Pfade: /resources, /resources/{id}

• Occupancy: is_locked (1 = gesperrter Zeitraum, kein Gast). note ist dann der Sperrgrund.
• Sperren ohne Belegungskopf erscheinen in der Occupancy (LEFT JOIN auf Belegungen).

2026-09-02 — Belegungen: gesperrte Zeiträume

Pfade: /bookings, /bookings/{id}

• GET /bookings listet keine gesperrten Zeiträume (is_locked=1).
• POST /bookings mit konkretem Zimmer: HTTP 409 wenn das Zimmer im Zeitraum gesperrt oder belegt ist.

2026-09-02 — Gesperrte Zeiträume: Liste, Anlegen, Ändern, Löschen

Pfade: /locked-ranges, /locked-ranges/{id}

• GET /locked-ranges: Sperren ab heute, optional date_from / date_until / rm_resource_id.
• POST /locked-ranges: anlegen. Pflicht: rm_resource_id (oder Array), from, until. Optional note, color. Mehrere Zimmer in einem Request.
• POST/PATCH / DELETE /locked-ranges/{rm_item_id}: ändern bzw. löschen.
• Kollision mit Belegung oder anderer Sperre: HTTP 409. Auth: HostLimitation auf die Schnittstelle locked-ranges.

2026-09-02 — Verfügbarkeit: rooms_ooo für gesperrte Zeiträume

Pfade: /availability

• rooms_ooo: Anzahl gesperrter Zimmer (is_locked) je Tag und Kategorie. Teilmenge von rooms_booked.
• closed bleibt Stop-Sell auf der Preisliste, unabhängig von Zimmersperren.

2026-09-02 — Belege: Liste, Einzelabruf und Teilzahlungen

Pfade: /vouchers, /vouchers/{id}, /vouchers/{id}/payment

• GET /vouchers?rm_booking_id=: Rechnungen (Belegstufe 5) einer Belegung. rm_booking_id ist Pflicht.
• GET /vouchers/{vk_voucher_no}: Beleg inkl. payments[].
• POST /vouchers/{vk_voucher_no}/payment: (Teil-)Zahlung. amount ist Pflicht und darf sum_opened nicht überschreiten. Mehrere Zahlungen pro Rechnung möglich.
• Dieselbe reference wird nicht erneut gebucht (HTTP 200). Auth: HostLimitation auf die Schnittstelle vouchers.

2026-09-02 — Belegungen: Rechnung, Teilzahlung und offener Betrag

Pfade: /bookings/{id}, /bookings/{id}/invoice, /bookings/{id}/payment

• GET /bookings/{id}: amount_due (nicht fakturierte Positionen plus offene Rechnungsbeträge) und invoices[].
• POST /bookings/{id}/invoice: Rechnung über noch nicht abgerechnete Positionen (idempotent).
• POST /bookings/{id}/payment: (Teil-)Zahlung auf die offene Rechnung. amount ist Pflicht und darf sum_opened nicht überschreiten. Bevorzugt: POST /vouchers/{vk_voucher_no}/payment.
• book_payment=1 beim Rechnung anlegen: ebenfalls amount Pflicht. Dieselbe reference verhindert Doppelbuchungen.

2026-09-02 — Resources: optionaler Benutzer und Reinigungsstatus-Historie

Pfade: /resources, /resources/{id}

• POST /resources/{id}: optionales bv_user_id für Historie (created_from).
• Resource-Antwort: cleaning_changed_by, cleaning_changed_by_name, cleaning_changed_at.

2026-09-02 — Benutzer: Liste und Einzelabruf

Pfade: /users, /users/{id}

• GET /users und GET /users/{id}: Benutzer des Mandanten (ohne Passwort/Rechte).
• Standard nur aktive. Filter: is_active (1, 0, all) oder include_disabled=1.

2026-08-28 — FiBu Export: lock-Parameter und festgeschriebene Belege

Pfade: /fibu/export

• lock=true wirkt wie lock=1; false/0 bleibt aus. Ungültige Werte liefern HTTP 400 (kein stiller Erfolg mehr).
• Response: locked (boolean), locked_count (Anzahl) und locked_vouchers (Liste der tatsächlich festgeschriebenen Belege mit type und voucher_no).