Operaciones de localizaciones

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

Consulta, crea, edita y borra las localizaciones de tus actividades por API v1 o MCP.

Una localización es el sitio físico donde ocurre algo: el punto de encuentro de una actividad, la

playa donde arranca una clase, el mostrador donde se recoge un alquiler. Buky la usa para que el

cliente sepa adónde ir y para que la asignes a las sesiones de tus actividades.

Sobre cómo se gestionan desde el panel, ver Gestionar localizaciones

en 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. En

las cinco, customer_id se toma de tu token salvo que uses uno multicuenta.

list-locations: enumera las localizaciones de la cuenta

Devuelve las localizaciones del negocio: identificador, título y si está desactivada. Es una

operación de solo lectura: vale con cualquier token. Es la forma de ver qué localizaciones

existen sin tener que provocar un error en get-location.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/list-locations" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame las localizaciones que tengo».

Parámetros

Qué devuelve

Ejecución real, con las dos localizaciones de la cuenta demo:

{
  "success": true,
  "operation": "list-locations",
  "customer_id": "5a55fff67e9fe0036a541d15",
  "detail": "compact",
  "count": 2,
  "total": 2,
  "items": [
    { "_id": "645cdcea660cbe47fe65b750", "title": "nueva", "internalName": null, "is_disabled": false },
    { "_id": "6a357472a0cc4a3ec763b9a8", "title": "playa de prueba", "internalName": null, "is_disabled": false }
  ],
  "warnings": []
}

Consejos

• Antes de crear una localización, mira aquí si ya existe con otro nombre.

get-location: consulta una localización por nombre o identificador

Devuelve el documento completo y actualizado de una localización: la forma de comprobar cómo quedó

tras crearla o editarla. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-location?location=Playa%20de%20Somo" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame la localización Playa de Somo».

Parámetros

Qué devuelve

Ejecución real, con una localización ya existente en la cuenta demo:

{
  "success": true,
  "operation": "get-location",
  "customer_id": "5a55fff67e9fe0036a541d15",
  "_id": "6a357472a0cc4a3ec763b9a8",
  "resolved": { "id": "6a357472a0cc4a3ec763b9a8", "reason": "match por título 'playa de prueba'" },
  "item": {
    "_id": "6a357472a0cc4a3ec763b9a8",
    "type": "Location",
    "title": { "es": "playa de prueba" },
    "description": { "es": "" },
    "isDisabled": false,
    "children": [],
    "gallery": [],
    "createdAt": "2026-06-19T16:55:14.795Z"
  },
  "warnings": []
}

Errores propios de esta operación

Consejos

• Consulta get-location con un nombre aproximado antes de crear una nueva: si no hay match exacto,

la respuesta trae location_candidates con todas las localizaciones existentes y evitas duplicar

una que ya tienes con otro nombre.

create-location: crea una localización nueva

Es de escritura. El ejemplo de esta página se ejecutó en modo prueba: el sistema valida y muestra

qué pasaría, pero no llega a crear nada.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-location \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Muelle de Poniente", "dry_run": true}'

Por MCP: «Crea la localización Muelle de Poniente».

Parámetros

Qué devuelve

Prueba en seco, mínima:

{
  "success": true,
  "dry_run": true,
  "operation": "create-location",
  "applied_defaults": { "type": "Location", "location_capacity_default": 0 },
  "payload_preview": {
    "title": { "es": "Muelle de Poniente", "en": "New", "…": "…" },
    "description": { "es": "", "…": "…" },
    "type": "Location"
  }
}

En la prueba en seco no hay _id: como no se llega a crear nada, no existe todavía. En una

creación real la respuesta trae el _id de la localización creada en su lugar.

Errores propios de esta operación

Consejos

• Si solo quieres el nombre, no mandes location_capacity ni description: es la variante mínima y

la más habitual.

update-location: cambia el nombre o el aforo anual

Es de escritura, con edición parcial: solo cambia lo que le pasas, el resto de la localización

queda igual.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-location \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"location": "Playa de Somo", "title": "Playa de Somo (norte)", "dry_run": true}'

Por MCP: «Cambia el nombre de la localización Playa de Somo a "Playa de Somo (norte)"».

Parámetros

Tienes que pasar al menos uno de title o location_capacity: si no aportas ningún cambio, la

operación responde no_changes (ver más abajo).

Qué devuelve

Prueba en seco cambiando el nombre:

{
  "success": true,
  "dry_run": true,
  "operation": "update-location",
  "_id": "6a357472a0cc4a3ec763b9a8",
  "changes": { "title": { "es": "Playa de Somo (norte)" } }
}

Errores propios de esta operación

delete-location: borra una localización

La localización 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 recuperarla si lo necesitas. Es una operación de escritura. No borra en cascada, así que si

alguna sesión de tus actividades sigue

apuntando a la localización, esa referencia queda colgando sin más efecto.

Cómo llamarla

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

Por MCP: «Borra la localización Muelle de Poniente».

Parámetros

Qué devuelve

Prueba en seco:

{
  "success": true,
  "dry_run": true,
  "operation": "delete-location",
  "would_delete": { "_id": "645cdcea660cbe47fe65b750", "name": "nueva" },
  "soft_deleted": false,
  "reversible": true,
  "warnings": ["las sesiones que referencian esta location quedarán con la ref colgando (impacto menor)"]
}

Errores propios de esta operación

Consejos

• Si te equivocas, el soporte de Buky puede recuperarla.