Centro de ayuda›Desarrolladores›API v1 — Introducción y primeros pasos

API v1 — Introducción y primeros pasos

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

Ejecuta las operaciones de Buky por HTTP desde api.bukyapp.com/v1 con tu token: descubrimiento, GET o POST, prueba en seco, errores y límites.

La API v1 de Buky expone las operaciones de tu cuenta por HTTP: consultar disponibilidad, precios y calendario, listar y editar actividades, alojamientos, packs, alquileres, clientes y reservas. Son exactamente las mismas operaciones que usa un asistente de IA conectado por MCP, con el mismo nombre y el mismo token, así que lo que hagas por API y lo que le pidas a tu asistente coinciden siempre.

Cada operación resuelve lo que le pides como lo haría el panel: por ejemplo, le das el nombre de una actividad y ella la busca en tu catálogo, aplica las reglas de reserva y te devuelve el resultado listo para usar.

Antes de empezar

Necesitas un token de API de tu cuenta, con el complemento API y MCP activo. Cómo crearlo, qué permiso darle y cómo revocarlo está en Conectar Buky con herramientas externas (API Tokens). Si lo que quieres es conectar Claude u otro asistente, ve a Conectar tu asistente de IA a Buky (MCP).

URL base y autenticación

https://api.bukyapp.com/v1

Envía el token en cada petición con la cabecera Authorization:

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

Un token de solo lectura solo puede ejecutar operaciones de consulta. Un token de escritura puede además ejecutar las de creación y edición. Ningún token puede gestionar usuarios del panel, reembolsos, métodos de pago ni otros tokens.

Descubrir las operaciones

El índice y el manual de cada operación son públicos: no necesitan token.

Petición	Qué devuelve
`GET /v1/ops`	Lista de operaciones con nombre, resumen, si es de solo lectura y sus parámetros obligatorios.
`GET /v1/ops/{operacion}/manual`	Manual completo: descripción, parámetros con su tipo y nivel (obligatorio, recomendado, opcional), ejemplos y campos de la respuesta.

curl https://api.bukyapp.com/v1/ops
curl https://api.bukyapp.com/v1/ops/get-calendar/manual

Ejecutar una operación

Los parámetros son los que describe el manual. Hay dos formas de enviarlos:

Con `POST` y un cuerpo JSON (vale para cualquier operación):

curl -X POST https://api.bukyapp.com/v1/ops/get-calendar \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activity": "Surf Principiante", "from": "2026-10-01", "to": "2026-10-31", "pax": 2}'

Con `GET` y los parámetros en la URL (solo operaciones de consulta):

curl "https://api.bukyapp.com/v1/ops/get-calendar?activity=Surf%20Principiante&from=2026-10-01&to=2026-10-31&pax=2" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Si envías con GET una operación de escritura, la API responde 405 y te pide usar POST.

Prueba en seco. Las operaciones de escritura aceptan "dry_run": true en el cuerpo: la operación se prepara y se valida por completo, pero no guarda nada. Úsalo para comprobar parámetros antes de crear o modificar de verdad.

Cómo es la respuesta

Toda ejecución devuelve un JSON con estos campos comunes, además de los propios de cada operación:

Campo	Significado
`success`	`true` si la operación terminó bien.
`operation`	Nombre de la operación ejecutada.
`customer_id`	Cuenta sobre la que se ejecutó (la de tu token).
`dry_run`	Si fue una prueba en seco.
`duration_ms`	Tiempo de ejecución.
`warnings`	Avisos no bloqueantes, por ejemplo un parámetro desconocido que se ha ignorado.
`*_candidates`	Solo cuando el nombre que diste no se resuelve a un único producto: la lista de coincidencias (por ejemplo `activity_candidates`) para que elijas. La operación no adivina.

Cuando indicas un producto por nombre, la respuesta incluye cómo se resolvió (resolved_activity, resolved_accommodation, etc.) con el identificador elegido y el motivo, para que puedas comprobarlo.

Toda respuesta lleva la cabecera X-Catalog-Version, un identificador de la versión del catálogo de operaciones. Si cambia, conviene volver a leer el manual de las operaciones que uses.

Errores

Código	`error`	Significado
`400`	`invalid_params`	Falta un parámetro obligatorio o tiene un valor no válido. El campo `details` dice cuál.
`401`	`unauthorized` o `auth_failed`	Sin token, token mal formado, revocado, caducado o de una cuenta sin el complemento activo.
`403`	`read_only_token`	Operación de escritura con un token de solo lectura.
`404`	`unknown_operation`	La operación no existe. Consulta `GET /v1/ops`.
`405`	`method_not_allowed`	Operación de escritura enviada con `GET`.
`429`	`rate_limited`	Demasiadas peticiones. Espera un minuto.
`200` con `success: false`	según la operación	La petición era válida pero la operación no pudo completarse. El propio JSON explica por qué.

Límites

Peticiones por minuto: hasta 120 por token y hasta 120 por dirección IP.
Operaciones de varios pasos: algunas operaciones hacen varias llamadas internas (por ejemplo, crear una actividad con sus tarifas). Si una falla a medias, no se deshace lo ya hecho: la respuesta describe hasta dónde llegó y qué identificadores se crearon.
Reservar no es una operación. Las operaciones de disponibilidad devuelven enlaces al motor de reservas con la fecha y las personas rellenas.

Buenas prácticas

Un token por integración, de solo lectura salvo que necesites escribir.
Lee el manual de la operación antes de usarla: los parámetros recomendados cambian el resultado (por ejemplo, pax decide qué días son reservables).
Usa `dry_run` en las escrituras mientras desarrollas.
Identifica tu integración con la cabecera opcional X-Agent: nombre-de-tu-integracion. Ayuda a diagnosticar problemas.

Preguntas frecuentes

¿Qué diferencia hay con la API anterior?

La API anterior expone directamente los recursos internos de Buky (/api/orders, /api/payments, etc.) con sus filtros de base de datos. Sigue funcionando con los mismos tokens, pero es menos cómoda y no se amplía. Está documentada en API pública — Introducción y primeros pasos. Para integraciones nuevas, usa la v1.

¿Puedo usar la v1 desde Zapier, n8n o Make?

Sí, con cualquier módulo de petición HTTP: URL de la operación, cabecera Authorization y cuerpo JSON.

¿Las operaciones cambian con el tiempo?

Pueden añadirse operaciones y parámetros nuevos en cualquier momento. Renombrar o quitar un parámetro se evita expresamente. En esta fase no hay un contrato congelado: la cabecera X-Catalog-Version te dice cuándo ha cambiado el catálogo, y en ese caso conviene releer el manual de las operaciones que uses.