Webklar-Kundenbereich/docs/funktionen/unterkunft-einbau.md

Buchungskalender auf der Kundenwebsite einbauen

Anleitung für das WEBklar-Team. Das Widget lässt Besucher auf der Website des Kunden („Vermieter“) einen Zeitraum im Kalender wählen und eine unverbindliche Anfrage senden. Unterkünfte, Preise, Anfragen, Rechnungen und die Verbindung zu Stripe pflegt der Vermieter im Kundenportal (Tab „Funktionen“, Kachel „Buchungskalender“, Reiter „Buchungen“). Den siteKey (16 Zeichen, a–z und 2–7) findest Du im Einrichtungs-Ticket und im Ticketsystem (WOMS): Kunde → Reiter „Funktionen“, Zeile Buchungskalender. Im Ticket stehen Snippet und Schritte schon fertig; dieses Dokument ist die Referenz dahinter. Ohne aktive Funktion oder ohne freigeschaltete Unterkunft ist nichts buchbar: Das Widget zeigt dann den Ausweichtext (Abschnitt 4). API-Vertrag: docs/funktionen/unterkunft-api.md.

Der Buchungskalender ist an den Vertrag über den Betrieb der Website gekoppelt (Leistungsbeschreibung Buchungskalender Nr. 10), aber nicht in der Software: Das Portal schaltet ihn nicht von selbst ab. Das Abschalten zum Vertragsende machen wir von Hand (Abschnitt 8).

1. Das Snippet

<div data-webklar-unterkunft="SITEKEY" data-api="https://project.webklar.com">
  <p>Der Buchungskalender ist gerade nicht erreichbar. Bitte schreiben Sie uns: info@beispiel.de</p>   <!-- Ausweichtext, Abschnitt 4 -->
</div>
<script src="https://project.webklar.com/embed/unterkunft.js" defer></script>

Das Skript steht einmal pro Seite, vor </body>. Es hat keine Abhängigkeiten, setzt keine Cookies, lädt nichts von Dritten und fragt nur project.webklar.com an. Texte des Vermieters setzt das Skript nur als Text ein, nie als HTML. Das Widget rechnet nie selbst: Preise, Summen und belegte Nächte kommen fertig vom Server (die Anfrage ist unverbindlich; der Preis wird erst bei der Freigabe festgelegt).

Attribut	Pflicht	Bedeutung
data-webklar-unterkunft	ja	der siteKey des Projekts
data-api	nein	Herkunft des Portals, Standard https://project.webklar.com. Bei Modul-Import, Tag-Manager oder nachgeladenem Skript ist data-api Pflicht.

2. Wohin damit

1. Auf der Seite einen Bereich „Anfrage“ (Anker #anfrage oder eine eigene Seite) anlegen und das Snippet an die Stelle des Formulars setzen. Ein bisheriges Anfrageformular wird ersetzt; Telefon und E-Mail des Vermieters stehen unter dem Kalender. Das div braucht Breite (normaler Blockcontainer; in einem Flex- oder Grid-Element ohne Breite schrumpft es auf null).
2. Layout: Das Widget zeigt zwei Spalten (Kalender links, Formular rechts) und unter 760 px Breite beide untereinander; der Kalender zeigt einen Monat, ab 1100 px Breite zwei.
3. Menüpunkt oder Knopf „Anfragen“ auf den Bereich verlinken.
4. Mehrere Widgets auf einer Seite sind nicht vorgesehen. Der Buchungskalender ist ein Widget je Website; mehrere Unterkünfte wählt der Gast im Widget (bei nur einer Unterkunft entfällt die Auswahl).

Aussehen: Das Widget nimmt die Akzentfarbe aus den Einstellungen des Vermieters. Die Stile stehen in @layer wku, jede Regel der Kundenseite gewinnt also. Anpassen per CSS-Variablen auf dem div, in der Seiten-CSS oder auf :root, zum Beispiel [data-webklar-unterkunft]{ --wku-akzent:#8a5a2b; --wku-akzent-text:#fff; }:

Variable	Standard
--wku-akzent und --wku-akzent-text (Auswahl, Knöpfe; setze beide zusammen)	Akzentfarbe des Vermieters, sonst Standardblau und #fff
--wku-hintergrund	#fff
--wku-text	#1f2937
--wku-rand	#858f9e
--wku-radius	10px
--wku-schrift, --wku-schrift-titel	Schrift der Seite

Kontrast (WCAG 2.1 AA): Text auf dem Hintergrund und Schrift auf dem Akzent mindestens 4,5 : 1, Rand gegen den Hintergrund mindestens 3 : 1. Prüfe beim Abnehmen, ob globale Regeln des Themes (button{…}, input{…}) das Widget stören, und überschreibe sie gezielt ([data-webklar-unterkunft] .wku-btn{ … }).

3. Datenschutz-Absatz (Pflicht vor dem Einbau)

Bau das Widget erst ein, wenn der Absatz aus docs/funktionen/unterkunft-datenschutz-absatz.md in der Datenschutzerklärung der Website steht. Liegt sie in der Website, die WEBklar betreut, fügst Du ihn ein (gehört zur Einrichtung), Platzhalter und nicht Zutreffendes angepasst. Liegt sie woanders, schickst Du ihn dem Vermieter im Chat (Leistungsbeschreibung Nr. 5 Abs. 10). Dasselbe gilt für Impressum und Verlinkung der Datenschutzerklärung: Die Adresse der Datenschutzerklärung trägt der Vermieter in den Einstellungen ein; das Widget und die Buchungsseite verlinken sie.

4. Ausweichtext

Der Inhalt des div bleibt stehen, solange das Widget nicht lädt oder die Funktion nicht aktiv ist (zum Beispiel vor der Freischaltung, bei UNTERKUNFT_ENABLED=off, bei Wartung). Schreib dort Kontaktdaten des Vermieters hinein, damit niemand ohne Möglichkeit zur Anfrage bleibt. Ein aktives Widget ersetzt den Inhalt.

5. Vor der Abnahme prüfen

• Im Portal: mindestens eine aktive Unterkunft mit Preisen und Stornobedingungen, Firmendaten vollständig, Steuernummer oder USt-ID, Steuerart gewählt. Sonst ist die Funktion nicht freischaltbar.
• Der Datenschutz-Absatz steht in der Datenschutzerklärung.
• Auf dem Handy und am Desktop: Anreise und Abreise wählbar, belegte Nächte nicht wählbar, Mindestnächte und Höchstzahl der Personen werden geprüft, Anfrage senden zeigt die Nummer.
• Tastatur: Pfeiltasten im Kalender, Enter wählt; jeder Tag hat ein aria-label mit Datum und Status.
• Kein Konflikt mit globalen Stilen des Themes (Abschnitt 2).
• Testanfrage mit eigener Adresse: E-Mail G16 (Eingang) beim Gast, K36 beim Vermieter.

6. Vorschau und Testanfrage

1. Vorschau-Subdomain des Projekts (<subdomain>.project.webklar.com) ansehen.
2. Anfrage senden, im Portal unter „Buchungen → Anfragen“ öffnen, Preis prüfen, Freigeben (E-Mail G17 mit Buchungslink).
3. Buchungslink öffnen: Rechnungsadresse eintragen, Zahlart „vor Ort“ wählen, „Zahlungspflichtig buchen“. E-Mail G19 mit Rechnungs-PDF prüfen (Rechnung trägt Name und Daten des Vermieters, keinen WEBklar-Hinweis).
4. Online-Zahlung nur testen, wenn das Stripe-Konto verbunden ist (kleiner Betrag, danach im Portal stornieren und erstatten).
5. Im Portal „bezahlt (vor Ort)“ setzen, dann stornieren (Stornorechnung, E-Mail G22).
6. Testanfragen danach im Portal stornieren oder ablehnen; Sperren des Tests im Kalender entfernen.

7. Was das Widget zeigt (Kurzüberblick)

• Kalender mit belegten Nächten (durchgestrichen); vergangene Tage und Zeiträume über eine belegte Nacht hinweg sind nicht wählbar. Anreise am Abreisetag eines anderen Gastes ist möglich.
• Zusammenfassung des Zeitraums („12.–30. Nov. · 18 Nächte“), Personenzahl, Name, E-Mail, Telefon und Nachricht (optional), Firma (optional), Datenschutzhinweis.
• Schaltfläche „Anfrage senden“ (unverbindlich). Danach die Anfragenummer und der Hinweis, dass der Vermieter sich meldet.
• Die Buchung selbst läuft nicht im Widget, sondern auf der Buchungsseite bei WEBklar (Link in der E-Mail G17).

8. Wenn der Vertrag über die Website endet (Abschalten von Hand)

Der Buchungskalender läuft, solange WEBklar die Website des Vermieters betreibt (Leistungsbeschreibung Nr. 10). Die Software prüft das nicht. Du musst es selbst im Blick haben, wenn ein solcher Vertrag endet, gekündigt oder widerrufen wird:

1. Vorher schreibst Du dem Vermieter eine E-Mail (oder Chat): Der Vertrag endet am TT.MM.JJJJ, damit endet auch der Buchungskalender. Er soll seine Rechnungen als PDF herunterladen (WEBklar löscht sie 90 Tage nach dem Abschalten), offene Anfragen bearbeiten und seine Gäste informieren.
2. Zum Vertragsende im Ticketsystem (WOMS): Kunde → Reiter „Funktionen“ → Buchungskalender → „Abschalten“. Danach nimmt das Widget keine Anfragen mehr an und zeigt den Ausweichtext; Reservierungen laufen aus.
3. Der Vermieter kann Anfragen, Buchungen und Rechnungen danach 90 Tage lang im Portal lesen und die Rechnungen herunterladen. Danach löscht der tägliche Job automatisch alle Daten des Buchungskalenders; das Einrichtungs-Ticket bleibt als Arbeitsnachweis ohne Gästedaten.
4. Nimm nach den 90 Tagen das Snippet und den Menüpunkt aus der Website.
5. Beginnt innerhalb der 90 Tage wieder ein Vertrag über den Betrieb der Website, schaltest Du den Buchungskalender auf Wunsch des Vermieters in Textform ohne weitere Kosten wieder ein (WOMS → Funktionen → Buchungskalender → Aktivieren).
6. Erstattung (Leistungsbeschreibung Nr. 10 Abs. 6): Endet der Vertrag, bevor wir den Buchungskalender freigeschaltet haben, erstatten wir den gezahlten Einrichtungspreis (199 €) vollständig, in Stripe von Hand. Sonst gibt es keine Erstattung.

Das Stripe-Konto des Vermieters bleibt in jedem Fall beim Vermieter; wir rühren es nicht an.

9. Kalenderabgleich (iCal) einrichten

Im Portal unter Buchungen → Unterkünfte & Preise → Kalenderabgleich: Der Vermieter trägt die iCal-Adresse von Booking.com oder Airbnb als Import ein (Name und https-Adresse) und kopiert die Export-Adresse des Buchungskalenders zu Booking.com („Kalender synchronisieren“) oder Airbnb. Der Abgleich ist zeitversetzt (Minuten bis Stunden, Leistungsbeschreibung Nr. 4); sag das dem Vermieter, damit er vor jeder Freigabe seine anderen Plattformen prüft.