Aulas de surf reais, numa chamada à API.

Sem protocolo fechado. Falamos OCTO — o standard aberto das reservas de atividades.

OCTO (octo.travel) é como os sistemas de reservas, channel managers e marketplaces de atividades falam entre si. Uma integração contra a SurfBooking, e a oferta fica legível por qualquer comprador OCTO. Para quem prefere, também devolvemos o formato nativo SB e variantes para adaptadores existentes.

Cinco tipos de parceiro. Uma API.

Se distribuis experiências — um hotel, uma agência, um DMC, uma app de turismo ou uma plataforma de alojamento — a API da SurfBooking coloca disponibilidade real de aulas de surf nas tuas mãos.

Como funciona.

Uma integração. Todas as escolas da plataforma. Vagas reais, preços reais, anti-overbooking — confirmado em milissegundos.

Cada parceiro liga só ao que lhe serve.

Não é a mesma API para todos. Cada chave é limitada (least-privilege) ao que esse parceiro precisa — nunca mais do que isso.

As chaves de plataforma carregam scopes. Uma chave de sizing só abre os endpoints de sizing — tudo o resto devolve 403 insufficient_scope.

Três coisas. Disponibilidade, serviços, reservas.

Tudo em REST + JSON, autenticado por chave da escola.

Uma chamada e vês a API a responder.

O descritor é público. Cola no terminal:

# ver a API (sem chave)
curl -s https://www.surfbooking.eu/api/partner/v1

Contrato completo, máquina-legível — pensado para agentes de IA e geradores de SDK auto-descobrirem a API: /openapi.json (OpenAPI 3.1) · referência interativa em /docs (Swagger UI).

Reserva em 2 passos com 2 chamadas — segura a vaga enquanto o teu cliente paga, depois 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"

Com a chave da escola, lês a disponibilidade — aqui em 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 pedidos/min por chave. Cada resposta traz X-RateLimit-Limit e X-RateLimit-Remaining; ao exceder recebes 429 com Retry-After: 60.

Um assistente dentro da tua escola, com uma chave só tua.

Além da API de parceiros, cada escola pode ligar um assistente MCP à sua própria operação. Está desligado por defeito e ainda não foi validado com um cliente real.

Ferramentas: 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 chamadas por minuto por chave e 2000 por dia. Sem ferramentas de dinheiro, e nada se aplica sem a confirmação do dono. O detalhe está na página MCP. /mcp

Uma chave por escola. Tu controlas.

Cada escola gera a sua própria chave no Centro de Controlo — e revoga-a quando quiser. A chave segue num cabeçalho, em qualquer um dos dois formatos:

Gera e revoga chaves em Centro de Controlo → Canais de venda → API Parceiros. Nunca guardamos a chave em claro — só o seu resumo.

Os endpoints.

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

O descritor — GET /api/partner/v1 (sem chave):

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

Identidade do fornecedor — 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": "…" }
}

Pedido e resposta, a sério.

O corpo de uma reserva e o que recebes de volta — tal como a API responde hoje.

Criar uma 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"
  }'

Resposta — 201 Created:

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

Disponibilidade em OCTO — GET /availabilities?format=octo devolve um 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/…" }
  }
]

Preços em cents (minor units) — 3500 = 35,00 €, conforme currencyPrecision: 2 do OCTO. As datas vêm em hora local da escola (Europe/Lisbon).

A mesma disponibilidade noutros formatos. Nativo SB — ?format=sb (envelope com _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" }
}

Outro 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" }
    }
  ]
}

Outro 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" }
    }
  ]
}

Em octo a resposta é um array simples (sem envelope). Em sb/fh vem em availabilities; em bl, em data.

Códigos de estado.

Cada erro traz um corpo JSON { "error": "…" } — legível por máquina.

Chave em falta ou inválida — 401:

# sem cabeçalho de chave
{
  "error": "missing_api_key",
  "hint": "Set X-Partner-API-Key header (or Authorization: Bearer)"
}

# chave inexistente ou revogada
{ "error": "invalid_api_key" }

Sem vagas suficientes (anti-overbooking) — 409:

# a aula já não tem lugares para o nº de participantes
{
  "error": "insufficient_spots",
  "remaining": 1
}

# externalRef repetido → idempotência: devolve o bookingId existente
{
  "error": "external_ref_exists",
  "bookingId": "f1e2d3c4-…"
}

A revalidação de vagas e rácios corre dentro de uma transação com SELECT … FOR UPDATE — esgotado é esgotado, nunca há dupla-marcação.

O que podes pedir, e quanto.

Estes três números são lidos do código que serve a API, não escritos aqui à mão: se mudarem lá, esta página fica errada e há uma prova a dizê-lo.

Recomenda o equipamento certo. Sem tocar em reservas.

O caminho v2 para marcas de equipamento, apps e IA. Chave de plataforma com scope sizing, forecast e/ou brand:read — determinístico, sem dados pessoais, nunca toca em reservas. Descobre os teus scopes em /api/partner/v2/meta. Base: https://www.surfbooking.eu/api/partner/v2.

Recomendação de prancha — 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" } }

As chaves de plataforma (sbpd_…) são emitidas pela SurfBooking, não pela escola. Scope errado → 403 insufficient_scope. Limite 240 pedidos/min por chave, com Retry-After: 60 ao exceder.

Sizing no teu site. Uma linha.

Uma página iframe self-contained, "Powered by SurfBooking". Mostra as condições do pico, recomenda a prancha pelo peso e nível, e leva o cliente a reservar uma aula — com o teu link de parceiro premium embutido. PII-free, sem cookies de seguimento.

<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 = a tua chave de plataforma (scope sizing, e forecast se quiseres as condições no topo). spot e slug são opcionais — o slug liga as reservas geradas ao teu /aff (cookie de 90 dias).

v1 — estável.

A base é /api/partner/v1. Mudanças que quebram compatibilidade entram numa versão nova (/v2) — a v1 não tem depreciação prevista. Podemos acrescentar campos sem aviso, por isso lê de forma tolerante: ignora o que ainda não conheces.

Channel managers, marketplaces, hotéis.

Qualquer parceiro que queira vender ou mostrar aulas de surf reais. Desenhado no padrão aberto OCTO, que muitos sistemas de reservas e channel managers já falam.

A escola manda. Sempre.