Operaciones de alojamientos

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

Consulta, crea, edita y borra alojamientos básicos, compartidos y repetidos por API v1 o MCP.

Un alojamiento es el tipo de producto de Buky para vender estancias por noches: una habitación, un apartamento, un bungaló o una cama en un dormitorio compartido. Más sobre el concepto en Qué es un alojamiento en BukyApp.

Al crear uno, Buky distingue tres tipos. Básico: una unidad única e indivisible que se reserva entera, como un apartamento o una villa. Compartido: una unidad con varias camas que se venden por separado, como un dormitorio de hostal. Repetido: varias unidades idénticas que se gestionan desde una sola ficha indicando cuántas hay, como 10 bungalós iguales en un camping. Las camas del compartido y las unidades del repetido no se crean con estas operaciones: se añaden en un paso posterior, ya con el alojamiento creado.

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-accommodations: lista los alojamientos del centro

Devuelve el catálogo de alojamientos del centro: identificador, título, tipo, capacidad y algunos flags. Es el paso previo natural para encontrar el identificador exacto de un alojamiento antes de editarlo o borrarlo. Es de solo lectura: vale con cualquier token.

Cómo llamarla

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

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

Parámetros

Qué devuelve

Ejemplo real, recortado:

{
  "success": true,
  "detail": "compact",
  "count": 6,
  "total": 6,
  "items": [
    { "_id": "5a5602b07e9fe0036a541d16", "title": "Alojamiento simple", "internalName": null, "type": "BasicAccommodation", "categories": [], "is_disabled": false, "private": false, "capacity": 4 },
    { "_id": "6a37ee385c498030c4a22d97", "title": "hostel test", "internalName": "hostel test", "type": "SharedAccommodation", "categories": [], "is_disabled": false, "private": false, "capacity": null }
  ]
}

Los alojamientos borrados no aparecen aquí.

Consejos

• Si no conoces el nombre exacto, usa q con parte del nombre y revisa internalName en la respuesta para no confundir alojamientos con títulos parecidos.

get-accommodation: obtener un alojamiento por nombre o id

Devuelve el documento completo y fresco de un único alojamiento: 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-accommodation?accommodation=Alojamiento%20simple" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame el alojamiento Alojamiento simple».

Parámetros

\* El manual lo marca como «recomendado», pero en la práctica es obligatorio: sin él, la operación falla (ver «Errores propios»).

Qué devuelve

Ejemplo real para un alojamiento básico:

{
  "success": true,
  "_id": "5a5602b07e9fe0036a541d16",
  "resolved": { "id": "5a5602b07e9fe0036a541d16", "reason": "match exacto 'Alojamiento simple'" },
  "item": {
    "_id": "5a5602b07e9fe0036a541d16",
    "type": "BasicAccommodation",
    "title": { "es": "Alojamiento simple", "en": "New", "..." : "..." },
    "capacity": 4,
    "rates": [{ "_id": "5e25b5ac73aa1400007271df", "price": 200, "season": { "active": false } }],
    "stayMin": 1,
    "dayEnter": -1,
    "dayExit": -1,
    "children": [],
    "categories": [],
    "extras": []
  },
  "warnings": []
}

Errores propios

Consejos

• Si no conoces el nombre exacto, llama con cualquier texto: la lista de accommodation_candidates que devuelve te sirve para elegir el _id correcto en la siguiente llamada.

create-accommodation: crear un alojamiento nuevo

Crea un alojamiento raíz: básico por defecto, o compartido/repetido si lo indicas en type. Es una operación de escritura: hace falta un token con permiso de escritura, y necesita al menos una tarifa (price_eur o rates) para guardarse.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-accommodation \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Bungalow Vista Doc", "internal_name": "DOC-TEST-Bungalow Vista", "price_eur": 65, "capacity": 3, "tax": "21%", "dry_run": true}'

Por MCP: «Crea un alojamiento básico llamado Bungalow Vista Doc, 65 € la noche, capacidad 3».

Parámetros

*Datos del alojamiento*

*Precio e impuesto*

Qué devuelve

Prueba en seco de un alojamiento básico:

{
  "success": true,
  "dry_run": true,
  "applied_defaults": { "capacity": 3, "rate_name": "Tarifa Adulto" },
  "resolved_type": { "type": "BasicAccommodation", "reason": "default (BasicAccommodation — alojamiento simple)" },
  "resolved_tax": { "id": "69a181ce5d6272575493bcfd", "reason": "match por percent=21" },
  "resolved_parent": null,
  "payload_preview": {
    "title": { "es": "Bungalow Vista Doc" },
    "type": "BasicAccommodation",
    "taxes": ["69a181ce5d6272575493bcfd"],
    "rates": [{ "description": { "name": "Tarifa Adulto" }, "price": 6500 }],
    "internalName": "DOC-TEST-Bungalow Vista",
    "capacity": 3
  }
}

Ejemplos

Compartido (el dormitorio raíz; las camas se añaden después):

{ "title": "Dormitorio Compartido Doc", "internal_name": "DOC-TEST-Dormitorio Compartido", "price_eur": 22, "type": "SharedAccommodation" }

Errores propios

Consejos

• Necesitas exactamente una de price_eur o rates; no las combines.
• En compartido no envíes capacity: se deriva del número de camas que añadas después.

update-accommodation: editar un alojamiento existente

Edita un alojamiento con un PUT parcial: solo cambia los campos que le pasas, el resto queda igual. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-accommodation \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accommodation": "Alojamiento simple", "title": "Alojamiento Simple Doc", "price_eur": 75, "dry_run": true}'

Por MCP: «Cambia el título de Alojamiento simple a Alojamiento Simple Doc y sube el precio a 75 €».

Parámetros

*Qué alojamiento editar*

*Datos generales*

*Precio y tarifas*

*Capacidad y condiciones de estancia*

*Reservas y pago*

Qué devuelve

Prueba en seco cambiando título y precio:

{
  "success": true,
  "dry_run": true,
  "_id": "5a5602b07e9fe0036a541d16",
  "changes": {
    "title": { "es": "Alojamiento Simple Doc" },
    "rates": [{ "_id": "5e25b5ac73aa1400007271df", "price": 7500, "season": { "active": false } }]
  },
  "note": "PUT parcial: solo estos campos cambian; customer/_id/__v nunca se envían."
}

Errores propios

Consejos

• Si solo quieres tocar el precio de la tarifa base, usa price_eur; para reorganizar todas las tarifas (temporadas, rangos de personas), usa rates completo — no se pueden mezclar.
• categories, extras y tags reemplazan el conjunto entero: si quieres añadir una categoría sin perder las que ya tenía, incluye también las existentes.

delete-accommodation: borrar un alojamiento

El alojamiento 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-accommodation \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accommodation": "Surf House Doc Ficticio", "confirm": true, "dry_run": true}'

Por MCP: «Borra el alojamiento Surf House Doc Ficticio».

Parámetros

Qué devuelve

Prueba en seco sobre un alojamiento compartido con camas:

{
  "success": true,
  "dry_run": true,
  "would_delete": { "_id": "6a37ee385c498030c4a22d97", "name": "hostel test" },
  "soft_deleted": false,
  "reversible": true,
  "dependencies": {
    "children": 5,
    "note": "El server NO borra los children (units/camas) en el soft-delete: quedarán apuntando al alojamiento borrado (HUÉRFANOS). Las reservas existentes siguen vivas."
  },
  "warnings": ["el alojamiento tiene 5 child(ren) (units/camas) que quedarían HUÉRFANOS"]
}

Errores propios

Consejos

• Si el alojamiento tiene camas o unidades (compartido o repetido), bórralas o reasígnalas antes: el borrado no las arrastra y quedan huérfanas.