Permetti ai tuoi clienti di prenotare lezioni di surf direttamente sulla tua piattaforma. REST · JSON · OCTO — disponibilità reale di ogni scuola, leggibile da qualsiasi marketplace o channel manager. Collega una volta, arrivi a molti.
{
"spot": "Carcavelos",
"date": "2026-06-22",
"time": "10:00",
"level": "iniciante",
"capacity": 6,
"vacancy": 4
}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.
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.
Offrono lezioni di surf come extra all'ospite, con prenotazione in tempo reale — senza telefonate, senza coordinamento manuale.
Includono lezioni di surf in qualsiasi pacchetto, prenotabili direttamente via API, con idempotenza sulle richieste ripetute.
Aggiungono il surf a qualsiasi itinerario di gruppo e confermano la disponibilità in tempo reale, con i posti liberi in diretta.
Mostrano scuole, spot e disponibilità in diretta. Lo scope forecast aggiunge le condizioni per spot.
Affitti brevi e appartamenti fanno upsell di surf al checkout — confermato in pochi secondi via API.
Una integrazione. Tutte le scuole della piattaforma. Posti reali, prezzi reali, anti-overbooking — confermato in millisecondi.
Non è la stessa API per tutti. Ogni chiave è limitata (least-privilege) a ciò che serve a quel partner — mai più di questo.
Leggono le lezioni disponibili e creano prenotazioni per conto dell'ospite/cliente. Il percorso v1 (OCTO). L'accesso di chi distribuisce lezioni.
Consigliano la tavola/muta giusta e leggono le condizioni dello spot. Il percorso v2, con scope sizing e/o forecast — non toccano mai le prenotazioni.
Portano clienti e ricevono commissione via /aff + cookie di 90 giorni. Senza chiave, senza integrazione tecnica.
Le chiavi di piattaforma portano scope. Una chiave sizing apre solo gli endpoint di sizing — tutto il resto restituisce 403 insufficient_scope.
Tutto in REST + JSON, autenticato con la chiave della scuola.
Le lezioni reali con giorno, ora, spot, livello, posti e prezzo. Filtra per data e livello. Formati sb · fh · bl · octo.
I tipi di lezione della scuola (livello, gruppo/privata, fascia di prezzo) — in nativo SB o come products OCTO.
Crea, consulta e cancella prenotazioni per conto del cliente finale. Idempotente per externalRef, con rivalidazione di posti e rapporti.
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.
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.
JSON-RPC 2.0, protocollo MCP 2024-11-05. Intestazione Authorization: Bearer sbek_…. La scuola viene sempre dalla chiave, mai dagli argomenti.
Genera la chiave con la sessione del titolare. Corpo: label, role, staffId?, scopes (read, oppure read e propose), expiresInDays (30, 90 o 365). La chiave viene restituita una sola volta.
Revoca la chiave e fa scadere le proposte in sospeso che ha richiesto.
Solo il titolare. Invia il payloadHash che ha visto; la modifica passa per lo stesso percorso del pannello, e una lezione cambiata nel frattempo finisce in conflitto.
Strumenti: 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
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
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:
X-Partner-API-Key: sbpk_xxxx… — il formato canonico di SurfBooking.
Authorization: Bearer sbpk_xxxx… — per i client che parlano OCTO. La stessa chiave.
Genera e revoca le chiavi in SurfBooking OS → Canali Esterni → API Partner. Non salviamo mai la chiave in chiaro — solo il suo digest.
Base: https://www.surfbooking.eu/api/partner/v1
Descrittore dell'API (radice, senza chiave). Restituisce name, version, auth, octo e la mappa completa degli endpoints. Aprirlo nel browser reindirizza a questa pagina.
Lezioni prenotabili. Parametri: from, to, level?, format? (sb·fh·bl·octo). Default: from=oggi, to=+30 giorni.
Alias OCTO di /availabilities — assume format=octo per default (plug-and-play OCTO).
Tipi di lezione della scuola. format? (sb·octo) — in OCTO restituisce products.
Alias OCTO di /services — assume format=octo per default. Array di products OCTO.
Identità del fornitore (descrittore OCTO supplier): id, name, endpoint, contact, locales, timeZone.
Crea una prenotazione. Corpo: lessonSlotId, customerName, customerEmail, customerPhone?, participants?, externalRef?, notes?.
Consulta lo stato di una prenotazione.
Cancella una prenotazione.
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": "…" }
}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": "BOKUN-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" }
}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 la risposta è un array semplice (senza envelope). In sb/fh arriva in availabilities; in bl, in data.
Ogni errore porta un corpo JSON { "error": "…" } — leggibile dalle macchine.
Chiave assente, troppo corta, non valida o revocata. Include un hint quando manca l'header.
Corpo incompleto, email malformata, o intervallo di date non valido (max 180 giorni, from ≤ to).
La lezione o la prenotazione non esiste in questa scuola — oppure, nel DELETE, era già stata cancellata.
Conflitto di stato: nessun posto, lezione nel passato, chiusa alla vendita, rapporto istruttore superato, o externalRef ripetuto (idempotenza — restituisce il bookingId che esiste già).
La chiave è valida ma non raggiunge quella risorsa: la prenotazione o la lezione è di un'altra scuola. Una chiave vede solo ciò che appartiene alla scuola che l'ha creata.
La prenotazione era in attesa di conferma e la finestra è passata. Non è un errore tuo: il posto è tornato a chi lo vuole. Creala di nuovo.
Oltre 120 richieste/min per chiave. Aspetta il Retry-After (60s). Ogni risposta porta X-RateLimit-Remaining.
Quella è colpa nostra. Riprova con lo stesso externalRef: creare prenotazioni è idempotente su quella chiave, quindi riprovare non duplica nulla.
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.
Ogni risposta porta X-RateLimit-Limit e X-RateLimit-Remaining. Oltre, un 429 con Retry-After: 60. Niente indovinelli: i numeri viaggiano in ogni risposta.
L'intervallo from–to è ciò che limita la risposta; oltre 180 giorni restituisce 400. Non c'è paginazione a cursore di proposito: una lezione ha una data, e chiedere per date è la paginazione naturale di questo dominio. Se ti serve di più, sono due richieste.
Revoca quelle che non usi prima di crearne di nuove. Una chiave revocata smette di funzionare già alla richiesta successiva, senza attese.
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.
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.
Tavola consigliata per level + weight. Scope sizing.
Tavola calibrata sulla giornata: level, weight, swellPeriodS, swellDirectionDeg, bestSwellDirDeg. Scope sizing.
Taglia della muta per weight + height. Scope sizing.
Leash per boardSize + category (board·soft_board). Scope sizing.
Calzari per shoeSizeEu (es.: 42). Scope sizing.
Elenca gli spot che puoi consultare — usa un id da qui in /conditions/:spotId. Scope forecast.
Condizioni dello spot — la stessa shape pubblica, sanificata (non espone mai modello né fonti). Scope forecast.
I migliori spot del paese adesso, ordinati per lo score in diretta — limit + level. Scope forecast.
Per i marchi di attrezzatura: quante volte ogni taglia del tuo marchio è stata usata nelle lezioni, per month (YYYY-MM). Solo i tuoi dati. Scope brand:read.
In quali spot l'attrezzatura del tuo marchio è stata più usata, ultimi months (1–12). Scope brand:read.
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.
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).
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.
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.
Offri lezioni vere ai tuoi ospiti senza gestire nulla — la prenotazione e il pagamento restano su SurfBooking.
Sincronizza la disponibilità in tempo reale, senza doppie prenotazioni. OCTO di fabbrica.
Elenca l’offerta delle scuole e instrada la prenotazione — con posti e rapporti sempre riconvalidati dalla nostra parte.
Ogni chiave vede solo l’offerta della propria scuola. Revocala con un clic e l’accesso muore all’istante.
Ogni prenotazione riconvalida posti e rapporti istruttore dentro una transazione. Esaurito è esaurito.
Il flusso di denaro resta dalla nostra parte — il partner instrada, SurfBooking conferma.
Esce solo ciò che serve alla prenotazione. I contatti dei tuoi allievi non finiscono nella lista di nessuno.
L’API è viva. Se hai una scuola di surf, generi la tua chiave nel SurfBooking OS. Se sei un partner esterno — marchio di attrezzatura, app, IA o hotel — richiedi una chiave di piattaforma (emessa da SurfBooking).
Sono una scuola · Apri il SurfBooking OS Sono un partner esterno · Richiedi accesso Vedi il descrittore