Operaciones de recursos y material

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

Consulta, crea, edita y borra recursos y material, con sus tallas y unidades, por API v1 o MCP.

Un recurso es el material físico que respalda un producto de alquiler: la tabla que se presta, el neopreno que se reparte por tallas, el barco con sus plazas. Buky distingue tres tipos: material simple (tablas, kayaks… unidades intercambiables), material por tallas (neoprenos, trajes… primero la talla, luego las unidades de esa talla) y material de transporte (barco, furgoneta… con una capacidad fija de plazas en vez de unidades sueltas). El recurso nunca lleva impuesto ni precio; eso vive en el producto vendible que lo referencia, el alquiler. Por dentro, Buky guarda con el mismo modelo las camas y habitaciones de un alojamiento, así que varias de estas operaciones (añadir unidades, renombrar o borrar un hijo, identificar un identificador) sirven también para alojamientos, y se indica en cada una.

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. Si quieres el contexto completo del inventario, está Gestionar el inventario en la base de conocimiento.

get-resource: consulta un material por nombre o identificador

Devuelve el documento completo y actualizado de un material: la forma de comprobar cómo quedó tras crearlo o editarlo. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

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

Por MCP: «Enséñame el material camiseta».

Parámetros

Qué devuelve

Ejecución real, con el material por tallas «camiseta» ya existente en la cuenta demo:

{
  "success": true,
  "_id": "6a37e7cb5c498030c4a194cf",
  "resolved": { "id": "6a37e7cb5c498030c4a194cf", "reason": "match exacto 'camiseta'" },
  "item": { "title": { "es": "camiseta" }, "type": "SizedRental",
    "children": ["6a37e7db5c498030c4a19535", "6a37e7dc30e0c1f575f76ae0"], "taxes": [] }
}

item.type es el subtipo (BasicRental, SizedRental o TransportRental); item.children son sus tallas o unidades directas.

Errores propios: nombre sin coincidencia → resource_unresolved, con resource_candidates listando el material real de la cuenta.

Consejos: úsala tras crear o editar para confirmar cómo quedó de verdad. Para identificar un identificador suelto sin saber su nombre, usa identify-resource.

create-resource: crea un material nuevo

Crea el recurso raíz: solo el material, sin stock todavía. El stock se añade después con add-resource-units o add-resource-sizes. Es una operación de escritura.

Cómo llamarla

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

Por MCP: «Crea un material por tallas llamado Neoprenos Demo».

Parámetros

Qué devuelve

Prueba en seco de un material por tallas:

{ "dry_run": true, "success": true,
  "resolved_type": { "type": "SizedRental", "reason": "match exacto 'SizedRental'" },
  "payload_preview": { "title": { "es": "Neoprenos Demo" }, "type": "SizedRental" },
  "stock_hint": "Añade tallas con add-resource-sizes y units por talla con add-resource-units." }

Si pasas thumb o gallery, la respuesta añade images_pending (las URLs o identificadores que se importarán) e images_missing (los que no se han encontrado). Prueba en seco real con una URL de foto: "images_pending": ["https://ejemplo.com/foto.jpg"], "images_missing": [].

Errores propios: TransportRental sin capacity → capacity_required; capacity en simple/por tallas → rechazado (el stock de esos tipos se añade como unidades).

Consejos: elige bien el type desde el principio, no se puede cambiar después. Tras crear, añade el stock con add-resource-units (simple/transporte) o add-resource-sizes + add-resource-units (por tallas).

update-resource: edita un material existente

Edita título, descripción, etiquetas y, solo en material de transporte, la capacidad. PUT parcial: solo cambia lo que pases; no toca unidades ni tallas. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-resource \
  -H "Authorization: Bearer bk_TU_TOKEN" -H "Content-Type: application/json" \
  -d '{"resource": "camiseta", "title": "Camiseta técnica", "dry_run": true}'

Por MCP: «Cambia el título del material camiseta a Camiseta técnica».

Parámetros

Qué devuelve

Prueba en seco real, sobre «camiseta»:

{ "dry_run": true, "success": true, "_id": "6a37e7cb5c498030c4a194cf",
  "changes": { "title": { "es": "Camiseta técnica" } },
  "note": "PUT parcial: solo estos campos cambian. Sin impuesto. No toca tallas ni unidades." }

Si pasas thumb o gallery, la respuesta añade images_check con refs (lo que pediste), urls (lo resuelto) y missing (lo que no se encontró). Prueba en seco real con una URL de foto: "images_check": { "refs": ["https://ejemplo.com/foto.jpg"], "urls": ["https://ejemplo.com/foto.jpg"], "missing": [], "ok": true }.

Consejos: para renombrar una talla o unidad concreta usa rename-resource-child. Antes de tocar tags, consulta con get-resource para no perder etiquetas al reemplazar la lista.

delete-resource: borra un material

Borra el material raíz. El material deja de verse en el panel. No puedes deshacerlo desde la API ni desde el asistente, pero el soporte de Buky puede recuperarlo si lo necesitas. Tampoco arrastra sus hijos: las unidades o tallas quedan huérfanas, apuntando a un material borrado. Es una operación de escritura.

Cómo llamarla

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

Por MCP: «Borra el material camiseta».

Parámetros

Qué devuelve

Prueba en seco real, con «camiseta» (2 tallas):

{ "dry_run": true, "success": true,
  "would_delete": { "_id": "6a37e7cb5c498030c4a194cf", "name": "camiseta", "type": "SizedRental" },
  "reversible": true, "dependencies": { "children": 2 },
  "warnings": ["el material tiene 2 child(ren) (units/sizes) que quedarán huérfanos"] }

dependencies.children cuenta tallas o unidades que no se borrarán con él; warnings avisa cuando hay hijos que quedarían huérfanos.

Consejos: si tiene hijos, bórralos antes uno a uno con delete-resource-child, o acepta que queden huérfanos (no rompen nada, pero tampoco se ven en ningún sitio útil). Si te equivocas, el soporte de Buky puede recuperarlo.

add-resource-sizes: añade una talla a un material por tallas

Añade una talla nueva (S, M, 42…) a un material SizedRental. La talla no es reservable todavía: sus unidades se añaden después con add-resource-units. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/add-resource-sizes \
  -H "Authorization: Bearer bk_TU_TOKEN" -H "Content-Type: application/json" \
  -d '{"parent": "camiseta", "label": "XL", "dry_run": true}'

Por MCP: «Añade la talla XL al material camiseta».

Parámetros

Qué devuelve

Prueba en seco real, añadiendo «XL» a «camiseta»:

{ "dry_run": true, "success": true, "parent_id": "6a37e7cb5c498030c4a194cf", "label": "XL",
  "payload_preview": { "title": { "es": "XL" }, "type": "size", "parent": "6a37e7cb5c498030c4a194cf" } }

Consejos: crea una talla por llamada (para S, M y L hacen falta tres). Después, añade sus unidades con add-resource-units usando el identificador de la talla como parent.

add-resource-units: añade unidades (stock) a un material o a una talla

Añade N unidades físicas reservables. Sirve para material simple, de transporte, o una talla concreta; también para camas y habitaciones de un alojamiento (el contenedor se busca en ambos catálogos). El tipo de hoja se deduce del contenedor. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/add-resource-units \
  -H "Authorization: Bearer bk_TU_TOKEN" -H "Content-Type: application/json" \
  -d '{"parent": "<id-de-la-talla-o-material>", "count": 3, "dry_run": true}'

Por MCP: «Añade 3 unidades a la talla S del material camiseta».

Parámetros

Qué devuelve

Prueba en seco real, añadiendo 3 unidades a la talla «S» de «camiseta» (que ya tenía 2):

{ "dry_run": true, "success": true, "parent_type": "size", "child_type": "unit", "created_count": 3,
  "payload_preview": [{ "title": { "es": "Unidad 3" }, "parent": "6a37e7db5c498030c4a19535", "type": "unit" }, "..."] }

Errores propios: parent es un SizedRental raíz (no una talla) → parent_not_container: primero hace falta crear una talla.

Consejos: para material por tallas, crea antes la talla con add-resource-sizes y usa su identificador como parent. Las unidades se numeran solas; puedes renombrarlas después con rename-resource-child.

delete-resource-child: borra una talla o una unidad

Borra un hijo concreto: unidad, talla o (en alojamientos) cama o habitación. Si borras una talla con unidades, esas unidades no se borran con ella: quedan huérfanas. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/delete-resource-child \
  -H "Authorization: Bearer bk_TU_TOKEN" -H "Content-Type: application/json" \
  -d '{"child": "<id-de-la-unidad-o-talla>", "confirm": true, "dry_run": true}'

Por MCP: «Borra la unidad 2 del material camiseta».

Parámetros

Qué devuelve

Prueba en seco real, sobre la talla «S» de «camiseta» (2 unidades):

{ "dry_run": true, "success": true,
  "would_delete": { "_id": "6a37e7db5c498030c4a19535", "type": "size", "title": { "es": "S" } },
  "reversible": true, "dependencies": { "children": 2 },
  "warnings": ["la talla tiene 2 unidad(es) que quedarán huérfanas: el sistema no las borra en cascada"] }

Consejos: pasa el identificador cuando lo tengas; el título solo funciona bien si es único (usa parent si no). Si te equivocas, el soporte de Buky puede recuperarlo.

rename-resource-child: renombra una talla o una unidad

Cambia solo el nombre de un hijo (unidad, talla, cama o habitación); no toca nada más. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/rename-resource-child \
  -H "Authorization: Bearer bk_TU_TOKEN" -H "Content-Type: application/json" \
  -d '{"child": "<id-de-la-talla-o-unidad>", "title": "S (nueva etiqueta)", "dry_run": true}'

Por MCP: «Renombra la talla S del material camiseta a S (nueva etiqueta)».

Parámetros

Qué devuelve

Prueba en seco real, renombrando la talla «S» de «camiseta»:

{ "dry_run": true, "success": true, "_id": "6a37e7db5c498030c4a19535", "child_type": "size",
  "changes": { "title": { "es": "S (reetiquetada)" } }, "note": "PUT parcial: solo el nombre cambia." }

Consejos: sirve igual para una unidad suelta («Tabla roja») que para una talla o, en alojamientos, una cama o habitación.

identify-resource: traduce un identificador suelto a qué es de verdad

Cuando tienes un identificador opaco —el de un bloqueo de calendario, el parent de otra operación— y no sabes si es un material, una talla, una unidad, un alojamiento o una habitación, esta operación lo traduce, sube la cadena de pertenencia hasta la raíz y dice con qué operaciones se trabaja. Es una operación de solo lectura.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/identify-resource?resource=6a37e7db5c498030c4a19535" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «¿Qué es este identificador: 6a37e7db5c498030c4a19535?».

Parámetros

Qué devuelve

Ejecución real, identificando la talla «S» del material «camiseta»:

{ "success": true, "identity": {
  "kind": "talla de un material", "title": "S",
  "chain": [{ "_id": "6a37e7db5c498030c4a19535", "kind": "talla de un material", "title": "S" },
            { "_id": "6a37e7cb5c498030c4a194cf", "kind": "material de alquiler (por tallas)", "title": "camiseta" }],
  "root": { "_id": "6a37e7cb5c498030c4a194cf", "kind": "material de alquiler (por tallas)", "title": "camiseta" },
  "related_operations": ["add-resource-sizes", "rename-resource-child", "delete-resource-child"] } }

identity.kind dice qué es en lenguaje claro; identity.chain es su cadena de pertenencia hasta la raíz; identity.root es la entidad de catálogo sobre la que realmente se opera.

Consejos: úsala antes de operar a ciegas sobre un identificador que no reconoces. Con full: true obtienes también el documento crudo.