Lezioni di surf vere,con una chiamata API.

Nessun protocollo chiuso. Parliamo OCTO — lo standard aperto delle prenotazioni di attività. Integri una volta, arrivi a tutti.

OCTO (octo.travel) è il modo in cui i sistemi di prenotazione, i channel manager e i marketplace di attività si parlano. Una integrazione contro SurfBooking, e l'offerta diventa leggibile da qualsiasi acquirente OCTO. Per chi preferisce, restituiamo anche il formato nativo SB e varianti per gli adattatori esistenti.

Cinque tipi di partner. Una API.

Se distribuisci esperienze — un hotel, un'agenzia, un DMC, una app di turismo o una piattaforma di alloggi — l'API di SurfBooking ti mette in mano la disponibilità reale delle lezioni di surf.

Come funziona.

Una integrazione. Tutte le scuole della piattaforma. Posti reali, prezzi reali, anti-overbooking — confermato in millisecondi.

Ogni partner si collega solo a ciò che gli serve.

Non è la stessa API per tutti. Ogni chiave è limitata (least-privilege) a ciò che serve a quel partner — mai più di questo.

Le chiavi di piattaforma portano scope. Una chiave sizing apre solo gli endpoint di sizing — tutto il resto restituisce 403 insufficient_scope.

Tre cose. Disponibilità, servizi, prenotazioni.

Tutto in REST + JSON, autenticato con la chiave della scuola.

Una chiamata e vedi l’API rispondere.

Il descrittore è pubblico. Incollalo nel terminale:

# vedi l’API (senza chiave)
curl -s https://www.surfbooking.eu/api/partner/v1

Contratto completo, leggibile dalle macchine — pensato perché agenti di IA e generatori di SDK scoprano da soli l'API: /openapi.json (OpenAPI 3.1) · riferimento interattivo su /docs (Swagger UI).

Prenotazione in 2 passi con 2 chiamate — blocca il posto mentre il tuo cliente paga, poi conferma:

# 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"

Con la chiave della scuola leggi la disponibilità — qui in formato OCTO:

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"

Limite: 120 richieste/min per chiave. Ogni risposta porta X-RateLimit-Limit e X-RateLimit-Remaining; superandolo ricevi 429 con Retry-After: 60.

Un assistente dentro la tua scuola, con una chiave solo tua.

Oltre all’API partner, ogni scuola può collegare un assistente MCP alla propria attività. È disattivato per impostazione predefinita e non è ancora stato validato con un client reale.

Strumenti: 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

Limiti: 60 chiamate al minuto per chiave e 2000 al giorno. Nessuno strumento di denaro, e nulla si applica senza la conferma del titolare. I dettagli sono nella pagina MCP. /mcp

Una chiave per scuola. Il controllo è tuo.

Ogni scuola genera la propria chiave in SurfBooking OS — e la revoca quando vuole. La chiave viaggia in un header, in uno dei due formati:

Genera e revoca le chiavi in SurfBooking OS → Canali di vendita → API Partner. Non salviamo mai la chiave in chiaro — solo il suo digest.

Gli endpoint.

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

Il descrittore — GET /api/partner/v1 (senza chiave):

{
  "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à del fornitore — 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": "…" }
}

Richiesta e risposta, sul serio.

Il corpo di una prenotazione e quello che ricevi indietro — esattamente come l’API risponde oggi.

Creare una prenotazione — 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"
  }'

Risposta — 201 Created:

{
  "ok": true,
  "bookingId": "f1e2d3c4-…",
  "createdAt": "2026-06-21T11:42:00.000Z",
  "lessonSlotId": "a1b2c3d4-…",
  "schoolId": "…",
  "status": "confirmed",
  "participants": 2,
  "totalAmountCents": 7000,
  "currency": "EUR"
}

Disponibilità in OCTO — GET /availabilities?format=octo restituisce un array:

[
  {
    "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/…" }
  }
]

Prezzi in centesimi (minor units) — 3500 = 35,00 €, secondo il currencyPrecision: 2 di OCTO. Le date arrivano nell'ora locale della scuola (Europe/Lisbon).

La stessa disponibilità in altri formati. Nativo SB — ?format=sb (envelope con _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" }
}

Un altro sistema di prenotazione — ?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" }
    }
  ]
}

Un altro sistema di prenotazione — ?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 la risposta è un array semplice (senza envelope). In sb/fh arriva in availabilities; in bl, in data.

Codici di stato.

Ogni errore porta un corpo JSON { "error": "…" } — leggibile dalle macchine.

Chiave mancante o non valida — 401:

# nessun header di chiave
{
  "error": "missing_api_key",
  "hint": "Set X-Partner-API-Key header (or Authorization: Bearer)"
}

# chiave inesistente o revocata
{ "error": "invalid_api_key" }

Posti insufficienti (anti-overbooking) — 409:

# la lezione non ha più posti per il n. di partecipanti
{
  "error": "insufficient_spots",
  "remaining": 1
}

# externalRef ripetuto → idempotenza: restituisce il bookingId esistente
{
  "error": "external_ref_exists",
  "bookingId": "f1e2d3c4-…"
}

La rivalidazione di posti e rapporti gira dentro una transazione con SELECT … FOR UPDATE — esaurito è esaurito, non c'è mai doppia prenotazione.

Cosa puoi chiedere, e quanto.

Questi tre numeri sono letti dal codice che serve l'API, non scritti qui a mano: se cambiano lì, questa pagina diventa sbagliata e un test lo dice.

Consiglia l’attrezzatura giusta. Senza toccare le prenotazioni.

Il percorso v2 per marchi di attrezzatura, app e IA. Chiave di piattaforma con scope sizing, forecast e/o brand:read — deterministico, senza dati personali, non tocca mai le prenotazioni. Scopri i tuoi scope su /api/partner/v2/meta. Base: https://www.surfbooking.eu/api/partner/v2.

Raccomandazione di tavola — 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" } }

Le chiavi di piattaforma (sbpd_…) sono emesse da SurfBooking, non dalla scuola. Scope sbagliato → 403 insufficient_scope. Limite 240 richieste/min per chiave, con Retry-After: 60 al superamento.

Le taglie sul tuo sito. Una riga.

Una pagina iframe autonoma, "Powered by SurfBooking". Mostra le condizioni dello spot, consiglia la tavola per peso e livello, e porta il cliente a prenotare una lezione — con il tuo link partner premium integrato. Senza PII, senza cookie di tracciamento.

<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 = la tua chiave di piattaforma (scope sizing, e forecast se vuoi le condizioni in alto). spot e slug sono opzionali — lo slug collega le prenotazioni generate al tuo /aff (cookie di 90 giorni).

v1 — stabile.

La base è /api/partner/v1. I cambiamenti che rompono la compatibilità entrano in una versione nuova (/v2) — la v1 non ha deprecazione prevista. Possiamo aggiungere campi senza preavviso, quindi leggi in modo tollerante: ignora ciò che ancora non conosci.

Channel manager, marketplace, hotel.

Qualsiasi partner che voglia vendere o mostrare lezioni di surf reali. Progettato sullo standard aperto OCTO, che molti sistemi di prenotazione e channel manager già parlano.

Comanda la scuola. Sempre.