Operaciones de sesiones

Juan José Vélez Medina · Equipo Bukyapp· 4 min de lectura·Actualizado 17 sept 2026

Lista, consulta, crea, edita y borra sesiones de tus actividades, una a una o en bloque, por API v1 o MCP.

Una sesión es una clase, salida o turno concreto de una actividad: un día y una hora con un aforo, y opcionalmente personal, ubicación o barco asignados. Es lo que ve tu cliente cuando reserva y lo que gestionas cada día en el calendario. Más sobre cómo se crean y organizan en Añadir sesiones y gestionar el calendario.

Las bases comunes (autenticación, GET frente a POST, prueba en seco, errores HTTP, límites) están en API v1 — Introducción y primeros pasos. Las sesiones cuelgan siempre de una actividad ya creada: ver Operaciones de actividades. En todas estas operaciones, customer_id se toma de tu token: solo hace falta indicarlo con tokens multicuenta, así que no aparece en las tablas de parámetros de esta página.

list-sessions: agenda de sesiones de una actividad

Operación de solo lectura. Lista las sesiones de una actividad en un rango de fechas, igual que el calendario del panel. Si no indicas actividad, funciona como agenda general con todas las actividades.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/list-sessions?activity=Surf%20Principiante%20en%20piscina&from=2026-09-01&to=2026-10-31" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame las sesiones de Surf Principiante en piscina entre el 1 de septiembre y el 31 de octubre».

Parámetros

Qué devuelve

Ejecutando la operación de verdad para «Surf Principiante en piscina» entre el 1 de septiembre y el 31 de octubre de 2026, hoy esa actividad no tiene ninguna sesión programada en ese rango:

{
  "success": true,
  "mode": "activity",
  "resolved_activity": { "id": "6aa3db20f4b405ea4e3dfc20", "reason": "match exacto por nombre 'Surf Principiante en piscina'" },
  "count": 0,
  "total": 0,
  "range": { "from": "2026-09-01", "to": "2026-10-31" },
  "items": [],
  "warnings": []
}

Así es una sesión real de esa misma agenda (sin filtrar por actividad, mismo rango; pertenece a «Surf Principiante», la actividad hermana sin «en piscina»):

{
  "_id": "69dbaf7eb227f96a4e3ba8bb",
  "activity": { "_id": "69dba4d4b227f96a4e3b21a8", "title": "Surf Principiante" },
  "start": "2026-09-01T07:00:00.000Z",
  "end": "2026-09-01T09:00:00.000Z",
  "capacity": 10,
  "repeat_id": "69dbaf7eb227f96a4e3ba856"
}

Errores propios

Consejos

• El aforo (capacity) no descuenta reservas de forma exacta; para saber cuántas plazas quedan de verdad usa get-avail.
• Guarda el _id de la sesión que te interese: es lo único que aceptan get-session, update-session y delete-session, ya que las sesiones no tienen un nombre propio.

get-session: consulta el documento completo de una sesión

Operación de solo lectura. Devuelve la sesión completa y al momento, tal y como está en ese instante: es la forma de comprobar cómo quedó una sesión tras crearla o editarla.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-session?session=69dbaf7eb227f96a4e3ba8bb" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame el detalle de la sesión 69dbaf7eb227f96a4e3ba8bb».

Parámetros

El manual marca session como «recomendado», pero al ejecutar la operación sin él, Buky responde con error: en la práctica es obligatorio.

Qué devuelve

{
  "success": true,
  "_id": "69dbaf7eb227f96a4e3ba8bb",
  "resolved": { "id": "69dbaf7eb227f96a4e3ba8bb", "reason": "lookup directo por _id" },
  "item": {
    "_id": "69dbaf7eb227f96a4e3ba8bb",
    "title": { "es": "Surf Principiante", "en": "Beginner Surf" },
    "activity": "69dba4d4b227f96a4e3b21a8",
    "start": "2026-09-01T07:00:00.000Z",
    "end": "2026-09-01T09:00:00.000Z",
    "capacity": 10,
    "capacityMode": "fixed",
    "private": false,
    "staff": [],
    "locations": [],
    "repeat": true,
    "repeat_id": "69dbaf7eb227f96a4e3ba856",
    "repeat_end": "2026-09-30T00:00:00.000Z",
    "shop_hidden": false
  }
}

Errores propios

create-session: crea una sesión sobre una actividad existente

Operación de escritura. Crea una sesión puntual o una serie semanal repetida, colgada siempre de una actividad ya existente.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-session \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activity": "Surf Principiante en piscina", "start": "2026-09-22T10:00:00.000Z", "end": "2026-09-22T11:30:00.000Z", "capacity": 8}'

Por MCP: «Crea una sesión de Surf Principiante en piscina el 22 de septiembre de 10:00 a 11:30 para 8 personas».

Parámetros

Qué devuelve

Prueba en seco, con dry_run: true:

{
  "success": true,
  "dry_run": true,
  "resolved_activity": { "id": "6aa3db20f4b405ea4e3dfc20", "title": "Surf Principiante en piscina" },
  "resolved_profile": { "profile": "single", "repeat": false },
  "payload_preview": {
    "activity": "6aa3db20f4b405ea4e3dfc20",
    "title": { "es": "Surf Principiante en piscina" },
    "start": "2026-09-22T10:00:00.000Z",
    "end": "2026-09-22T11:30:00.000Z",
    "capacity": 8,
    "repeat": false
  },
  "warnings": []
}

Consejos

• Si omites title o capacity, la sesión hereda los de la actividad: revisa el resultado si esperabas otra cosa.
• En una serie, repeat_end es inclusive: para que la última sesión sea el día 26, pon repeat_end en el día 26, no en el 27.

update-session: edita una sesión existente

Operación de escritura. Edición parcial por session_id: solo cambia los campos que envíes, el resto queda igual.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-session \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "69dbaf7eb227f96a4e3ba8bb", "capacity": 12, "dry_run": true}'

Por MCP: «Cambia el aforo de la sesión 69dbaf7eb227f96a4e3ba8bb a 12 plazas».

Parámetros

Hace falta pasar al menos uno de los campos editables además de session_id: si no, la operación falla.

Qué devuelve

Prueba en seco, cambiando solo el aforo:

{
  "success": true,
  "dry_run": true,
  "_id": "69dbaf7eb227f96a4e3ba8bb",
  "changes": { "capacity": 12 },
  "warnings": []
}

Errores propios

Consejos

• Los días y horarios de una serie repetida no se editan desde aquí campo a campo: afecta solo a la sesión indicada.
• Para saber el resultado final tras editar, confírmalo con get-session.

delete-session: borra una sesión

Operación de escritura. Borrado definitivo (físico, no hay papelera) de una sesión concreta por su session_id. No existe una operación para recuperarla después.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/delete-session \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "69dbaf7eb227f96a4e3ba8bb", "confirm": true}'

Por MCP: «Borra la sesión 69dbaf7eb227f96a4e3ba8bb» (el asistente te pedirá confirmar antes de ejecutar de verdad).

Parámetros

Qué devuelve

Prueba en seco (con este script, confirm: true también se muestra en modo dry-run; nunca borra de verdad):

{
  "success": true,
  "dry_run": true,
  "would_delete": { "_id": "69dbaf7eb227f96a4e3ba8bb" },
  "reversible": false,
  "warnings": [
    "IRREVERSIBLE: la sesión se borrará FÍSICAMENTE; no hay restauración posible.",
    "Si la sesión tiene RESERVAS, el server NO la borrará (sin error): la operación lo detecta y lo avisa aquí."
  ]
}

Consejos

• Si la sesión tiene reservas, Buky no la borra y no da ningún error: simplemente sigue existiendo. Compruébalo con get-session si esperabas que hubiese desaparecido.

delete-sessions-bulk: borra toda una serie de sesiones repetidas

Operación de escritura. Borra de golpe todas las sesiones que comparten la misma serie repetida (el mismo repeat_id), no una sola sesión. Es un borrado definitivo: cuantas más sesiones tenga la serie, mayor el alcance del borrado.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/delete-sessions-bulk \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repeat_id": "69dbaf7eb227f96a4e3ba856", "confirm": true}'

Por MCP: «Borra toda la serie de sesiones repetidas 69dbaf7eb227f96a4e3ba856» (pide confirmación antes de ejecutar de verdad).

Parámetros

Tienes que dar repeat_id o session_id: si no mandas ninguno de los dos, la operación falla. El manual los marca como «recomendado» y «opcional», pero en la práctica hace falta uno de ellos.

Qué devuelve

Prueba en seco sobre una serie real de 122 sesiones (recortada a las dos primeras):

{
  "success": true,
  "dry_run": true,
  "repeat_id": "69dbaf7eb227f96a4e3ba856",
  "series_size": 122,
  "would_delete": [
    { "session_id": "69dbaf7eb227f96a4e3ba857", "start": "2026-04-14T07:00:00.000Z", "end": "2026-04-14T09:00:00.000Z", "capacity": 10 },
    { "session_id": "69dbaf7eb227f96a4e3ba858", "start": "2026-04-15T07:00:00.000Z", "end": "2026-04-15T09:00:00.000Z", "capacity": 10 }
  ],
  "reversible": false,
  "warnings": [
    "BLAST RADIUS: se borrarían 122 sesiones de la serie 69dbaf7eb227f96a4e3ba856, de una vez.",
    "IRREVERSIBLE: las sesiones se borran FÍSICAMENTE; no hay restauración posible.",
    "Si alguna sesión tiene RESERVAS, el server NO la borrará (sin error): el ledger lo reflejará (borrado parcial)."
  ]
}

Si al confirmar de verdad alguna sesión de la serie tiene reservas, Buky no la borra: el resultado final distingue las sesiones que sí se borraron de las que siguen existiendo por tener reservas, para que sepas si la serie quedó limpia del todo o solo en parte.

Errores propios

Consejos

• Antes de confirmar, mira siempre series_size: es el número real de sesiones que desaparecerán.
• Consigue el repeat_id con list-sessions: cada sesión de una serie lo trae.