Operaciones de personal

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

Consulta, crea, edita y borra instructores y monitores de tu equipo por API v1 o MCP.

El personal son los instructores y monitores de tu equipo: los das de alta en Buky para asignarlos a actividades y sesiones, controlar su disponibilidad y consultar sus horas trabajadas. Más contexto en Gestionar el personal (instructores y monitores). El personal se asigna desde la ficha de cada actividad: ver Operaciones de actividades.

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-staff: lista el personal del equipo

Devuelve el personal dado de alta: identificador, nombre y si está activo o desactivado. Es la forma de ver quién existe sin tener que adivinar un nombre en get-staff. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

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

curl -X POST https://api.bukyapp.com/v1/ops/list-staff \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"disabled": false}'

Por MCP: «Enséñame el personal que tengo dado de alta».

Parámetros

Qué devuelve

Ejemplo real, vista compacta (nombre sustituido por uno ficticio):

{
  "success": true,
  "detail": "compact",
  "count": 1,
  "total": 1,
  "items": [
    { "_id": "602a2edd48bcd3005f403474", "name": "Laura Gómez", "internalName": null, "is_disabled": false }
  ],
  "warnings": []
}

get-staff: consulta la ficha completa de un miembro del personal

Devuelve el documento completo y actualizado de un instructor o monitor, resuelto por nombre o identificador. Es la forma de comprobar cómo quedó tras crearlo o editarlo. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

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

curl -X POST https://api.bukyapp.com/v1/ops/get-staff \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"staff": "Laura Gómez"}'

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

Parámetros

Qué devuelve

Ejemplo real, recortado (nombre sustituido por uno ficticio):

{
  "success": true,
  "_id": "602a2edd48bcd3005f403474",
  "resolved": { "id": "602a2edd48bcd3005f403474", "reason": "match exacto 'Laura Gómez'" },
  "item": {
    "_id": "602a2edd48bcd3005f403474",
    "name": "Laura Gómez",
    "type": "Staff",
    "activities_staff_available": [],
    "categories": [],
    "extras": [],
    "gallery": [],
    "createdAt": "2021-02-15T08:20:45.902Z"
  },
  "warnings": []
}

Errores propios

create-staff: da de alta un instructor o monitor

Crea un nuevo miembro del personal con un mínimo de datos; el resto se completa después con update-staff. Es una operación de escritura: en esta documentación siempre se ejecuta en modo prueba (dry_run).

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-staff \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Laura Gómez", "staff_email": "laura@example.com", "langs": ["es", "en"], "dry_run": true}'

Por MCP: «Da de alta a Laura Gómez como monitora, con email laura@example.com e idiomas español e inglés». El asistente te enseña la prueba en seco antes de crear de verdad.

Parámetros

Qué devuelve

Prueba en seco real, con una foto de perfil por URL:

{
  "success": true,
  "dry_run": true,
  "resolved_categories": [],
  "resolved_extras": [],
  "payload_preview": {
    "name": "Laura Gómez",
    "description": {},
    "type": "Staff",
    "staff_email": "laura@example.com",
    "langs": ["es", "en"]
  },
  "images_pending": ["https://example.com/laura.jpg"],
  "images_missing": []
}

Errores propios

Consejos

• Con solo name basta para crear el registro; añade staff_email y langs cuando los tengas.

update-staff: edita nombre, email o idiomas

Cambia solo los campos que le pasas; el resto de la ficha queda igual. Es una operación de escritura: en esta documentación siempre se ejecuta en modo prueba.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-staff \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"staff": "Laura Gómez", "staff_email": "laura@example.com", "langs": ["es", "en", "de"], "dry_run": true}'

Por MCP: «Añade alemán a los idiomas de Laura Gómez».

Parámetros

Tienes que aportar al menos uno de name, staff_email o langs: si no cambias nada, la operación falla.

Qué devuelve

{
  "success": true,
  "_id": "602a2edd48bcd3005f403474",
  "changes": { "langs": ["es", "en", "de"] },
  "note": "PUT parcial: solo estos campos cambian; customer/_id/__v nunca se envían."
}

Errores propios

delete-staff: da de baja a un miembro del personal

La persona deja de verse en el panel y se retira automáticamente de las actividades donde estaba asignada. 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: en esta documentación siempre se ejecuta en modo prueba.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/delete-staff \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"staff": "Laura Gómez", "confirm": true, "dry_run": true}'

Por MCP: «Da de baja a Laura Gómez del equipo» (el asistente te pedirá confirmación antes de marcar confirm: true).

Parámetros

Qué devuelve

Prueba en seco real, con confirm: true:

{
  "success": true,
  "dry_run": true,
  "would_delete": { "_id": "602a2edd48bcd3005f403474", "name": "Laura Gómez" },
  "soft_deleted": false,
  "reversible": true,
  "warnings": []
}

Errores propios

Consejos

• Al dar de baja a alguien, Buky la quita automáticamente de las actividades donde estaba asignada.