Echte Surfkurse,mit einem API-Aufruf.

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.

Fünf Partnertypen. Eine API.

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.

So funktioniert es.

Eine Integration. Alle Schulen der Plattform. Echte Plätze, echte Preise, Anti-Overbooking — in Millisekunden bestätigt.

Jeder Partner verbindet sich nur mit dem, was ihm nützt.

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.

Plattform-Schlüssel tragen Scopes. Ein sizing-Schlüssel öffnet nur die Sizing-Endpoints — alles andere gibt 403 insufficient_scope zurück.

Drei Dinge. Verfügbarkeit, Leistungen, Buchungen.

Alles in REST + JSON, authentifiziert über den Schlüssel der Surfschule.

Ein Aufruf und du siehst die API antworten.

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.

Ein Assistent in deiner Schule, mit einem Schlüssel nur für dich.

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.

Werkzeuge: list_my_schools · get_school_briefing · get_school_schedule · get_bookings_summary · get_lesson_roster · get_stock_summary · get_conditions_for_my_lessons · review_week_with_sea · 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

Ein Schlüssel pro Surfschule. Du hast die Kontrolle.

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:

Schlüssel erzeugen und widerrufen in SurfBooking OS → Vertriebskanäle → Partner-API. Wir speichern den Schlüssel nie im Klartext — nur seinen Hash.

Die Endpoints.

Basis: https://www.surfbooking.eu/api/partner/v1

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": "…" }
}

Request und Response, echt.

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": "EXT-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" }
}

Ein anderes Buchungssystem — ?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" }
    }
  ]
}

Ein anderes Buchungssystem — ?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.

Statuscodes.

Jeder Fehler trägt einen JSON-Body { "error": "…" } — maschinenlesbar.

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.

Was du abfragen kannst, und wie viel.

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.

Empfiehlt die richtige Ausrüstung. Ohne Buchungen anzufassen.

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.

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.

Größen auf deiner Website. Eine Zeile.

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).

v1 — stabil.

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.

Channel Manager, Marketplaces, Hotels.

Jeder Partner, der echte Surfkurse verkaufen oder zeigen will. Auf dem offenen Standard OCTO entworfen, den viele Buchungssysteme und Channel Manager schon sprechen.

Die Surfschule bestimmt. Immer.