De vrais cours de surf,en un appel API.

Pas de protocole fermé. Nous parlons OCTO — le standard ouvert des réservations d'activités. Tu intègres une fois, tu atteins tout le monde.

OCTO (octo.travel), c'est la façon dont les systèmes de réservation, channel managers et marketplaces d'activités se parlent. Une intégration contre SurfBooking, et l'offre devient lisible par n'importe quel acheteur OCTO. Pour ceux qui préfèrent, nous renvoyons aussi le format natif SB et des variantes pour les adaptateurs existants.

Cinq types de partenaire. Une API.

Si tu distribues des expériences — un hôtel, une agence, un DMC, une app de tourisme ou une plateforme d'hébergement — l'API SurfBooking met la disponibilité réelle des cours de surf entre tes mains.

Comment ça marche.

Une intégration. Toutes les écoles de la plateforme. Places réelles, prix réels, anti-overbooking — confirmé en millisecondes.

Chaque partenaire se connecte seulement à ce qui lui sert.

Ce n'est pas la même API pour tout le monde. Chaque clé est limitée (least-privilege) à ce dont ce partenaire a besoin — jamais plus que ça.

Les clés de plateforme portent des scopes. Une clé sizing n'ouvre que les endpoints de sizing — tout le reste renvoie 403 insufficient_scope.

Trois choses. Disponibilité, services, réservations.

Tout en REST + JSON, authentifié par la clé de l’école.

Un appel et tu vois l’API répondre.

Le descripteur est public. Colle-le dans le terminal :

# voir l’API (sans clé)
curl -s https://www.surfbooking.eu/api/partner/v1

Contrat complet, lisible par machine — pensé pour que les agents d'IA et les générateurs de SDK découvrent l'API tout seuls : /openapi.json (OpenAPI 3.1) · référence interactive sur /docs (Swagger UI).

Réservation en 2 étapes avec 2 appels — bloque la place pendant que ton client paie, puis confirme :

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

Avec la clé de l’école, tu lis la disponibilité — ici au format 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 requêtes/min par clé. Chaque réponse porte X-RateLimit-Limit et X-RateLimit-Remaining ; en cas de dépassement tu reçois 429 avec Retry-After: 60.

Un assistant dans ton école, avec une clé rien qu’à toi.

En plus de l’API partenaires, chaque école peut connecter un assistant MCP à sa propre activité. Il est désactivé par défaut et n’a pas encore été validé avec un vrai client.

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

Limites : 60 appels par minute par clé et 2000 par jour. Aucun outil d’argent, et rien ne s’applique sans la confirmation du propriétaire. Le détail est sur la page MCP. /mcp

Une clé par école. C’est toi qui contrôles.

Chaque école génère sa propre clé dans SurfBooking OS — et la révoque quand elle veut. La clé passe dans un en-tête, dans l'un des deux formats :

Génère et révoque des clés dans SurfBooking OS → Canaux de vente → API Partenaires. Nous ne stockons jamais la clé en clair — seulement son empreinte.

Les endpoints.

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

Le descripteur — GET /api/partner/v1 (sans clé) :

{
  "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é du fournisseur — 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": "…" }
}

Requête et réponse, pour de vrai.

Le corps d’une réservation et ce que tu reçois en retour — exactement comme l’API répond aujourd’hui.

Créer une réservation — 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"
  }'

Réponse — 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é en OCTO — GET /availabilities?format=octo renvoie un tableau :

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

Prix en centimes (minor units) — 3500 = 35,00 €, selon le currencyPrecision: 2 d'OCTO. Les dates arrivent en heure locale de l'école (Europe/Lisbon).

La même disponibilité dans d'autres formats. Natif SB — ?format=sb (envelope avec _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 autre système de réservation — ?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 autre système de réservation — ?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" }
    }
  ]
}

En octo la réponse est un tableau simple (sans envelope). En sb/fh elle arrive dans availabilities ; en bl, dans data.

Codes d’état.

Chaque erreur porte un corps JSON { "error": "…" } — lisible par machine.

Clé absente ou invalide — 401 :

# pas d’en-tête de clé
{
  "error": "missing_api_key",
  "hint": "Set X-Partner-API-Key header (or Authorization: Bearer)"
}

# clé inexistante ou révoquée
{ "error": "invalid_api_key" }

Pas assez de places (anti-overbooking) — 409 :

# le cours n’a plus de places pour le nombre de participants
{
  "error": "insufficient_spots",
  "remaining": 1
}

# externalRef répété → idempotence : renvoie le bookingId existant
{
  "error": "external_ref_exists",
  "bookingId": "f1e2d3c4-…"
}

La revalidation des places et des ratios s'exécute dans une transaction avec SELECT … FOR UPDATE — complet c'est complet, il n'y a jamais de double réservation.

Ce que tu peux demander, et combien.

Ces trois nombres sont lus dans le code qui sert l'API, pas écrits ici à la main : s'ils changent là-bas, cette page devient fausse et un test le dit.

Recommande le bon matériel. Sans toucher aux réservations.

Le chemin v2 pour les marques de matériel, les apps et l'IA. Clé de plateforme avec scope sizing, forecast et/ou brand:read — déterministe, sans données personnelles, ne touche jamais aux réservations. Découvre tes scopes sur /api/partner/v2/meta. Base : https://www.surfbooking.eu/api/partner/v2.

Recommandation de planche — 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" } }

Les clés de plateforme (sbpd_…) sont émises par SurfBooking, pas par l'école. Mauvais scope → 403 insufficient_scope. Limite 240 requêtes/min par clé, avec Retry-After: 60 en cas de dépassement.

Les tailles sur ton site. Une ligne.

Une page iframe autonome, "Powered by SurfBooking". Elle montre les conditions du spot, recommande la planche selon le poids et le niveau, et emmène le client réserver un cours — avec ton lien de partenaire premium intégré. Sans PII, sans cookies de suivi.

<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 = ta clé de plateforme (scope sizing, et forecast si tu veux les conditions en haut). spot et slug sont optionnels — le slug relie les réservations générées à ton /aff (cookie de 90 jours).

v1 — stable.

La base est /api/partner/v1. Les changements qui cassent la compatibilité passent dans une nouvelle version (/v2) — la v1 n'a pas de dépréciation prévue. Nous pouvons ajouter des champs sans préavis, alors lis de façon tolérante : ignore ce que tu ne connais pas encore.

Channel managers, marketplaces, hôtels.

Tout partenaire qui veut vendre ou montrer de vrais cours de surf. Conçu sur le standard ouvert OCTO, que beaucoup de systèmes de réservation et channel managers parlent déjà.

C’est l’école qui décide. Toujours.