Operaciones de clientes

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

Lista, consulta, crea, edita, borra e importa fichas de cliente por API v1 o MCP.

Un «cliente» es la ficha de cada persona que reserva contigo: nombre, contacto, documento, dirección, etiquetas y notas internas. Es distinto del usuario del panel: aquí hablamos de quien compra, no de quien administra la cuenta. Para ver esta ficha desde el panel, consulta Ver el perfil y el historial de un cliente.

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. La página API pública — Clientes (customerClients) documenta la consulta de estas mismas fichas por la API anterior de Buky; esta página es la de la API v1 actual, con más operaciones (alta, edición, borrado e importación).

En todas las operaciones, customer_id es opcional: se toma de tu token salvo que uses un token multicuenta.

list-clients: lista los clientes de tu cuenta

Es una operación de solo lectura. Devuelve la lista completa de clientes (pagina internamente hasta agotar la colección) en formato compacto, con filtros opcionales.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/list-clients?q=garcia&limit=20" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Lista mis clientes cuyo nombre o email contenga García».

Parámetros

Qué devuelve

Ejemplo real, recortado y con datos anonimizados:

{
  "success": true,
  "customer_id": "5a55fff67e9fe0036a541d15",
  "count": 5,
  "total": 12,
  "items": [
    {
      "_id": "69a6cbb1afbedf1dee60bd06",
      "name": "Laura",
      "surname": "Gómez",
      "email": "laura@example.com",
      "phone": "+34600000000",
      "dni": null,
      "lang": "es",
      "createdAt": "2026-03-03T11:53:21.052Z"
    },
    "..."
  ]
}

Consejos

• Un filtro sin coincidencias devuelve count: 0 y items: [], no un error.
• Para la ficha completa de un solo cliente es mejor get-client: aquí full:true trae la ficha completa de todos, más pesado.

get-client: ficha completa de un cliente

Es una operación de solo lectura. Resuelve un cliente por nombre o _id y devuelve el documento completo y fresco del servidor: es la forma de comprobar cómo quedó una ficha tras crearla o editarla.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-client?client=Laura%20G%C3%B3mez" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame la ficha del cliente Laura Gómez».

Parámetros

Qué devuelve

Ejemplo real, recortado y con datos anonimizados:

{
  "success": true,
  "_id": "60b09285dac98f1b2514856d",
  "resolved": { "id": "60b09285dac98f1b2514856d", "reason": "match por _id" },
  "item": {
    "_id": "60b09285dac98f1b2514856d",
    "name": "Laura",
    "surname": "Gómez",
    "email": "laura@example.com",
    "phone": "+34600000000",
    "country": "ES",
    "state": "M",
    "city": "Madrid",
    "street_address": "Calle Mayor 1",
    "zip": "28013",
    "tags": [],
    "check_marketing": false,
    "lang": "es",
    "createdAt": "2021-05-28T06:49:41.493Z"
  }
}

Errores propios

create-client: da de alta un cliente

Es una operación de escritura. Crea una ficha nueva con los datos básicos y, opcionalmente, el resto de la ficha completa (documento, dirección, notas, etiquetas). El script de esta guía fuerza siempre dry_run:true: no hay forma de crear un cliente de verdad con él.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-client \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Laura", "surname": "Gómez", "email": "laura@example.com", "phone": "+34 600 00 00 00", "profile": "contactable", "dry_run": true}'

Por MCP: «Da de alta un cliente nuevo: Laura Gómez, laura@example.com, 600 00 00 00».

Parámetros

Qué devuelve

Respuesta real de la prueba en seco, para un alta mínima con perfil operativo:

{
  "success": true,
  "dry_run": true,
  "resolved_profile": { "profile": "contactable", "requiresEmail": true, "reason": "match exacto 'contactable'" },
  "resolved_lang": { "lang": "es", "reason": "default (es)" },
  "payload_preview": {
    "name": "Laura",
    "surname": "Gómez",
    "email": "laura@example.com",
    "phone": "+34600000000",
    "origin": "manual",
    "lang": "es"
  },
  "warnings": []
}

Errores propios

Consejos

• Si vas a crear un cliente para que pueda reservar, usa profile: "contactable" y no olvides el email.
• Para altas con ficha completa (por ejemplo, migrando datos de otra herramienta), añade origin: "import".

update-client: edita una ficha existente

Es una operación de escritura. Cambia solo los campos que le pases; el resto de la ficha queda intacta. El script fuerza dry_run:true siempre.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-client \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": "laura@example.com", "tags": ["VIP", "buceador"], "customer_notes": "Cliente recurrente, prefiere mañanas.", "dry_run": true}'

Por MCP: «Añade la etiqueta VIP a Laura Gómez y anota que prefiere las mañanas».

Parámetros

Qué devuelve

Respuesta real de la prueba en seco:

{
  "success": true,
  "dry_run": true,
  "_id": "60b09285dac98f1b2514856d",
  "changes": {
    "customer_notes": "Cliente recurrente, prefiere mañanas.",
    "tags": ["VIP", "buceador"]
  },
  "note": "PUT parcial: solo estos campos cambian; customer/_id/__v nunca se envían."
}

Errores propios

Consejos

• Editar la ficha propaga los datos de contacto y dirección a las reservas ya hechas por ese cliente.
• Como tags reemplaza la lista entera, si solo quieres añadir una etiqueta consulta antes la ficha con get-client y envía el array completo.

delete-client: elimina un cliente

Es una operación de escritura e irreversible: el cliente se borra físicamente, no hay papelera ni operación de restaurar. Al borrarlo, el servidor anonimiza su nombre en sus reservas (queda como «*Ficha borrada», las reservas siguen existiendo) y borra sus documentos y formularios subidos. El script de esta guía fuerza siempre dry_run:true, así que ni con confirm:true llega a borrar nada de verdad.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/delete-client \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": "laura@example.com", "confirm": true}'

Por MCP: «Borra la ficha del cliente Laura Gómez» (el asistente te avisará del carácter irreversible antes de confirmar).

Parámetros

Qué devuelve

Prueba en seco real, con confirm: true:

{
  "success": true,
  "dry_run": true,
  "would_delete": { "_id": "60b09285dac98f1b2514856d", "name": "Laura Gómez" },
  "reversible": false,
  "cascade": {
    "orders": "el pax se ANONIMIZA en sus orders → nombre \"*Ficha borrada\" (las reservas siguen)",
    "s3": "sus uploads/forms en S3 (documentos subidos, fichas de checkin) se BORRAN"
  },
  "warnings": ["IRREVERSIBLE: el cliente se borra FÍSICAMENTE; el server anonimiza su pax en orders y borra sus uploads/forms en S3."]
}

Consejos

• El borrado no se puede deshacer. Si dudas, no borres: usa update-client para vaciar campos o quitar etiquetas.

import-clients: importación masiva de clientes

Es una operación de escritura, pensada para volcar de golpe clientes de otra herramienta (una hoja de cálculo, un CSV exportado). Necesita un token de administrador de la cuenta. La entrada son siempre filas en memoria (rows, un array de objetos): no se acepta una ruta de fichero del disco, ni por API ni por MCP. El proceso tiene siempre dos pasos: una prueba en seco que genera un informe y una «firma» (manifest_hash), y una ejecución posterior que repite exactamente lo firmado. El script de esta guía se queda siempre en el primer paso.

Cómo llamarla

Por API, primero la prueba en seco (sin confirm_hash):

curl -X POST https://api.bukyapp.com/v1/ops/import-clients \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [{"Nombre": "Laura Gómez", "Email": "laura@example.com", "Teléfono": "600000000"}],
    "mapping": {"fields": {
      "name": {"column": "Nombre", "transform": "split-name", "part": "name"},
      "surname": {"column": "Nombre", "transform": "split-name", "part": "surname"},
      "email": {"column": "Email", "transform": "lower"},
      "phone": {"column": "Teléfono", "transform": "phone"}
    }},
    "dry_run": true
  }'

Y luego, tras revisar el informe, la ejecución con el hash devuelto:

{ "rows": [ "..." ], "mapping": { "...": "..." }, "confirm_hash": "<manifest_hash del paso anterior>" }

Por MCP: «Importa estos clientes desde este fichero» adjuntando el CSV o Excel; el asistente lo lee, arma las filas y el mapeo, y te enseñará el informe antes de pedirte el visto bueno para ejecutar.

Parámetros

Qué devuelve

Prueba en seco real con tres filas ficticias, dos de ellas idénticas:

{
  "success": true,
  "dry_run": true,
  "manifest_hash": "f1032a09d934868eb80c0a4b15afa12f62dad30f70787912d4f8b9b03041ce57",
  "report": {
    "total_source": 3,
    "mapped": 3,
    "rejected_local": [],
    "intra_duplicates": 1,
    "db_existing": 12,
    "db_collisions": 0,
    "lang_distribution": { "(schema:es)": 3 },
    "sample_rows": [
      { "name": "Laura", "surname": "Gómez", "email": "laura@example.com", "phone": "600000000" },
      "..."
    ]
  },
  "next_step": "Firma este informe y ejecuta con confirm_hash='f1032a09d934868eb80c0a4b15afa12f62dad30f70787912d4f8b9b03041ce57'."
}

Errores propios

Consejos

• No encadenes la prueba en seco y la ejecución en el mismo mensaje: enseña el informe y espera el visto bueno antes de pasar confirm_hash.
• Si la ejecución responde hash_mismatch, no lo fuerces: repite la prueba en seco con las filas y el mapeo actuales y vuelve a pedir confirmación.
• Con más de 1000 filas, trocea el fichero en el cliente (asistente o script) y repite prueba en seco + ejecución por cada trozo; la deduplicación del servidor evita que se dupliquen las filas ya subidas.