Operaciones de categorías

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

Lista, crea, edita y borra las categorías de tu catálogo por API v1 o MCP.

Las categorías agrupan tus productos (actividades, alojamientos, packs, alquileres, bonos, extras o

tienda) para que el cliente los encuentre por pestañas en tu catálogo público. Estas operaciones

listan, crean, editan y borran categorías. Sobre qué son y cómo se organizan de cara al

cliente, ver Gestionar categorías y etiquetas.

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. En

las cinco, customer_id se toma de tu token salvo que uses uno multicuenta.

list-categories: lista las categorías de tu negocio

Solo lectura: vale con cualquier token. Es el catálogo que usan las demás operaciones cuando

referencias una categoría por nombre, así que conviene consultarlo antes de crear una nueva para no

duplicar («Surf» y «surf» y «Cursos de surf»).

Cómo llamarla

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

Por MCP: «¿Qué categorías tengo creadas?», «Lista las categorías que contengan surf» o «¿Qué

categorías tengo desactivadas?».

Parámetros

Qué devuelve

Ejemplo real, vista compacta (la de por defecto):

{
  "success": true,
  "operation": "list-categories",
  "customer_id": "5a55fff67e9fe0036a541d15",
  "detail": "compact",
  "count": 2,
  "total": 2,
  "items": [
    { "_id": "69bc294ac2395a856d55d2c7", "title": "Clase", "is_disabled": false },
    { "_id": "6a37efe25c498030c4a25ea3", "title": "pruebas", "is_disabled": false }
  ]
}

Con detail:"descriptive" y lang:"es", el título llega ya resuelto a un idioma y cada categoría

trae sus subcategorías (lista vacía si no tiene ninguna):

{
  "success": true,
  "operation": "list-categories",
  "detail": "descriptive",
  "count": 2,
  "total": 2,
  "items": [
    { "_id": "69bc294ac2395a856d55d2c7", "title": "Clase", "is_disabled": false, "children": [] },
    { "_id": "6a37efe25c498030c4a25ea3", "title": "pruebas", "is_disabled": false, "children": [] }
  ]
}

Consejos

• Usa disabled:true para encontrar categorías que ocultaste y que ya no ves en el catálogo.

create-category: crea una categoría nueva

Es de escritura. El ejemplo de esta página se ejecutó en modo prueba: el sistema valida y muestra

qué pasaría, pero no llega a crear nada.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-category \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Buceo", "dry_run": true}'

Por MCP: «Crea una categoría llamada Buceo».

Parámetros

Qué devuelve

Prueba en seco con un divisor y un producto enlazado:

{
  "success": true,
  "dry_run": true,
  "operation": "create-category",
  "resolved_children": [
    { "index": 0, "type": "subtitle", "title": "Iniciación", "reason": "divisor con título" },
    { "index": 1, "type": "product", "product": "69dba4d4b227f96a4e3b21a8", "reason": "match exacto por nombre 'Surf Principiante'" }
  ],
  "payload_preview": {
    "title": { "es": "Cursos", "en": "New", "de": "New", "…": "…" },
    "children": [
      { "type": "subtitle", "title": { "es": "Iniciación", "…": "…" } },
      { "type": "product", "product": "69dba4d4b227f96a4e3b21a8" }
    ]
  }
}

En la prueba en seco no hay _id: como no se llega a crear nada, no existe todavía. En una

creación real la respuesta trae el _id de la categoría creada en su lugar.

Errores propios de esta operación

Consejos

• Consulta list-categories antes de crear, para no duplicar una que ya existe con otro nombre.
• Si solo quieres el título, no mandes children: es la variante mínima y la más habitual.

update-category: cambia el título o la visibilidad

Es de escritura, con edición parcial: solo cambia lo que le pasas, el resto de la categoría queda

igual.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-category \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"category": "Surf", "title": "Surf y bodyboard", "dry_run": true}'

Por MCP: «Cambia el nombre de la categoría Surf a "Surf y bodyboard"» u «Oculta la categoría Surf del catálogo».

Parámetros

Qué devuelve

Prueba en seco cambiando el título:

{
  "success": true,
  "dry_run": true,
  "operation": "update-category",
  "_id": "69bc294ac2395a856d55d2c7",
  "changes": { "title": { "es": "Clases de surf" } }
}

Errores propios de esta operación

Consejos

• Los productos enlazados a una categoría (children de tipo producto) no se tocan desde aquí: ese

enlace se gestiona desde la ficha del producto, no desde la categoría.

delete-category: borra una categoría

Es de escritura. La categoría deja de verse en el panel y en el catálogo público. No puedes

deshacerlo desde la API ni desde el asistente, pero el soporte de Buky puede recuperarla si lo

necesitas. No borra en cascada, así que si algún producto sigue apuntando a la categoría, esa

referencia queda colgando sin más efecto.

Cómo llamarla

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

Por MCP: «Borra la categoría Buceo».

Parámetros

Qué devuelve

Prueba en seco:

{
  "success": true,
  "dry_run": true,
  "operation": "delete-category",
  "would_delete": { "_id": "6a37efe25c498030c4a25ea3", "name": "pruebas" },
  "soft_deleted": false,
  "reversible": true,
  "warnings": ["borrado limpio (sin cascada): posibles referencias colgando a esta categoría son menores"]
}

Errores propios de esta operación

Consejos

• Si te equivocas, el soporte de Buky puede recuperarla.