Operaciones de bloqueos de calendario

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

Lista, crea y borra bloqueos de calendario por API v1 o MCP.

Un bloqueo cierra fechas de una unidad de alojamiento, un material de alquiler o un miembro del personal para que no se puedan reservar, sin ser una reserva real: no tiene cliente, ni pago, ni pedido. Se crea a mano desde el calendario (por obras, vacaciones o mantenimiento) o llega importado automáticamente por un enlace iCal de un canal externo. Más sobre cómo se hace desde el panel en Gestionar la disponibilidad y bloquear fechas.

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. El identificador de tu cuenta se toma siempre de tu token; solo hace falta pasarlo con tokens multicuenta.

list-blocks: consulta los bloqueos activos

Devuelve los bloqueos del calendario, con quién los creó (a mano o por iCal) y detecta los que quedaron huérfanos tras desconectar un canal. Nunca devuelve reservas reales. Es de solo lectura: vale con cualquier token.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/list-blocks?from=2026-09-01&to=2026-12-31" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «¿Qué bloqueos tengo entre septiembre y diciembre?» o «Muéstrame los bloqueos huérfanos».

Parámetros

Qué devuelve

Ejemplo real, sin filtros, en la cuenta demo (un único bloqueo manual):

{
  "success": true,
  "operation": "list-blocks",
  "customer_id": "5a55fff67e9fe0036a541d15",
  "count": 1,
  "total": 1,
  "breakdown": { "manual": 1, "ical": 0, "orphans": 0, "by_dead_cal": {} },
  "items": [
    {
      "_id": "694658a75c898dd607a4fde3",
      "resource": "5a5602b07e9fe0036a541d16",
      "start": "2025-12-01T23:00:00.000Z",
      "end": "2025-12-03T23:00:00.000Z",
      "notes": null,
      "origin": "manual"
    }
  ],
  "warnings": []
}

Probé el rango pedido (septiembre-diciembre de 2026) y devolvió count: 0: el único bloqueo de la cuenta demo es de diciembre de 2025, fuera de rango. El filtro por rango y por resource funcionan como describe el manual.

Consejos

• Para ver de un vistazo cuántos bloqueos huérfanos tienes antes de pedir a soporte que los limpie, ejecuta esta operación con only_orphans: true: te da el desglose sin tocar nada.
• Si resource no te dice nada, resuélvelo con get-resource, get-accommodation o get-staff según el tipo de unidad.

create-block: bloquea fechas de un recurso

Crea un bloqueo sobre una unidad de alojamiento, una unidad de material de alquiler o un miembro del personal. Un bloqueo impide reservas nuevas; no cancela ni toca las que ya existen, y se exporta también por iCal a tus canales sincronizados. Es una operación de escritura: siempre se ejecuta en modo prueba (dry_run: true), aquí y por MCP.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-block \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource": "Habitación Doble", "start_date": "2026-10-01", "end_date": "2026-10-03", "notes": "Obras", "dry_run": true}'

Por MCP: «Bloquea la Habitación Doble del 1 al 3 de octubre por obras».

Parámetros

Qué devuelve

Prueba en seco bloqueando una habitación dos noches:

{
  "success": true,
  "operation": "create-block",
  "dry_run": true,
  "resolved_resource": { "_id": "5a5602b07e9fe0036a541d16", "type": "BasicAccommodation", "title": "Alojamiento simple" },
  "semantics": { "branch": "accommodation", "end_date_meaning": "día de salida (esa noche NO se bloquea)", "nights_blocked": 2 },
  "payload_preview": {
    "type": "Blocked",
    "startDate": "2026-09-30T22:00:00.000Z",
    "endDate": "2026-10-02T22:00:00.000Z",
    "resource": "5a5602b07e9fe0036a541d16",
    "mode": "unique",
    "notes": "Mantenimiento"
  },
  "warnings": ["NO idempotente: si el rango solapa con un booking/bloqueo existente del recurso, el server responderá 400 collision."]
}

Con un material de alquiler con tallas (unidad hoja, un día suelto), el bloqueo es por días y end_date es inclusive:

{
  "semantics": { "branch": "rental_staff", "end_date_meaning": "último día bloqueado inclusive (+1d en el body)", "days_blocked": 1 },
  "payload_preview": { "startDate": "2026-09-30T22:00:00.000Z", "endDate": "2026-10-01T22:00:00.000Z", "resource": "6a37ed55a0cc4a3ec77c6a5b" }
}

Y con personal, por horas, el intervalo es exacto (sin redondeos):

{
  "semantics": { "branch": "hourly", "end_date_meaning": "instante exacto de fin (intervalo [start, end), sin ajustes)", "hours_blocked": 4 },
  "payload_preview": { "startDate": "2026-10-01T08:00:00.000Z", "endDate": "2026-10-01T12:00:00.000Z", "resource": "602a2edd48bcd3005f403474" }
}

Errores propios de esta operación

Consejos

• Si te da resource_is_parent, repite la llamada con uno de los identificadores de candidates: son las unidades finales, las únicas que se pueden bloquear.
• Revisa siempre semantics antes de confirmar: el significado de end_date cambia según el tipo de unidad y es la causa más común de bloquear una noche de más o de menos.
• El bloqueo no comprueba colisiones en la prueba en seco; se comprueba al ejecutar de verdad. Si sospechas solape, revisa antes con list-blocks filtrando por resource y rango.

delete-block: borra un bloqueo por su identificador

Borra un bloqueo de calendario por su block_id. Se niega si el identificador no corresponde a un bloqueo vivo de tu cuenta —porque no existe, ya está borrado o pertenece a una reserva real—, así que nunca toca una reserva por error. Es una operación de escritura: siempre se ejecuta en modo prueba.

Cómo llamarla

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

Por MCP: «Borra el bloqueo del 1 al 3 de diciembre en la Habitación Doble» (el asistente lo busca antes con list-blocks).

Parámetros

Qué devuelve

Prueba en seco sobre un bloqueo real de la cuenta demo:

{
  "success": true,
  "operation": "delete-block",
  "dry_run": true,
  "_id": "694658a75c898dd607a4fde3",
  "would_delete": {
    "block_id": "694658a75c898dd607a4fde3",
    "resource": "5a5602b07e9fe0036a541d16",
    "start": "2025-12-01T23:00:00.000Z",
    "end": "2025-12-03T23:00:00.000Z",
    "notes": null,
    "origin": "manual"
  },
  "reversible": "soft (isDeleted en BD, sin endpoint de restore)",
  "warnings": []
}

Errores propios de esta operación

Consejos

• Consigue el block_id con list-blocks antes de borrar; no lo adivines.
• Para limpiar de golpe los bloqueos huérfanos de un enlace iCal desconectado, contacta con el soporte de Buky en vez de borrarlos uno a uno.