API pública — Introducción y primeros pasos

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

Accede a los datos de tu cuenta de Buky desde herramientas externas mediante la API de solo lectura: autenticación por token, paginación y filtrado incluidos

La API pública de Buky te permite consultar los datos de tu cuenta (reservas, pagos, facturas, clientes) desde herramientas externas como Zapier, n8n, data warehouses, agentes de IA o dashboards propios. Devuelve los datos en formato JSON. Por defecto los tokens son de solo lectura; si al crear el token marcas Permitir escritura, también podrás crear y modificar registros, como lo haría un administrador.

Antes de empezar

• Necesitas un token de API activo. Si aún no tienes uno, consulta la guía Conectar Buky con herramientas externas (API Tokens).
• Tu token tiene el prefijo bk_ y solo se muestra una vez al crearlo. Guárdalo en un lugar seguro.

URL base

Todas las peticiones van contra:

https://app.bukyapp.com/api/

Autenticación

Incluye tu token en cada petición de una de estas dos formas:

Opción 1 — Header Authorization (recomendado):

curl https://app.bukyapp.com/api/orders \
  -H "Authorization: bk_tu_token_aqui"

Opción 2 — Query string:

curl "https://app.bukyapp.com/api/orders?token=bk_tu_token_aqui"

Si el token es inválido, está revocado o ha expirado, recibirás un error 401.

Limitaciones generales

Paginación

Las listas devuelven resultados paginados. Usa los parámetros limit y page:

curl "https://app.bukyapp.com/api/orders?limit=50&page=2" \
  -H "Authorization: bk_tu_token"

La respuesta incluye headers con la información de paginación:

Si no envías limit ni page, recibirás los primeros 100 resultados.

Filtrado

Puedes filtrar resultados con el parámetro filter. El formato es un objeto JSON con sintaxis estilo MongoDB, codificado como URL:

# Reservas con estado "confirmed"
curl "https://app.bukyapp.com/api/orders?filter=%7B%22status%22%3A%22confirmed%22%7D" \
  -H "Authorization: bk_tu_token"

El JSON sin codificar del ejemplo anterior es:

{"status": "confirmed"}

Operadores comunes que puedes usar dentro del filtro:

Selección de campos

Para recibir solo los campos que necesitas, usa el parámetro fields:

curl "https://app.bukyapp.com/api/orders?fields=%7B%22client%22%3A1%2C%22total%22%3A1%7D" \
  -H "Authorization: bk_tu_token"

JSON sin codificar: {"client": 1, "total": 1}

Usa 1 para incluir un campo o 0 para excluirlo.

Ordenación

Usa el parámetro sort con un objeto JSON:

# Ordenar por fecha de creación ascendente
curl "https://app.bukyapp.com/api/orders?sort=%7B%22createdAt%22%3A1%7D" \
  -H "Authorization: bk_tu_token"

• 1 = ascendente
• -1 = descendente

Por defecto, los resultados se ordenan por fecha de creación descendente ({"createdAt": -1}).

Expandir relaciones (populate)

Algunos campos son referencias a otros objetos (por ejemplo, el cliente de una reserva). Para obtener el objeto completo en vez de solo su ID, usa populate:

curl "https://app.bukyapp.com/api/orders?populate=client" \
  -H "Authorization: bk_tu_token"

Puedes expandir varios campos separándolos por comas: ?populate=client,products.

Ejemplo completo

Obtener las 20 reservas más recientes con estado "confirmed", mostrando solo cliente y total, expandiendo los datos del cliente:

curl "https://app.bukyapp.com/api/orders?limit=20&page=1&filter=%7B%22status%22%3A%22confirmed%22%7D&fields=%7B%22client%22%3A1%2C%22total%22%3A1%2C%22createdAt%22%3A1%7D&populate=client&sort=%7B%22createdAt%22%3A-1%7D" \
  -H "Authorization: bk_tu_token"

Recursos disponibles

Cada recurso acepta los mismos parámetros de filtrado, paginación, campos y ordenación descritos arriba.

Errores comunes

Preguntas frecuentes

¿Puedo crear o modificar reservas desde la API?

Sí, con un token de escritura. Los tokens se crean de solo lectura por defecto: para poder crear o modificar reservas, clientes o configuración, marca Permitir escritura al crear el token en Configuración > API Tokens. Hay acciones que ningún token puede hacer, tenga o no escritura: gestionar los usuarios del panel, hacer reembolsos, cambiar los métodos de pago o la suscripción de Buky y crear o revocar tokens. Consulta Conectar Buky con herramientas externas (API Tokens) para el detalle.

¿Cuántas peticiones puedo hacer?

No hay un límite estricto de rate-limiting, pero te recomendamos no superar las 60 peticiones por minuto para un uso razonable.

¿Los filtros son case-sensitive?

Sí. Si usas $regex, puedes añadir "$options": "i" para búsquedas sin distinguir mayúsculas: {"client.name": {"$regex": "garcía", "$options": "i"}}.

¿Cómo obtengo un token?

Desde el panel de Buky, ve a Configuración > API Tokens. Consulta la guía Conectar Buky con herramientas externas (API Tokens) para el paso a paso.