Lass deine Kunden Surfkurse direkt auf deiner Plattform buchen. REST · JSON · OCTO — echte Verfügbarkeit jeder Schule, lesbar für jeden Marktplatz oder Channel Manager. Einmal anbinden, viele erreichen.
{
"spot": "Carcavelos",
"date": "2026-06-22",
"time": "10:00",
"level": "iniciante",
"capacity": 6,
"vacancy": 4
}Kein geschlossenes Protokoll. Wir sprechen OCTO — den offenen Standard für Aktivitätsbuchungen. Einmal integrieren, alle erreichen.
OCTO (octo.travel) ist die Art, wie Buchungssysteme, Channel Manager und Aktivitäts-Marktplätze miteinander sprechen. Eine Integration gegen SurfBooking, und das Angebot ist für jeden OCTO-Käufer lesbar. Wer will, bekommt auch das native SB-Format und Varianten für bestehende Adapter.
Wenn du Erlebnisse vertreibst — ein Hotel, eine Agentur, ein DMC, eine Tourismus-App oder eine Unterkunftsplattform — legt die SurfBooking-API echte Verfügbarkeit von Surfkursen in deine Hände.
Sie bieten dem Gast Surfkurse als Extra an, mit Buchung in Echtzeit — ohne Telefonate, ohne manuelle Koordination.
Sie nehmen Surfkurse in jedes Paket auf, direkt über die API buchbar, mit Idempotenz bei wiederholten Anfragen.
Sie fügen jedem Gruppenprogramm Surf hinzu und bestätigen die Verfügbarkeit in Echtzeit, mit freien Plätzen live.
Sie zeigen Schulen, Spots und Verfügbarkeit live. Der Scope forecast ergänzt die Bedingungen pro Spot.
Ferienwohnungen und Apartments verkaufen Surf beim Checkout dazu — in Sekunden über die API bestätigt.
Eine Integration. Alle Schulen der Plattform. Echte Plätze, echte Preise, Anti-Overbooking — in Millisekunden bestätigt.
Es ist nicht dieselbe API für alle. Jeder Schlüssel ist (least-privilege) auf das begrenzt, was dieser Partner braucht — nie mehr als das.
Sie lesen die verfügbaren Kurse und erstellen Buchungen im Namen des Gastes/Kunden. Der Weg v1 (OCTO). Der Zugang für alle, die Kurse vertreiben.
Sie empfehlen das richtige Board und den richtigen Neoprenanzug und lesen die Bedingungen am Spot. Der Weg v2, mit Scope sizing und/oder forecast — sie fassen Buchungen nie an.
Sie bringen Kunden und erhalten Provision über /aff + ein 90-Tage-Cookie. Ohne Schlüssel, ohne technische Integration.
Plattform-Schlüssel tragen Scopes. Ein sizing-Schlüssel öffnet nur die Sizing-Endpoints — alles andere gibt 403 insufficient_scope zurück.
Alles in REST + JSON, authentifiziert über den Schlüssel der Surfschule.
Die echten Kurse mit Tag, Uhrzeit, Spot, Level, freien Plätzen und Preis. Filter nach Datum und Level. Formate sb · fh · bl · octo.
Die Kursarten der Schule (Level, Gruppe/privat, Preisspanne) — im nativen SB-Format oder als OCTO-products.
Erstellt, liest und storniert Buchungen im Namen des Endkunden. Idempotent über externalRef, mit erneuter Prüfung von Plätzen und Verhältnissen.
Der Descriptor ist öffentlich. Ins Terminal einfügen:
# API ansehen (ohne Schlüssel) curl -s https://www.surfbooking.eu/api/partner/v1
Vollständiger, maschinenlesbarer Vertrag — gedacht für KI-Agenten und SDK-Generatoren, um die API selbst zu entdecken: /openapi.json (OpenAPI 3.1) · interaktive Referenz unter /docs (Swagger UI).
Buchung in 2 Schritten mit 2 Aufrufen — halte den Platz, während dein Kunde bezahlt, dann bestätige:
# 1 — hold (expira sozinho; a vaga fica segura)
curl -X POST https://www.surfbooking.eu/api/partner/v1/bookings -H "X-Partner-API-Key: A_TUA_CHAVE" -H "Content-Type: application/json" -d '{"lessonSlotId":"…","customerName":"…","customerEmail":"…",
"status":"ON_HOLD","expirationMinutes":30}'
# 2 — confirm (idempotente; hold expirado devolve 410 e liberta a vaga)
curl -X POST https://www.surfbooking.eu/api/partner/v1/bookings/{id}/confirm -H "X-Partner-API-Key: A_TUA_CHAVE"Mit dem Schlüssel der Surfschule liest du die Verfügbarkeit — hier im OCTO-Format:
curl -s "https://www.surfbooking.eu/api/partner/v1/availabilities?format=octo&from=2026-07-01&to=2026-07-07" \
-H "Authorization: Bearer sbpk_xxxxxxxxxxxxxxxxxxxxxxxx"Limit: 120 Anfragen/Min pro Schlüssel. Jede Antwort trägt X-RateLimit-Limit und X-RateLimit-Remaining; bei Überschreitung bekommst du 429 mit Retry-After: 60.
Neben der Partner-API kann jede Schule einen MCP-Assistenten mit ihrem eigenen Betrieb verbinden. Er ist standardmäßig aus und noch nicht mit einem echten Client geprüft.
JSON-RPC 2.0, MCP-Protokoll 2024-11-05. Header Authorization: Bearer sbek_…. Die Schule kommt immer aus dem Schlüssel, nie aus den Argumenten.
Erzeugt den Schlüssel mit der Sitzung des Inhabers. Body: label, role, staffId?, scopes (read, oder read und propose), expiresInDays (30, 90 oder 365). Der Schlüssel kommt nur einmal zurück.
Widerruft den Schlüssel und lässt seine offenen Vorschläge verfallen.
Nur der Inhaber. Sendet den payloadHash, den er gesehen hat; die Änderung läuft über denselben Weg wie das Dashboard, und ein Kurs, der sich inzwischen geändert hat, endet im Konflikt.
Werkzeuge: list_my_schools · get_school_schedule · get_bookings_summary · get_lesson_roster · get_stock_summary · get_conditions_for_my_lessons · prepare_lesson_move · prepare_stock_change · list_pending_proposals
Limits: 60 Aufrufe pro Minute pro Schlüssel und 2000 pro Tag. Keine Geld-Werkzeuge, und nichts wird ohne Bestätigung des Inhabers angewendet. Details auf der MCP-Seite. /mcp
Jede Schule erzeugt ihren eigenen Schlüssel in SurfBooking OS — und widerruft ihn, wann sie will. Der Schlüssel geht in einem Header mit, in einem der beiden Formate:
X-Partner-API-Key: sbpk_xxxx… — das kanonische Format von SurfBooking.
Authorization: Bearer sbpk_xxxx… — für Clients, die OCTO sprechen. Derselbe Schlüssel.
Schlüssel erzeugen und widerrufen in SurfBooking OS → Externe Kanäle → Partner-API. Wir speichern den Schlüssel nie im Klartext — nur seinen Hash.
Basis: https://www.surfbooking.eu/api/partner/v1
API-Deskriptor (Root, ohne Schlüssel). Gibt name, version, auth, octo und die vollständige Karte der endpoints zurück. Im Browser geöffnet, leitet es auf diese Seite weiter.
Buchbare Kurse. Parameter: from, to, level?, format? (sb·fh·bl·octo). Standard: from=heute, to=+30 Tage.
OCTO-Alias von /availabilities — nimmt standardmäßig format=octo an (plug-and-play OCTO).
Kursarten der Schule. format? (sb·octo) — in OCTO gibt es products zurück.
OCTO-Alias von /services — nimmt standardmäßig format=octo an. Array von OCTO-products.
Identität des Anbieters (OCTO-supplier-Deskriptor): id, name, endpoint, contact, locales, timeZone.
Erstellt eine Buchung. Body: lessonSlotId, customerName, customerEmail, customerPhone?, participants?, externalRef?, notes?.
Fragt den Status einer Buchung ab.
Storniert eine Buchung.
Der Deskriptor — GET /api/partner/v1 (ohne Schlüssel):
{
"name": "SurfBooking Partner API v1",
"version": "1.0.0",
"auth": "X-Partner-API-Key header, ou Authorization: Bearer (compatível OCTO).",
"octo": {
"supported": true,
"formatParam": "octo",
"supplierEndpoint": "/api/partner/v1/supplier"
},
"endpoints": {
"availabilities": { "method": "GET", "path": "/api/partner/v1/availabilities" },
"services": { "method": "GET", "path": "/api/partner/v1/services" },
"supplier": { "method": "GET", "path": "/api/partner/v1/supplier" },
"createBooking": { "method": "POST", "path": "/api/partner/v1/bookings" },
"getBooking": { "method": "GET", "path": "/api/partner/v1/bookings/:id" },
"cancelBooking": { "method": "DELETE", "path": "/api/partner/v1/bookings/:id" }
}
} Identität des Anbieters — GET /supplier (OCTO):
{
"id": "school-uuid-…",
"name": "Nome da Escola",
"endpoint": "https://www.surfbooking.eu/api/partner/v1",
"contact": { "website": "https://www.surfbooking.eu", "email": null, "telephone": null, "address": null },
"locales": ["pt", "en"],
"timeZone": "Europe/Lisbon",
"_sb": { "description": "…", "logoUrl": "…" }
}Der Body einer Buchung und was du zurückbekommst — genau so, wie die API heute antwortet.
Eine Buchung erstellen — POST /bookings:
curl -s -X POST https://www.surfbooking.eu/api/partner/v1/bookings \
-H "Authorization: Bearer sbpk_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"lessonSlotId": "a1b2c3d4-…",
"customerName": "Ana Silva",
"customerEmail": "[email protected]",
"customerPhone": "+351912345678",
"participants": 2,
"externalRef": "BOKUN-7782",
"notes": "Primeira aula"
}'Antwort — 201 Created:
{
"ok": true,
"bookingId": "f1e2d3c4-…",
"createdAt": "2026-06-21T11:42:00.000Z",
"lessonSlotId": "a1b2c3d4-…",
"schoolId": "…",
"status": "confirmed",
"participants": 2,
"totalAmountCents": 7000,
"currency": "EUR"
}Verfügbarkeit in OCTO — GET /availabilities?format=octo gibt ein Array zurück:
[
{
"id": "a1b2c3d4-…",
"localDateTimeStart": "2026-07-02T10:00:00",
"localDateTimeEnd": "2026-07-02T12:00:00",
"available": true,
"status": "AVAILABLE",
"vacancies": 4,
"capacity": 6,
"maxUnits": 4,
"pricing": {
"original": 3500, "retail": 3500, "net": 3500,
"currency": "EUR", "currencyPrecision": 2
},
"_sb": { "level": "beginner", "spotName": "…", "bookingUrl": "https://www.surfbooking.eu/aula/…" }
}
]Preise in Cent (minor units) — 3500 = 35,00 €, gemäß currencyPrecision: 2 von OCTO. Die Daten kommen in der Ortszeit der Schule (Europe/Lisbon).
Dieselbe Verfügbarkeit in anderen Formaten. Nativ SB — ?format=sb (Envelope mit _meta):
{
"availabilities": [
{
"id": "a1b2c3d4-…",
"date": "2026-07-02",
"startTime": "10:00",
"endTime": "12:00",
"level": "beginner",
"spotsTotal": 6,
"spotsRemaining": 4,
"pricePerPerson": 3500,
"currency": "EUR",
"instructorName": "…",
"spotName": "…",
"schoolId": "…",
"schoolName": "…",
"bookingUrl": "https://www.surfbooking.eu/aula/9f3c1a2b7d"
}
],
"_meta": { "format": "sb", "total": 1, "from": "2026-07-01", "to": "2026-07-07" }
}FareHarbor — ?format=fh (Envelope availabilities):
{
"availabilities": [
{
"pk": "a1b2c3d4-…",
"start_at": "2026-07-02T10:00:00",
"end_at": "2026-07-02T12:00:00",
"capacity": 6,
"num_remaining": 4,
"is_available": true,
"customer_type_rates": [
{ "pk": "a1b2c3d4-…_default", "total": { "amount": "35.00", "currency": "EUR" } }
],
"_sb_meta": { "level": "beginner", "bookingUrl": "https://www.surfbooking.eu/aula/9f3c1a2b7d" }
}
]
}Booking Layer — ?format=bl (Envelope data):
{
"data": [
{
"id": "a1b2c3d4-…",
"date": "2026-07-02",
"startTime": "10:00",
"endTime": "12:00",
"serviceName": "Surf beginner",
"capacity": 6,
"spotsLeft": 4,
"pricePerPerson": 3500,
"currency": "EUR",
"_sb_meta": { "level": "beginner", "bookingUrl": "https://www.surfbooking.eu/aula/9f3c1a2b7d" }
}
]
}In octo ist die Antwort ein einfaches Array (ohne Envelope). In sb/fh kommt sie in availabilities; in bl in data.
Jeder Fehler trägt einen JSON-Body { "error": "…" } — maschinenlesbar.
Schlüssel fehlt, zu kurz, ungültig oder widerrufen. Enthält einen hint, wenn der Header fehlt.
Unvollständiger Body, fehlerhafte E-Mail oder ungültiger Datumsbereich (max. 180 Tage, from ≤ to).
Der Kurs oder die Buchung existiert in dieser Schule nicht — oder war beim DELETE bereits storniert.
Zustandskonflikt: keine Plätze, Kurs in der Vergangenheit, für den Verkauf geschlossen, Trainer-Verhältnis überschritten oder wiederholter externalRef (Idempotenz — gibt die bereits vorhandene bookingId zurück).
Der Schlüssel ist gültig, erreicht diese Ressource aber nicht: die Buchung oder die Stunde gehört einer anderen Schule. Ein Schlüssel sieht immer nur, was der Schule gehört, die ihn erstellt hat.
Die Buchung wartete auf Bestätigung und das Fenster ist zu. Das ist kein Fehler auf deiner Seite: der Platz ging zurück an alle. Leg sie neu an.
Über 120 Anfragen/Min pro Schlüssel. Warte den Retry-After ab (60s). Jede Antwort trägt X-RateLimit-Remaining.
Das liegt an uns. Versuch es mit demselben externalRef erneut: das Anlegen einer Buchung ist über diesen Schlüssel idempotent, ein zweiter Versuch dupliziert also nichts.
Fehlender oder ungültiger Schlüssel — 401:
# kein Schlüssel-Header { "error": "missing_api_key", "hint": "Set X-Partner-API-Key header (or Authorization: Bearer)" } # Schlüssel existiert nicht oder wurde widerrufen { "error": "invalid_api_key" }
Nicht genug freie Plätze (Anti-Overbooking) — 409:
# der Kurs hat keine Plätze mehr für die Teilnehmerzahl { "error": "insufficient_spots", "remaining": 1 } # wiederholter externalRef → Idempotenz: gibt die vorhandene bookingId zurück { "error": "external_ref_exists", "bookingId": "f1e2d3c4-…" }
Die erneute Prüfung von Plätzen und Verhältnissen läuft in einer Transaktion mit SELECT … FOR UPDATE — ausverkauft ist ausverkauft, Doppelbuchungen gibt es nie.
Jede Antwort trägt X-RateLimit-Limit und X-RateLimit-Remaining. Darüber ein 429 mit Retry-After: 60. Kein Raten: die Zahlen fahren in jeder Antwort mit.
Der Bereich from–to begrenzt die Antwort; über 180 Tage kommt ein 400. Es gibt bewusst keine Cursor-Paginierung: eine Stunde hat ein Datum, und nach Daten zu fragen ist hier das natürliche Blättern. Brauchst du mehr, sind das zwei Anfragen.
Widerrufe die, die du nicht nutzt, bevor du neue anlegst. Ein widerrufener Schlüssel funktioniert schon bei der nächsten Anfrage nicht mehr, ohne Verzögerung.
Diese drei Zahlen werden aus dem Code gelesen, der die API bedient, nicht hier von Hand geschrieben: ändern sie sich dort, wird diese Seite falsch und ein Test sagt es.
Der Weg v2 für Ausrüstungsmarken, Apps und KI. Plattform-Schlüssel mit Scope sizing, forecast und/oder brand:read — deterministisch, ohne personenbezogene Daten, fasst Buchungen nie an. Entdecke deine Scopes unter /api/partner/v2/meta. Basis: https://www.surfbooking.eu/api/partner/v2.
Empfohlenes Board nach level + weight. Scope sizing.
Board auf den Tag abgestimmt: level, weight, swellPeriodS, swellDirectionDeg, bestSwellDirDeg. Scope sizing.
Neoprenanzug-Größe nach weight + height. Scope sizing.
Leash nach boardSize + category (board·soft_board). Scope sizing.
Füßlinge nach shoeSizeEu (z. B.: 42). Scope sizing.
Listet die Spots auf, die du abfragen kannst — nimm eine id von hier in /conditions/:spotId. Scope forecast.
Bedingungen am Spot — dieselbe öffentliche Shape, bereinigt (gibt weder Modell noch Quellen preis). Scope forecast.
Die besten Spots des Landes jetzt, sortiert nach dem Live-Score — limit + level. Scope forecast.
Für Ausrüstungsmarken: wie oft jede Größe deiner Marke in Kursen genutzt wurde, nach month (YYYY-MM). Nur deine Daten. Scope brand:read.
An welchen Spots die Ausrüstung deiner Marke am meisten genutzt wurde, letzte months (1–12). Scope brand:read.
Board-Empfehlung — GET /sizing/board:
curl -s "https://www.surfbooking.eu/api/partner/v2/sizing/board?level=beginner&weight=75" \
-H "X-Partner-API-Key: sbpd_xxxxxxxxxxxxxxxxxxxxxxxx"{ "recommendation": { "category": "soft_board", "size": "8'0" } }Plattform-Schlüssel (sbpd_…) werden von SurfBooking ausgegeben, nicht von der Schule. Falscher Scope → 403 insufficient_scope. Limit 240 Anfragen/Min pro Schlüssel, mit Retry-After: 60 bei Überschreitung.
Eine eigenständige iframe-Seite, "Powered by SurfBooking". Sie zeigt die Bedingungen am Spot, empfiehlt das Board nach Gewicht und Level und führt den Kunden zur Buchung eines Kurses — mit deinem Premium-Partnerlink eingebaut. PII-frei, ohne Tracking-Cookies.
<iframe
src="https://www.surfbooking.eu/w/surf?key=sbpd_xxxx&spot=SPOT_ID&slug=O_TEU_SLUG"
width="360" height="520" frameborder="0"></iframe>key = dein Plattform-Schlüssel (Scope sizing, und forecast, wenn du die Bedingungen oben willst). spot und slug sind optional — der slug verknüpft die erzeugten Buchungen mit deinem /aff (90-Tage-Cookie).
Die Basis ist /api/partner/v1. Änderungen, die die Kompatibilität brechen, kommen in eine neue Version (/v2) — für v1 ist keine Abkündigung geplant. Wir können ohne Ankündigung Felder ergänzen, also lies tolerant: ignoriere, was du noch nicht kennst.
Jeder Partner, der echte Surfkurse verkaufen oder zeigen will. Auf dem offenen Standard OCTO entworfen, den viele Buchungssysteme und Channel Manager schon sprechen.
Biete deinen Gästen echte Kurse an, ohne etwas zu verwalten — Buchung und Zahlung bleiben bei SurfBooking.
Synchronisiert die Verfügbarkeit in Echtzeit, ohne Doppelbuchung. OCTO ab Werk.
Listet das Angebot der Surfschulen und leitet die Buchung weiter — Plätze und Betreuungsschlüssel werden auf unserer Seite immer neu geprüft.
Jeder Schlüssel sieht nur das Angebot der eigenen Surfschule. Ein Klick zum Widerrufen und der Zugang ist sofort tot.
Jede Buchung prüft Plätze und Surflehrer-Verhältnisse innerhalb einer Transaktion neu. Ausgebucht ist ausgebucht.
Der Geldfluss bleibt auf unserer Seite — der Partner leitet weiter, SurfBooking bestätigt.
Es geht nur raus, was für die Buchung nötig ist. Die Kontakte deiner Schüler landen auf niemandes Liste.
Die API ist live. Wenn du eine Surfschule hast, erzeugst du deinen eigenen Schlüssel im SurfBooking OS. Wenn du externer Partner bist — Ausrüstungsmarke, App, KI oder Hotel — beantragst du einen Plattform-Schlüssel (von SurfBooking ausgestellt).
Ich bin eine Surfschule · SurfBooking OS öffnen Ich bin externer Partner · Zugang anfragen Descriptor ansehen