Operaciones de alquileres

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

Consulta, crea, edita y borra alquileres y enlázalos al material que los respalda por API v1 o MCP.

Un alquiler en Buky es un producto vendible: lo que el cliente final reserva y paga, con su título, su impuesto y sus tarifas. Por debajo, ese producto no es el material en sí — referencia el material real que tienes en inventario (tablas, kayaks, neoprenos, un barco…), agrupado en variaciones. El material se gestiona aparte, con sus propias operaciones, y un alquiler solo lo enlaza: puedes crear el producto y, en otro paso, conectarlo con el material que ya existe. Esa parte vive en Operaciones de recursos y material. Si quieres el contexto completo, está también la página Qué son los alquileres y cómo funcionan de la base de conocimiento.

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. Todas toman el centro de tu token salvo que uses uno multicuenta.

list-rentals: enumera los alquileres vendibles

Lista los productos de alquiler vendibles de tu cuenta: identificador, título y variaciones (no el material en sí). Es la forma de ver qué hay sin tener que provocar un error en get-rental para descubrirlo. Los alquileres borrados nunca aparecen. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

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

curl -X POST https://api.bukyapp.com/v1/ops/list-rentals \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"detail": "descriptive", "disabled": false}'

Por MCP: «¿Qué alquileres tengo configurados?».

Parámetros

Qué devuelve

Ejecución real: en esta cuenta todavía no hay ningún alquiler creado.

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

Consejos

• Úsala primero para saber qué alquileres existen y con qué nombre exacto, antes de llamar a get-rental, update-rental o delete-rental.
• Con un catálogo grande, combina q con limit para no traer documentos de más.

get-rental: consulta un alquiler por nombre o identificador

Devuelve el documento completo y actualizado de un alquiler, tal como está en ese momento. Es la forma de comprobar cómo quedó tras crearlo o editarlo, y de obtener su identificador exacto. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-rental?rental=Alquiler%20de%20Tablas%20de%20Surf" \
  -H "Authorization: Bearer bk_TU_TOKEN"

curl -X POST https://api.bukyapp.com/v1/ops/get-rental \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rental": "Alquiler de Tablas de Surf"}'

Por MCP: «Enséñame el alquiler de Tablas de Surf».

Parámetros

Qué devuelve

En la cuenta demo no hay ningún alquiler creado todavía, así que la ejecución real devuelve esto:

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

Cuando el nombre sí resuelve a un alquiler, la respuesta trae además _id (el identificador exacto), resolved (qué se eligió y por qué) e item: el documento completo, con título, impuesto, variaciones y tarifas.

Errores propios

Consejos

• Úsala después de un create-rental o update-rental para confirmar cómo quedó el alquiler de verdad, no lo que pediste.
• Si candidates viene vacío, en esa cuenta todavía no se ha creado ningún alquiler. Con list-rentals compruebas el catálogo entero sin tener que adivinar un nombre.

create-rental: crea el producto de alquiler vendible

Crea el producto que el cliente final reserva: título, impuesto y variaciones que agrupan el material. No lleva precio al crearlo — el precio se añade después con update-rental. El material que referencies en las variaciones debe existir ya (créalo antes en Operaciones de recursos y material); aquí solo se enlaza. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-rental \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Alquiler de Kayaks",
    "variations": [{ "name": "Personas", "resources": [{ "resource": "Kayaks", "quantity": 1 }] }],
    "dry_run": true
  }'

Por MCP: «Crea un alquiler llamado Alquiler de Kayaks que use el material Kayaks».

Parámetros

Qué devuelve

Prueba en seco, con un material que sí existe en la cuenta demo (una camiseta de alquiler):

{
  "dry_run": true,
  "success": true,
  "resolved_tax": { "id": "69a181ce5d6272575493bcfd", "reason": "default (primer tax del customer)" },
  "resolved_variations": [
    { "name": "Personas", "mode": "single", "materials": [{ "resource": "6a37e7cb5c498030c4a194cf", "quantity": 1 }] }
  ],
  "payload_preview": {
    "type": "Rental",
    "title": { "es": "Alquiler de Kayaks" },
    "rentals_timeslot_day": true,
    "rentals_variations": [
      { "name": { "es": "Personas" }, "mode": "single", "pax": { "from": 1, "to": 1 }, "max": -1,
        "resources": [{ "resource": "6a37e7cb5c498030c4a194cf", "quantity": 1 }] }
    ],
    "taxes": ["69a181ce5d6272575493bcfd"]
  },
  "price_hint": "El producto se crea SIN precio (el front bloquea Tarifas hasta guardar). Añade las tarifas con un update posterior."
}

La prueba en seco no llega a crear nada, así que no trae identificador. Al crear de verdad (fuera de una prueba en seco), la respuesta añade _id: el identificador del alquiler recién creado, el que necesitas para las siguientes llamadas.

Errores propios

Consejos

• Crea primero el material (tablas, kayaks…) y después el alquiler que lo referencia: el orden inverso falla.
• En cuanto lo crees, ponle precio con update-rental: sin tarifas, el producto no se puede vender.

update-rental: edita el producto de alquiler

Edita el alquiler ya creado: título, impuesto, tarifas, variaciones, modo de pago, disponibilidad por día/hora/semana/mes, categorías y extras. Importante: rates, variations, categories y extras reemplazan el conjunto entero, no lo completan — pasa siempre la lista completa que quieres que quede, no solo lo que cambia. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-rental \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rental": "Alquiler de Kayaks", "rates": [{"variation": "Personas", "price_eur": 25}], "dry_run": true}'

Por MCP: «Ponle precio de 25 euros al Alquiler de Kayaks».

Parámetros

También acepta ajustes menos frecuentes: precio «desde», texto de aviso, descripción, granularidad de la disponibilidad, antelación mínima para reservar, nombre interno, exigir datos de cada participante, modo de check-in online y horario de apertura por franjas. Todos opcionales; están en el manual si los necesitas.

Qué devuelve

En la cuenta demo, sin ningún alquiler creado, la prueba en seco da:

{
  "dry_run": true,
  "success": false,
  "error": "rental_unresolved",
  "details": "el customer no tiene productos rental (vendibles) configurados",
  "candidates": [],
  "hint": "Especifica el PRODUCTO Rental (nombre/título o _id). Para el MATERIAL usa update-resource."
}

Con un alquiler existente, la prueba en seco devuelve en su lugar changes: el detalle de lo que cambiaría, sin llegar a guardarlo. Al editar de verdad, la respuesta trae también _id: el identificador del alquiler editado.

Errores propios

Consejos

• Antes de tocar rates, variations, categories o extras, consulta el alquiler con get-rental para saber qué hay y no perder nada al reemplazar la lista.
• Para editar el material en sí (tablas, barco…) usa las operaciones de recursos, no esta.

delete-rental: borra el producto de alquiler

Borra el producto vendible: no toca el material que referencia, que sigue existiendo de forma independiente. El producto 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 recuperarlo si lo necesitas. Es una operación de escritura.

Cómo llamarla

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

Por MCP: «Borra el alquiler de Kayaks».

Parámetros

Qué devuelve

Prueba en seco real, sin alquileres en la cuenta:

{
  "dry_run": true,
  "success": false,
  "error": "rental_unresolved",
  "details": "el customer no tiene productos rental (vendibles) configurados",
  "candidates": [],
  "hint": "Especifica el PRODUCTO Rental (nombre/título o _id) entre candidates. Para el MATERIAL usa delete-resource."
}

Con un alquiler real, un borrado confirmado devuelve _id (el identificador del alquiler borrado), soft_deleted: true y reversible.

Errores propios

Consejos

• Si te equivocas, el soporte de Buky puede recuperarlo.
• Borrar el alquiler no borra el material: las tablas, kayaks o el barco siguen disponibles para otro producto.

link-rental-material: enlaza material a un alquiler

Conecta un material ya existente (una tabla, un kayak, un neopreno…) con el alquiler que lo vende, añadiéndolo a una de sus variaciones. No crea nada nuevo: relaciona dos cosas que ya existen, el producto y el material. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/link-rental-material \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parent": "Alquiler de Kayaks", "material": "Kayaks", "quantity": 2, "dry_run": true}'

Por MCP: «Enlaza el material Kayaks al alquiler de Kayaks, con 2 unidades».

Parámetros

Qué devuelve

Prueba en seco real, sin alquileres creados en la cuenta:

{
  "dry_run": true,
  "success": false,
  "error": "parent_unresolved",
  "details": "el customer no tiene productos rental (vendibles) configurados",
  "parent_candidates": [],
  "hint": "Especifica el producto rental PADRE (nombre/título o _id) entre parent_candidates."
}

Con un alquiler y un material reales, la respuesta trae parent_id, material_id, variation_id y already_linked (si el material ya estaba enlazado, no lo duplica).

Errores propios

Consejos

• El alquiler debe tener ya al menos una variación (la crea create-rental); si no tiene ninguna, esta operación no puede enlazar nada.
• Es idempotente: puedes repetir la llamada sin miedo a duplicar el material en la variación.