Operaciones de bonos

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

Consulta, crea, edita y borra bonos de sesiones con sus tarifas, caducidad y actividades por API v1 o MCP.

Un bono es un producto que vende créditos: el cliente paga por un número de sesiones o inmersiones y las va canjeando cuando quiere, con una fecha de caducidad. Estas operaciones te dejan enumerar, consultar, crear, editar y borrar bonos por API o por tu asistente de IA. Más sobre el concepto en Qué es un bono de clases.

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-bonoclasses: enumera los bonos del centro

Devuelve el catálogo de bonos: identificador, título, nombre interno, categorías y las tarifas de créditos que vende cada uno. Es el paso previo natural para encontrar el identificador exacto de un bono antes de editarlo o borrarlo. Es de solo lectura: vale con cualquier token.

Cómo llamarla

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

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

Por MCP: «Enséñame los bonos que tengo» o «Busca los bonos que tengan "inmersiones" en el nombre».

Parámetros

Qué devuelve

Ejecución real: la cuenta demo usada para esta página no tiene ningún bono creado todavía, así que la respuesta viene vacía:

{
 "success": true,
 "detail": "compact",
 "count": 0,
 "total": 0,
 "items": [],
 "warnings": []
}

Según el manual, cada elemento de items en vista compact trae:

Los bonos borrados nunca aparecen aquí.

Consejos

• Antes de crear un bono con create-bonoclass, ejecuta list-bonoclasses con el nombre que piensas usar: si ya existe uno parecido, evitas duplicarlo.

get-bonoclass: consulta el detalle completo de un bono

Devuelve el documento completo y actualizado de un bono, resuelto por nombre o por identificador. Es de solo lectura: vale con cualquier token. Es la forma correcta de comprobar «cómo quedó» un bono tras crearlo o editarlo, y de obtener su identificador exacto.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-bonoclass?bonoclass=Bono%2010%20inmersiones" \
  -H "Authorization: Bearer bk_TU_TOKEN"

curl -X POST https://api.bukyapp.com/v1/ops/get-bonoclass \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bonoclass": "Bono 10 inmersiones"}'

Por MCP, pídeselo directamente a tu asistente: «Enséñame el detalle del bono Bono 10 inmersiones».

Parámetros

Qué devuelve

La cuenta demo usada para esta página no tiene ningún bono creado todavía, así que la ejecución real con un nombre inventado devuelve esto:

{
 "success": false,
 "error": "bonoclass_unresolved",
 "details": "el customer no tiene ninguna entidad de este tipo configurada",
 "candidates": [],
 "hint": "El customer no tiene ningún bono configurado todavía."
}

Cuando el bono existe, la respuesta trae, además de success y operation: _id (el identificador del bono), resolved (qué bono se eligió y por qué) e item: el documento completo y fresco (título, tarifas, actividades, caducidad, impuestos…).

Errores propios

Consejos

• Si el nombre es ambiguo, la respuesta trae candidates con las opciones: repite la llamada con el identificador exacto.
• Úsala después de create-bonoclass o update-bonoclass para confirmar el resultado con datos frescos, sin caché.

create-bonoclass: crea un bono con sus tarifas y caducidad

Crea un bono nuevo: título, tarifas de créditos, caducidad y, opcionalmente, a qué actividades da acceso. Es una operación de escritura; el token no puede tocar usuarios del panel, reembolsos ni pagos, pero sí crear productos como este.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-bonoclass \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bono 10 inmersiones",
    "rates": [{ "quantity": 10, "price": 360 }],
    "expiration": 365,
    "activities": ["Inmersión guiada"],
    "dry_run": true
  }'

Por MCP: «Crea un bono de 10 inmersiones a 360 euros, caduca a los 365 días, válido para Inmersión guiada».

Parámetros

Qué devuelve

Prueba en seco real, creando «Bono 10 sesiones de prueba»:

{
 "success": true,
 "dry_run": true,
 "resolved_rates": [
  { "quantity": 10, "price": 15000, "description": { "name": "Bono 10" } }
 ],
 "resolved_activities": [
  { "id": "69dba4d4b227f96a4e3b21a8", "reason": "match exacto por nombre 'Surf Principiante'" }
 ],
 "resolved_taxes": [
  { "id": "69a181ce5d6272575493bcfd", "reason": "default (primer tax del customer)" }
 ],
 "resolved_categories": [],
 "payload_preview": {
  "title": { "es": "Bono 10 sesiones de prueba", "en": "New", "…": "…" },
  "activities": ["69dba4d4b227f96a4e3b21a8"],
  "rates": [{ "quantity": 10, "price": 15000 }],
  "taxes": ["69a181ce5d6272575493bcfd"],
  "expiration": 365
 },
 "warnings": []
}

Al crear de verdad (sin dry_run), la respuesta añade _id con el identificador del bono recién creado.

Errores propios

Consejos

• Si tu bono tiene varios tamaños («2 inmersiones», «4 inmersiones»…), usa varias entradas en rates en vez de crear un bono por tamaño.
• Si omites activities, comprueba con get-bonoclass a qué actividades queda ligado el bono antes de publicarlo.
• Para las actividades que puede canjear el bono, mira Operaciones de actividades.

update-bonoclass: edita un bono existente

Edita un bono con un PUT parcial: solo se cambian los campos que le pasas, el resto queda igual. Si pasas rates, activities, taxes, categories o extras, ese campo se reemplaza entero, no se combina con lo que ya había. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-bonoclass \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bonoclass": "Bono 10 inmersiones",
    "title": "Bono 10 inmersiones PRO",
    "dry_run": true
  }'

Por MCP: «Cambia el título del bono Bono 10 inmersiones a "Bono 10 inmersiones PRO"».

Parámetros

Qué devuelve

La cuenta demo no tiene ningún bono creado, así que la prueba en seco no llega a resolver uno y devuelve esto:

{
 "success": false,
 "dry_run": true,
 "error": "bonoclass_unresolved",
 "details": "el customer no tiene bonos configurados",
 "candidates": [],
 "hint": "Especifica el bono (título o _id) entre candidates."
}

Cuando el bono sí existe y se resuelve, la respuesta trae _id, changes (qué campos cambiaron), resolved_rates, resolved_activities, resolved_taxes, resolved_categories y warnings.

Errores propios

Consejos

• Si solo quieres previsualizar el cambio, no hace falta nada especial: por API pública, añade "dry_run": true.
• Al reemplazar rates o activities, repite también los valores que quieras conservar: no se fusionan con los anteriores.

delete-bonoclass: da de baja un bono

El bono deja de verse en el catálogo y en la tienda. No puedes deshacerlo desde la API ni desde el asistente, pero el soporte de Buky puede recuperarlo si lo necesitas. Los créditos ya vendidos de ese bono siguen siendo válidos para los clientes que los compraron. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/delete-bonoclass \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "bonoclass": "Bono 10 sesiones", "confirm": true, "dry_run": true }'

Por MCP: «Borra el bono Bono 10 sesiones».

Parámetros

Qué devuelve

La cuenta demo no tiene ningún bono, así que la prueba en seco devuelve:

{
 "success": false,
 "dry_run": true,
 "error": "bonoclass_unresolved",
 "details": "el customer no tiene bonos configurados",
 "candidates": [],
 "hint": "Especifica el bono (título o _id) entre candidates."
}

Cuando el bono existe, la respuesta trae _id, soft_deleted: true, reversible: true y warnings.

Errores propios

Consejos

• confirm: true es la única forma de que esta operación llegue a borrar algo; sin él, es siempre una prueba en seco.
• Si te equivocas, el soporte de Buky puede recuperarlo.