Operaciones de imágenes

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

Sube imágenes a tu biblioteca de medios desde una URL o un fichero y úsalas como destacada o galería de tus productos por API v1 o MCP.

Cada cuenta de Buky tiene una biblioteca de medios propia: las imágenes que subes quedan guardadas ahí, con un identificador (_id), y desde ahí se asocian a tus productos. Los parámetros thumb y gallery aparecen en el create-* y el update-* de actividades (Operaciones de actividades), alojamientos (Operaciones de alojamientos), packs, alquileres, bonos, recursos y personal: thumb es la foto destacada; gallery es la galería completa y, al editar, la reemplaza entera (no añade fotos, sustituye la lista). Cada uno admite el _id de una imagen ya subida o directamente una URL pública: en ese caso el servidor la importa con las mismas guardas que create-upload.

Flujo recomendado: si vas a reutilizar la imagen o no sabes aún cuál usar, primero create-upload para conseguir el _id y luego el update-* del producto con ese identificador en thumb o gallery. Si ya tienes la URL de la imagen que quieres, puedes pasarla directamente en thumb/gallery del create-*/update-* del producto, sin pasar por create-upload.

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.

create-upload: sube una imagen a la biblioteca de medios

Sube una imagen nueva a la biblioteca de medios de la cuenta y devuelve su _id y su URL pública, listos para usar en thumb/gallery de cualquier producto. Es una operación de escritura.

Cómo llamarla

Desde una URL pública (la fuente habitual cuando lo pide un asistente):

curl -X POST https://api.bukyapp.com/v1/ops/create-upload \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://ejemplo.com/fotos/curso.jpg", "dry_run": true}'

Desde un fichero en disco, en base64 (la fuente habitual desde un script):

curl -X POST https://api.bukyapp.com/v1/ops/create-upload \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file": {"name": "curso.jpg", "mime": "image/jpeg", "data": "<base64>"}, "dry_run": true}'

Por MCP: adjunta la imagen en el chat o dale la URL y pide «sube esta foto a la biblioteca de imágenes».

Parámetros

dry_run valida la fuente (la URL: tipo y tamaño que declara el servidor de origen; el fichero: se decodifica y se comprueba tipo y tamaño) sin subir nada de verdad.

Qué devuelve

Prueba en seco real, desde una URL:

{
  "success": true,
  "dry_run": true,
  "would_upload": {
    "url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
    "mime": "image/png",
    "size": 224566,
    "redirects": 0
  }
}

Prueba en seco real, desde un fichero:

{
  "success": true,
  "dry_run": true,
  "would_upload": { "filename": "pixel.png", "mime": "image/png", "size": 70 }
}

Errores propios

Consejos

• Si vas a usar la misma imagen en varios productos, súbela una vez con create-upload y reutiliza el _id; si es una imagen puntual para un solo producto, ahórrate el paso y pon la URL directamente en thumb/gallery.
• Antes de confiar en una URL de terceros, prueba primero en seco: los errores (not_an_image, import_blocked, download_failed) te dicen si el problema es el tipo de fichero, el host o la propia descarga, sin gastar la subida real.

delete-upload: borra una imagen de la biblioteca de medios

Borra una imagen de la biblioteca de medios por su _id. El borrado es definitivo: la imagen se borra de verdad y no se puede recuperar. Antes de borrar, la operación avisa de qué productos la usan como destacada o en galería (referenced_by); el servidor no limpia esas referencias, así que si no las cambias antes, se quedan apuntando a una imagen que ya no existe. Es una operación de escritura.

Cómo llamarla

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

Por MCP: «Borra la imagen curso.jpg de mi biblioteca» (el asistente te pedirá confirmación antes de marcar confirm: true).

Parámetros

Qué devuelve

Prueba en seco real, con una imagen que sí está en uso:

{
  "success": true,
  "dry_run": true,
  "_id": "castle-1742379229530.png",
  "would_delete": { "_id": "castle-1742379229530.png" },
  "referenced_by": [
    { "type": "activity", "_id": "62c449644ae50106b7d0bca6", "title": "Nueva actividad", "field": "thumb" }
  ],
  "reversible": false,
  "hard_deleted": false,
  "warnings": [
    "IRREVERSIBLE: el Upload se borrará FÍSICAMENTE; no hay restauración posible.",
    "El fichero existe; que pertenezca a tu customer lo comprueba el borrado real (404 si no).",
    "1 referencia(s) en productos quedarán colgando (el server no las limpia): activity 'Nueva actividad' (thumb)"
  ]
}

Errores propios

Si el identificador tiene la forma correcta pero no corresponde a ninguna imagen, la prueba en seco ya lo detecta: comprueba que el fichero existe y devuelve success: false con error: "upload_not_found" y el motivo en details (por ejemplo, «No existe ningún fichero 'no-existe-1234567890.jpg' (404 en su URL pública)»). Que la imagen sea de tu cuenta se comprueba al ejecutar el borrado real.

Consejos

• Revisa siempre referenced_by antes de confirmar. Si hay productos que la usan y quieres sustituirla en vez de dejarles el hueco, actualízalos primero (update-activity, update-accommodation…) con otra imagen en thumb/gallery.

Listar y consultar imágenes de la biblioteca (list-uploads, get-upload) llegará más adelante. Hoy, el _id lo consigues de la respuesta de create-upload o de la ficha del producto que la usa (get-activity, get-accommodation…), en su campo thumb o gallery.