Operaciones de formularios

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

Consulta, crea, edita y borra los formularios de campos extra de reserva y check-in por API v1 o MCP.

Los formularios son los campos extra que Buky le pide a tu cliente al reservar o durante el check-in online: nombre, nivel, alergias, si acepta unas condiciones… Un mismo formulario puede ir suelto, ser un paso del check-in online o mostrarse como contexto de cada sesión (ver Crear formularios personalizados). Estas operaciones enumeran, crean, leen, editan, borran y recuperan el formulario en sí; no gestionan lo que responde cada 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.

list-forms: enumera los formularios del centro

Devuelve los formularios del centro: identificador, título, si son un paso del check-in online o del contexto de sesión, y cuántos campos tienen. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

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

Por MCP: «¿Qué formularios tengo creados?».

Parámetros

Qué devuelve

Ejemplo real de la cuenta demo:

{
  "success": true,
  "detail": "compact",
  "count": 1,
  "total": 1,
  "items": [
    {
      "_id": "67e57cb572327d54c19cd904",
      "title": "Checkin Surf",
      "checkin_online": true,
      "session_context": false,
      "components_count": 3
    }
  ]
}

Consejos

Usa detail: descriptive cuando quieras revisar un formulario sin pedir el documento completo: te da los productos afectados por su título (no solo el identificador) y el detalle de los campos.

get-form: consulta un formulario completo

Devuelve el documento completo y actualizado de un formulario: título, descripción, campos y configuración de rol. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-form?form=Checkin%20Surf" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame el formulario de check-in de surf».

Parámetros

\* El manual lo marca como «recomendado», pero en la práctica es obligatorio: sin él, la operación responde con error: "form_intent_required".

Qué devuelve

Ejemplo real, recortado, del formulario «Checkin Surf» de la cuenta demo:

{
  "success": true,
  "_id": "67e57cb572327d54c19cd904",
  "resolved": { "id": "67e57cb572327d54c19cd904", "reason": "match exacto 'Checkin Surf'" },
  "item": {
    "_id": "67e57cb572327d54c19cd904",
    "title": { "es": "Checkin Surf", "en": "Surf Checkin" },
    "checkin_online": true,
    "checkin_online_mode": "always",
    "checkin_online_needDocument": false,
    "checkin_online_needSign": false,
    "session_context": false,
    "components": [
      { "label": { "es": "Nombre completo" }, "type": "text", "required": true },
      { "label": { "es": "Nivel de surf" }, "type": "select", "required": true,
        "options": [{ "label": { "es": "Principiante" } }, "..."] },
      "..."
    ]
  }
}

Errores propios de esta operación

Consejos

Usa get-form después de create-form o update-form para comprobar cómo quedó de verdad el formulario: la operación de escritura confirma los cambios enviados, pero get-form te da el documento completo y fresco.

create-form: crea un formulario o paso de check-in

Crea un formulario nuevo: suelto, como paso del check-in online o como contexto de sesión. Es una operación de escritura: solo un token con permiso de escritura puede ejecutarla, y aquí siempre en modo de prueba (dry_run: true).

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-form \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Checkin buceo",
    "role": "checkin_online",
    "need_document": true,
    "components": ["Número de documento"],
    "dry_run": true
  }'

Por MCP: «Crea un formulario de check-in que pida el número de documento y una foto del DNI».

Parámetros

\* Obligatorio si resource_mode es someProducts o exceptSomeProducts; sin él la operación no crea nada.

Qué devuelve

Prueba en seco real, con rol checkin_online:

{
  "success": true,
  "dry_run": true,
  "applied_defaults": { "role": "checkin_online", "resource_mode": "always" },
  "resolved_role": { "role": "checkin_online", "checkinOnline": true, "sessionContext": false },
  "resolved_resources": [],
  "payload_preview": {
    "title": { "es": "Checkin prueba Kraken", "en": "New", "..." : "..." },
    "components": [
      { "label": { "es": "<p>Nivel de surf</p>" }, "type": "select",
        "options": [{ "label": { "es": "<p>Principiante</p>" } }, "..."] }
    ],
    "checkin_online": true,
    "checkin_online_needDocument": true,
    "checkin_online_needSign": true
  }
}

Al crearlo de verdad (fuera de la prueba en seco), la respuesta trae además el _id del formulario nuevo.

Errores propios de esta operación

Consejos

Un campo (component) puede ser solo un texto ("Nombre completo") para un campo de texto corto, o un objeto si necesitas otro tipo: inputSmall, inputBig, select, checkbox, date, file, title o paragraph. Los select necesitan options (al menos una).

update-form: edita título, descripción o rol

Edita un formulario existente: título, descripción o rol. No toca los campos (components); para eso hay que crear el formulario de nuevo. Es una operación de escritura, siempre en modo de prueba aquí.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-form \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"form": "Checkin Surf", "title": "Checkin Surf (temporada 2026)", "dry_run": true}'

Por MCP: «Cambia el título del formulario Checkin Surf a "Checkin Surf (temporada 2026)"».

Parámetros

\* Obligatorio si resource_mode es someProducts o exceptSomeProducts.

Qué devuelve

Prueba en seco real, cambiando el título:

{
  "success": true,
  "dry_run": true,
  "_id": "67e57cb572327d54c19cd904",
  "changes": { "title": { "es": "Checkin Surf (prueba Kraken)" } },
  "note": "PUT parcial: solo estos campos cambian; customer/_id/__v nunca se envían. components NO se toca."
}

Errores propios de esta operación

Consejos

Los campos (components) no se editan con esta operación: para añadir, quitar o reordenar preguntas, crea el formulario de nuevo con create-form y borra el anterior con delete-form.

delete-form: borra un formulario

El formulario 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 recuperarlo si lo necesitas. Es una operación de escritura, siempre en modo de prueba aquí.

Cómo llamarla

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

Por MCP: «Borra el formulario Checkin Surf» (el asistente te pedirá confirmar antes de ejecutarlo de verdad).

Parámetros

Qué devuelve

Prueba en seco real:

{
  "success": true,
  "dry_run": true,
  "would_delete": { "_id": "67e57cb572327d54c19cd904", "name": "Checkin Surf" },
  "soft_deleted": false,
  "reversible": true,
  "warnings": ["borrado limpio (sin cascada): posibles referencias colgando a este formulario son menores"]
}

Errores propios de esta operación

Consejos

Si te equivocas, el soporte de Buky puede recuperarlo.