Clases de surf reales,en una llamada a la API.

Sin protocolo cerrado. Hablamos OCTO — el estándar abierto de las reservas de actividades. Integras una vez, llegas a todo el mundo.

OCTO (octo.travel) es como los sistemas de reservas, channel managers y marketplaces de actividades hablan entre sí. Una integración contra SurfBooking, y la oferta queda legible por cualquier comprador OCTO. Para quien lo prefiera, también devolvemos el formato nativo SB y variantes para adaptadores existentes.

Cinco tipos de socio. Una API.

Si distribuyes experiencias — un hotel, una agencia, un DMC, una app de turismo o una plataforma de alojamiento — la API de SurfBooking pone disponibilidad real de clases de surf en tus manos.

Cómo funciona.

Una integración. Todas las escuelas de la plataforma. Plazas reales, precios reales, anti-overbooking — confirmado en milisegundos.

Cada socio se conecta solo a lo que le sirve.

No es la misma API para todos. Cada clave está limitada (least-privilege) a lo que ese socio necesita — nunca más que eso.

Las claves de plataforma llevan scopes. Una clave de sizing solo abre los endpoints de sizing — todo lo demás devuelve 403 insufficient_scope.

Tres cosas. Disponibilidad, servicios, reservas.

Todo en REST + JSON, autenticado con la clave de la escuela.

Una llamada y ves la API responder.

El descriptor es público. Pégalo en el terminal:

# ver la API (sin clave)
curl -s https://www.surfbooking.eu/api/partner/v1

Contrato completo, legible por máquina — pensado para que agentes de IA y generadores de SDK autodescubran la API: /openapi.json (OpenAPI 3.1) · referencia interactiva en /docs (Swagger UI).

Reserva en 2 pasos con 2 llamadas — bloquea la plaza mientras tu cliente paga, luego confirma:

# 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 clave de la escuela, lees la disponibilidad — aquí en 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"

Límite: 120 peticiones/min por clave. Cada respuesta trae X-RateLimit-Limit y X-RateLimit-Remaining; al excederlo recibes 429 con Retry-After: 60.

Un asistente dentro de tu escuela, con una clave solo tuya.

Además de la API de socios, cada escuela puede conectar un asistente MCP a su propia operación. Está desactivado por defecto y aún no se ha validado con un cliente real.

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

Límites: 60 llamadas por minuto por clave y 2000 al día. Sin herramientas de dinero, y nada se aplica sin la confirmación del propietario. El detalle está en la página MCP. /mcp

Una clave por escuela. Tú mandas.

Cada escuela genera su propia clave en SurfBooking OS — y la revoca cuando quiera. La clave va en una cabecera, en cualquiera de los dos formatos:

Genera y revoca claves en SurfBooking OS → Canales de venta → API Socios. Nunca guardamos la clave en claro — solo su resumen.

Los endpoints.

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

El descriptor — GET /api/partner/v1 (sin clave):

{
  "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" }
  }
}

Identidad del proveedor — 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": "…" }
}

Petición y respuesta, de verdad.

El cuerpo de una reserva y lo que recibes de vuelta — tal como la API responde hoy.

Crear una reserva — 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"
  }'

Respuesta — 201 Created:

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

Disponibilidad en OCTO — GET /availabilities?format=octo devuelve 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/…" }
  }
]

Precios en céntimos (minor units) — 3500 = 35,00 €, conforme al currencyPrecision: 2 de OCTO. Las fechas vienen en hora local de la escuela (Europe/Lisbon).

La misma disponibilidad en otros formatos. 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" }
}

Otro sistema de reservas — ?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" }
    }
  ]
}

Otro sistema de reservas — ?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 respuesta es un array simple (sin envelope). En sb/fh viene en availabilities; en bl, en data.

Códigos de estado.

Cada error trae un cuerpo JSON { "error": "…" } — legible por máquina.

Clave ausente o inválida — 401:

# sin cabecera de clave
{
  "error": "missing_api_key",
  "hint": "Set X-Partner-API-Key header (or Authorization: Bearer)"
}

# clave inexistente o revocada
{ "error": "invalid_api_key" }

Sin plazas suficientes (anti-overbooking) — 409:

# la clase ya no tiene plazas para el nº de participantes
{
  "error": "insufficient_spots",
  "remaining": 1
}

# externalRef repetido → idempotencia: devuelve el bookingId existente
{
  "error": "external_ref_exists",
  "bookingId": "f1e2d3c4-…"
}

La revalidación de plazas y ratios corre dentro de una transacción con SELECT … FOR UPDATE — agotado es agotado, nunca hay doble reserva.

Lo que puedes pedir, y cuánto.

Estos tres números se leen del código que sirve la API, no se escriben aquí a mano: si cambian allí, esta página queda mal y hay una prueba que lo dice.

Recomienda el equipo correcto. Sin tocar las reservas.

El camino v2 para marcas de equipamiento, apps e IA. Clave de plataforma con scope sizing, forecast y/o brand:read — determinista, sin datos personales, nunca toca reservas. Descubre tus scopes en /api/partner/v2/meta. Base: https://www.surfbooking.eu/api/partner/v2.

Recomendación de tabla — 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" } }

Las claves de plataforma (sbpd_…) las emite SurfBooking, no la escuela. Scope equivocado → 403 insufficient_scope. Límite 240 peticiones/min por clave, con Retry-After: 60 al excederlo.

Tallas en tu web. Una línea.

Una página iframe autocontenida, "Powered by SurfBooking". Muestra las condiciones del spot, recomienda la tabla por peso y nivel, y lleva al cliente a reservar una clase — con tu enlace de socio premium incorporado. Sin PII, sin cookies de seguimiento.

<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 = tu clave de plataforma (scope sizing, y forecast si quieres las condiciones arriba). spot y slug son opcionales — el slug liga las reservas generadas a tu /aff (cookie de 90 días).

v1 — estable.

La base es /api/partner/v1. Los cambios que rompen compatibilidad entran en una versión nueva (/v2) — la v1 no tiene depreciación prevista. Podemos añadir campos sin aviso, así que lee de forma tolerante: ignora lo que aún no conozcas.

Channel managers, marketplaces, hoteles.

Cualquier socio que quiera vender o mostrar clases de surf reales. Diseñado sobre el estándar abierto OCTO, que muchos sistemas de reservas y channel managers ya hablan.

La escuela manda. Siempre.