Webshop und Buchungen auf der Website
Wie eine Website den Laden der E-Commerce-App und die Buchungsstrecken der Termine-App einbindet: Schlüssel, Adapter, eigene Serverrouten, Übergabe an die Kasse und die drei Buchungsschritte.
Worum es geht
Seiten, Menüs und Texte kommen aus Sites. Produkte und Kasse kommen aus der App E-Commerce, Buchungen und Reservierungen aus der App Termine. Eine Website bindet beide über deren eigene Schnittstellen an. Die Vorlagen von Scorebase bringen alles Nötige mit; diese Anleitung erklärt, wie es zusammenhängt – für Entwicklerinnen und Entwickler.
Drei Grundsätze gelten überall:
- Schlüssel bleiben auf dem Server. Der Browser spricht nur mit Routen Ihrer eigenen Website; diese legen den Schlüssel dazu.
- Preise rechnet die App, nie die Website. Gesendet werden Produkt und Menge, nie ein Betrag. Beträge sind ganze Rappen (
2900= 29.00 CHF). - Zahlungen wickelt die App ab, der das Geschäft gehört, über die Zahlungsanbieter Ihrer Organisation (siehe Einstellungen, Zahlungsanbieter und Nutzung). Ihre Website nimmt keine Zahlungsmeldungen entgegen.
Schlüssel anlegen
| App | Wo | Schlüssel beginnt mit | Braucht |
|---|---|---|---|
| E-Commerce | Einstellungen → Schnittstelle der E-Commerce-App | ksk_ |
ecommerce.laden.read, für die Kasse zusätzlich ecommerce.laden.kaufen |
| Termine | Einstellungen → Schnittstelle der Termine-App | tmk_ |
Bereich „lesen und buchen“ |
Mehr dazu in E-Commerce im Überblick und Termine im Überblick.
Umgebungsvariablen
EC_URL=https://<ihre-organisation>.scorebase.ch # ohne /ecommerce
EC_TOKEN=ksk_…
NEXT_PUBLIC_EC_KANAL=web # Kennung des Verkaufskanals
TERMINE_URL=https://<ihre-organisation>.scorebase.ch # ohne /termine
TERMINE_TOKEN=tmk_…
NEXT_PUBLIC_TERMINE_STRECKE=<kennung> # Kennung der Buchungsstreckehcms init schreibt diese Variablen als leere Platzhalter in die .env.local, wenn die Vorlage Laden oder Buchung enthält. Kanal und Strecke dürfen öffentlich sein (NEXT_PUBLIC_): Der Warenkorb im Browser merkt sich den Kanal, und Server und Browser müssen denselben Wert lesen. Geheim sind nur die Schlüssel.
Die Dateien in den Vorlagen
| Datei | Aufgabe |
|---|---|
cms/laden.ts |
Katalog und Übergabe an die Kasse – nur auf dem Server |
cms/termine.ts |
Buchungsstrecke laden, Liste der erlaubten Vorgänge – nur auf dem Server |
cms/termine-client.ts |
Typen und Aufrufe für den Browser; ruft nur die eigene Route |
app/api/laden/kasse |
Eigene Route: nimmt die Warenkorbzeilen entgegen und holt die Übergabe-Adresse |
app/api/termine/<vorgang> |
Eigene Route: reicht die erlaubten Buchungsvorgänge weiter |
Wichtig: Browser-Code darf nichts aus
cms/termine.tsodercms/laden.tsimportieren, auch keine Typen. Diese Dateien lesen die Schlüssel; ein versehentlicher Import bringt sie ins Browser-Paket. Deshalb gibt escms/termine-client.ts.
Webshop: Produkte anzeigen
In einer Server-Komponente:
import { ecKanal, ladeProdukte, ladeProdukt } from "@/cms/laden"
const { produkte, gesamt } = await ladeProdukte({ kanal: await ecKanal(), limit: 60 })
const produkt = await ladeProdukt("leinen-hemd") // Adresse des ProduktsDer Adapter übersetzt die Felder der Schnittstelle an einer einzigen Stelle in die Form, die die Bausteine erwarten. Ändert sich die Schnittstelle, passen Sie eine Datei an, nicht jeden Baustein.
Der Warenkorb liegt im Browser (je Kanal einer). Er reserviert nichts und enthält keine Personendaten.
Webshop: an die Kasse übergeben
const antwort = await fetch(`/api/laden/kasse?kanal=${kanal}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
zeilen: lines.map((l) => ({
schluessel: l.productKey,
menge: l.quantity,
ausfuehrung: l.variantKey ?? null,
})),
}),
})
const { uebergabe } = await antwort.json()
window.location.href = uebergabeDie Antwort ist eine signierte, befristete Adresse, die nur diesen Warenkorb öffnet. Ab dort übernimmt die E-Commerce-App: Adresse, Versand, Rabattcode, Steuer, Reservierung des Bestands, Zahlung und Bestätigung.
- Bauen Sie auf Ihrer Website kein eigenes Adressformular – das wäre eine zweite Kasse, die bei Steuer, Rabatt oder Bestand von der echten abweicht.
- Schlägt die Übergabe fehl, lassen Sie den Warenkorb stehen, damit der Gast es noch einmal versuchen kann.
Buchungen: drei Schritte, nicht einer
import { holeZeiten, reserviere, buche } from "@/cms/termine-client"
// 1 — freie Zeiten. Was schon belegt ist (auch durch Events), fehlt in der Liste.
const zeiten = await holeZeiten(strecke, von, bis)
// 2 — reservieren: hält den Platz für die in der Termine-App eingestellte Frist.
const reservierung = await reserviere({ strecke, start, gruppengroesse: 2 })
// 3 — buchen. Ist sofort etwas zu bezahlen, kommt die Zahladresse mit.
const buchung = await buche({ strecke, reservierung: reservierung.marke, name, email })Trennen Sie Schritt 2 und 3: Sonst füllt der Gast das Formular aus, bevor feststeht, ob die Zeit noch frei ist. Die Belegung ist gemeinsam mit anderen Apps: Was die Website bucht, ist auch für Events und Anfragen belegt, und umgekehrt.
Die Route app/api/termine/<vorgang> kennt genau diese Vorgänge, jeweils mit fester Methode: strecke und zeiten (GET), reservieren, buchen, zahlung und zahlung-pruefen (POST). Alles andere beantwortet sie mit 404. Fehlermeldungen der Termine-App reicht sie unverändert weiter.
Buchungen: Rückkehr vom Zahlungsanbieter
import { pruefeZahlung } from "@/cms/termine-client"
const befund = await pruefeZahlung({ storno, vorgang })
if (befund?.zustand === "bezahlt") { /* Bestätigung zeigen */ }Eine Rückkehr-Adresse kann jeder aufrufen – „bezahlt“ ist erst, was der Zahlungsanbieter bestätigt. zahlung-pruefen fragt deshalb beim Anbieter nach. Die Buchung selbst bestätigt die Termine-App über die Meldung des Anbieters; die Prüfung sagt dem Gast nur, was er sehen soll.
Schutz vor Missbrauch
- Buchungsstrecken können ein verstecktes Feld gegen Spam-Roboter führen. Ist es ausgefüllt, wird die Buchung verworfen – mit derselben Meldung wie bei einer abgelaufenen Reservierung.
- Die öffentlichen Vorgänge sind je Besucher begrenzt, getrennt nach Lesen und Schreiben.
Fertige Bausteine
Die Vorlagen und die Bausteinbibliothek enthalten product-grid, product-detail, cart, mini-cart, checkout und booking – ausdrücklich zum Umgestalten. Solange sie nur über die Adapter und die eigenen Routen lesen, darf die Oberfläche aussehen, wie Sie wollen.
| Vorlage | Laden | Buchung |
|---|---|---|
frontend-starter |
ja | ja |
shop-storefront |
ja | – |
restaurant-alpenblick |
ja | ja |
veranstaltungshaus |
ja | ja |
Die Bausteine heissen in ihren Feldern kanal und strecke. Ältere Feldnamen (shop_key, resource_key) werden weiter gelesen, damit bestehende Seiten nicht leer bleiben.
Tickets
Für den Verkauf von Event-Tickets mit Sitzplan und Lounges gibt es eine eigene Schnittstelle in der Content API von Sites, siehe Ticketing über die Content API.
Wenn etwas nicht klappt
| Symptom | Ursache | Lösung |
|---|---|---|
| Baustein meldet „nicht eingerichtet“ | EC_… bzw. TERMINE_… ist leer |
Schlüssel anlegen und Variablen setzen |
| Fehler 401 aus der E-Commerce- oder Termine-App | Schlüssel falsch, widerrufen oder ohne passende Berechtigung | Schlüssel in der jeweiligen App prüfen |
| Warenkorb und Katalog passen nicht zusammen | Unterschiedliche Kanäle | NEXT_PUBLIC_EC_KANAL prüfen |
| Keine freien Zeiten | Strecke falsch, nicht veröffentlicht oder ausgebucht | NEXT_PUBLIC_TERMINE_STRECKE und die Strecke in der Termine-App prüfen |