Operaciones de actividades

Miguel Gómez Pérez · Equipo Bukyapp· 4 min de lectura·Actualizado 17 sept 2026

Lista, consulta, crea, edita y borra actividades por API v1 o MCP: tarifas, cupos, sesiones, personal y publicación.

Una actividad es el producto base de Buky: una clase, salida o experiencia reservable con fecha, hora, aforo y, opcionalmente, personal asignado. Es lo que tus clientes ven y reservan en el motor de reservas, y lo que tú organizas en sesiones desde el panel. Más sobre el concepto en Qué es una actividad en BukyApp.

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.

list-activities: lista las actividades del centro

Devuelve el catálogo de actividades del centro. Es el paso previo natural para encontrar el identificador exacto de una actividad antes de editarla o borrarla, y admite tres niveles de detalle según lo que necesites ver. Es de solo lectura: vale con cualquier token.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/list-activities?q=surf" \
  -H "Authorization: Bearer bk_TU_TOKEN"

curl -X POST https://api.bukyapp.com/v1/ops/list-activities \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"q": "surf", "detail": "descriptive", "lang": "es"}'

Por MCP: «Enséñame las actividades que tengo» o «Busca las actividades que tengan "surf" en el nombre».

Parámetros

Qué devuelve

Vista compact (por defecto), ejemplo real recortado:

{
  "success": true,
  "detail": "compact",
  "count": 13,
  "total": 13,
  "items": [
    { "_id": "5b98cbdc749e2af7dda1da69", "title": "Actividad", "internalName": null, "categories": [], "is_disabled": false, "private": false, "pax_min": 1, "pax_max": null },
    { "_id": "69dba4e53f831f958dbdff7c", "title": "Surf Avanzado", "internalName": null, "categories": [], "is_disabled": false, "private": false, "pax_min": 1, "pax_max": null }
  ]
}

Vista descriptive con lang: "es", ejemplo real recortado:

{
  "success": true,
  "detail": "descriptive",
  "count": 13,
  "total": 13,
  "items": [
    {
      "_id": "5b98cbdc749e2af7dda1da69",
      "title": "Actividad",
      "internalName": null,
      "short_description": null,
      "description": "descripción de la actividad",
      "included": [], "not_included": [], "requirements": [],
      "alert_text": "La hora de la clase puede variar según las condiciones meteorológicas",
      "level": null,
      "meeting_point": null,
      "cancellation_policy_mode": "general",
      "cancellation_policy": null,
      "categories": [],
      "payment_mode": "none",
      "payment_advance_mode": "percent",
      "payment_advance_percent": 20,
      "payment_advance_fixed": 0,
      "need_pax_data": false,
      "is_disabled": false,
      "private": false,
      "by_request": false,
      "not_bookable_standalone": false,
      "pax_min": 1,
      "pax_max": null,
      "duration_min": 60
    }
  ]
}

Las actividades borradas no aparecen aquí.

Consejos

• Con dos actividades con el mismo título (pasa: en la cuenta de ejemplo hay dos «surf de prueba c1»), pide full:true o cruza por internalName para no operar sobre la que no toca.
• detail:"descriptive" es el punto intermedio entre compact y full: sirve para mostrarle el catálogo a un cliente o revisar textos, sin cargar tarifas ni flags internos.

get-activity: detalle completo de una actividad

Devuelve el documento completo y fresco de una actividad: tarifas, impuesto, capacidad, modo de reserva, personal, todo. Es la forma de comprobar cómo quedó una actividad tras crearla o editarla, y de conseguir su identificador exacto. Es de solo lectura: vale con cualquier token.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-activity?activity=Surf%20Principiante%20en%20piscina" \
  -H "Authorization: Bearer bk_TU_TOKEN"

curl -X POST https://api.bukyapp.com/v1/ops/get-activity \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activity": "Surf Principiante en piscina"}'

Por MCP: «Enséñame el detalle de la actividad Surf Principiante en piscina».

Parámetros

Qué devuelve

Ejemplo real, recortado (esta actividad concreta hereda sus sesiones de otra, ver más abajo):

{
  "success": true,
  "_id": "6aa3db20f4b405ea4e3dfc20",
  "resolved": { "id": "6aa3db20f4b405ea4e3dfc20", "reason": "match exacto por nombre 'Surf Principiante en piscina'" },
  "item": {
    "_id": "6aa3db20f4b405ea4e3dfc20",
    "title": { "es": "Surf Principiante en piscina" },
    "activities_capacity": 6,
    "activities_duration": 60,
    "activities_bookingMode": "scheduled_in_other_activity",
    "activities_useSessionsFrom": "69dba4d4b227f96a4e3b21a8",
    "activities_private": false,
    "notBookableStandalone": false,
    "haveRatesByPersonRange": false,
    "priceFrom": 6000,
    "taxes": ["69a181ce5d6272575493bcfd"],
    "rates": [
      { "description": { "name": "Adulto" }, "price": 6000, "season": null, "_id": "6aa3dc3601ec3b760f91c62d" },
      { "description": { "name": "Temporada 2027" }, "price": 7500, "season": { "start": "2027-01-01", "end": "2027-06-21", "active": true }, "_id": "6aa3dc3697a76a5a4a6279a2" }
    ]
  }
}

Errores propios

create-activity: crea una actividad nueva

Crea una actividad con su modo de precio, personal y calendario. Es una operación de escritura: consulta siempre primero list-activities para no duplicar por error, y prueba en seco antes de confirmar.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-activity \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prueba documentación",
    "internal_name": "prueba-documentacion",
    "price_eur": 30,
    "color": "#1273de",
    "capacity": 6,
    "dry_run": true
  }'

Por MCP: «Crea una actividad llamada Prueba documentación a 30€, con 6 plazas y color azul».

Parámetros

Modo de precio: elige uno de estos tres (mandar más de uno da error):

Datos básicos y sesiones:

Personal y publicación (opcionales; se resumen porque son muchos):

Qué devuelve

Prueba en seco real:

{
  "success": true,
  "dry_run": true,
  "applied_defaults": { "activities_capacity": 6, "activities_bookingMode": "scheduled", "activities_color": "#1273de" },
  "resolved_tax": { "id": "69a181ce5d6272575493bcfd", "reason": "default (primer tax del customer)" },
  "resolved_pricing": { "mode": "flat", "base": { "name": "Adulto", "price_cents": 3000, "via": "priceFrom (sin rates, como el front)" } },
  "payload_preview": { "title": { "es": "Prueba documentación" }, "activities_capacity": 6, "internalName": "prueba-documentacion", "priceFrom": 3000, "activities_color": "#1273de" },
  "warnings": [
    "ACTIVIDAD AÚN NO VENDIBLE: se creó con priceFrom pero SIN tarifas. PASO 2 OBLIGATORIO: update-activity con rates:[{name,price_eur,quantity:1}]."
  ]
}

Consejos

• En modo plano (`price_eur`), la actividad se crea sin tarifa todavía vendible: solo queda el precio «desde» (priceFrom), y la respuesta lo avisa con warnings. Para que sea reservable de verdad, sigue con update-activity mandando rates: [{"name": "Adulto", "price_eur": 30, "quantity": 1}]. Esto no lo dice el manual de forma explícita: se ha comprobado en la ejecución.
• capacity, duration y color son la base de las sesiones que se generen para esta actividad; si trabajas con sesiones sueltas, revisa también Operaciones de sesiones.
• Antes de crear, ejecuta list-activities con el nombre que vas a usar para comprobar que no exista ya.
• Con thumb o gallery, una URL pública queda a la espera de subida: la prueba en seco lo muestra en images_pending (verificado en ejecución). Una ruta de archivo local ya no funciona: la operación no la reconoce ni como identificador ni como URL.

update-activity: edita una actividad existente

Cambia solo los campos que le pases: el resto de la actividad queda intacto. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-activity \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "activity": "Prueba documentación",
    "title": "Prueba documentación editada",
    "price_eur": 32,
    "capacity": 8,
    "dry_run": true
  }'

Por MCP: «Cambia el título de Prueba documentación a "Prueba documentación editada" y súbele el precio a 32€».

Parámetros

El resto son opcionales (se agrupan por bloque porque son muchos; cada uno reemplaza el valor anterior salvo que se indique lo contrario):

Qué devuelve

Prueba en seco real:

{
  "success": true,
  "dry_run": true,
  "_id": "6aa3db20f4b405ea4e3dfc20",
  "changes": {
    "title": { "es": "Prueba documentación editada" },
    "activities_capacity": 8,
    "rates": [
      { "description": { "name": "Adulto" }, "price": 3200, "season": null, "_id": "6aa3dc3601ec3b760f91c62d" },
      { "description": { "name": "Temporada 2027" }, "price": 7500, "season": { "start": "2027-01-01", "end": "2027-06-21" }, "_id": "6aa3dc3697a76a5a4a6279a2" }
    ]
  },
  "note": "PUT parcial: solo estos campos cambian."
}

Consejos

• Al cambiar price_eur, la respuesta reenvía la tabla de tarifas completa (rates) aunque solo hayas tocado la primera: es la actividad real, no un cálculo aparte. Compruébala si la actividad tiene tarifas por temporada.
• Cambiar el title se propaga a las sesiones futuras de esa actividad.
• Con thumb o gallery, la prueba en seco confirma la URL en images_check antes de aplicarla (verificado en ejecución); si mandas una ruta local en vez de un identificador o una URL, no la reconoce.

delete-activity: borra una actividad

La actividad deja de verse en el panel y en la tienda. No puedes deshacerlo desde la API ni desde el asistente, pero el soporte de Buky puede recuperarla si lo necesitas. Antes de borrar, avisa de las sesiones futuras y de si tienen reservas. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/delete-activity \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activity": "Prueba documentación", "confirm": true, "dry_run": true}'

Por MCP: «Borra la actividad Prueba documentación» (el asistente te pedirá confirmación antes de marcar confirm: true).

Parámetros

Qué devuelve

Prueba en seco real, con confirm: true:

{
  "success": true,
  "dry_run": true,
  "would_delete": { "_id": "6a35694ba0cc4a3ec76347cd", "name": "surf de test 4" },
  "soft_deleted": false,
  "reversible": true,
  "dependencies": {
    "future_sessions": 0,
    "future_sessions_with_bookings": 0,
    "note": "El server NO borra estas sesiones ni bloquea: quedarán apuntando a la actividad borrada. Las reservas existentes siguen vivas (libéralas vía Order)."
  },
  "warnings": []
}

Errores propios

Consejos

• Si dependencies.future_sessions_with_bookings es mayor que 0, gestiona esas reservas antes de borrar: el borrado no las toca ni las libera.