API pública — Reservas (orders)

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

Consulta las reservas de tu cuenta vía la API pública de Buky, con filtros por fecha, estado y paginación incluida

Esta página explica cómo consultar las reservas de tu cuenta mediante la API pública de Buky. Es el recurso más consultado: aquí están las compras de tus clientes, con sus productos, pagos, fechas y estado.

Antes de empezar

• Necesitas un API Token activo. Si aún no lo has creado, sigue la guía Conectar Buky con herramientas externas (API Tokens).
• El token es de solo lectura: puedes listar y consultar reservas, pero no modificarlas ni crearlas.
• La función está en fase beta. Si no ves la pestaña "API Tokens" en tu configuración, contacta con soporte.

Autenticación

El token se envía en cada petición de una de estas dos formas:

Opción 1 — Cabecera `auth` (recomendado):

curl "https://app.bukyapp.com/api/orders" \
  -H "auth: bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Opción 2 — Parámetro `token` en la URL:

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

Usa la cabecera siempre que puedas — las URLs suelen quedarse en logs y expuestas.

Listar reservas

curl "https://app.bukyapp.com/api/orders" \
  -H "auth: bk_TU_TOKEN"

La respuesta es un array JSON de reservas, ordenado por fecha de creación descendente por defecto (la más reciente primero):

[
  {
    "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Laura",
    "surname": "García",
    "email": "laura@example.com",
    "phone": "+34 600 123 456",
    "status": "active",
    "paymentPending": false,
    "total": 180,
    "amountPending": 0,
    "start": "2026-05-14T09:00:00.000Z",
    "end": "2026-05-14T12:00:00.000Z",
    "createdAt": "2026-04-18T15:32:10.000Z",
    "products": [ ... ],
    "bookings": ["65f1a2b3c4d5e6f7a8b9c0d2"],
    "customer": "5f0e1d2c3b4a5968778695a4"
  },
  ...
]

Paginación

En las cabeceras de la respuesta recibes el total de resultados y el número de páginas:

• X-Count: total de reservas que coinciden con el filtro.
• X-Page-Count: número de páginas.

Por defecto el endpoint devuelve como máximo 100 reservas por página. Para paginar:

curl "https://app.bukyapp.com/api/orders?page=1&limit=50" \
  -H "auth: bk_TU_TOKEN"

• limit: reservas por página (máximo 100).
• page: número de página, empezando en 1.

Filtrar reservas

El parámetro filter acepta un objeto JSON con sintaxis MongoDB. Envíalo codificado en la URL.

Por fecha de creación (reservas del último mes)

curl -G "https://app.bukyapp.com/api/orders" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'filter={"createdAt":{"$gte":"2026-03-20T00:00:00Z"}}'

Por estado

# Solo reservas activas (confirmadas)
--data-urlencode 'filter={"status":"active"}'

# Solo pendientes de pago
--data-urlencode 'filter={"paymentPending":true}'

# Canceladas en abril
--data-urlencode 'filter={"status":"cancelled","cancelledAt":{"$gte":"2026-04-01","$lt":"2026-05-01"}}'

Por cliente

# Todas las reservas de un email concreto
--data-urlencode 'filter={"email":"laura@example.com"}'

# Por ID de ficha de cliente (customerClient)
--data-urlencode 'filter={"pax.customerClient":"65f1a2b3c4d5e6f7a8b9c0d1"}'

Por fechas de la reserva (inicio / fin de la actividad)

# Reservas cuya actividad empieza entre dos fechas
--data-urlencode 'filter={"start":{"$gte":"2026-05-01","$lt":"2026-06-01"}}'

Combinando filtros

Cualquier combinación funciona — se aplica como AND:

--data-urlencode 'filter={"status":"active","paymentPending":true,"start":{"$gte":"2026-05-01"}}'

Ordenar los resultados

Con sort, también en formato JSON:

# Más antiguas primero
--data-urlencode 'sort={"createdAt":1}'

# Por fecha de inicio de la actividad
--data-urlencode 'sort={"start":1}'

1 = ascendente, -1 = descendente.

Traer solo los campos que necesites

Con fields reduces el tamaño de la respuesta pidiendo solo las columnas que usas:

--data-urlencode 'fields={"name":1,"surname":1,"email":1,"total":1,"status":1,"createdAt":1}'

Útil cuando vas a procesar miles de reservas y solo necesitas un resumen.

Expandir relaciones (populate)

Las referencias a otros recursos (bookings, customerClient, partner…) vienen como IDs. Para obtener el objeto completo en la misma respuesta:

curl -G "https://app.bukyapp.com/api/orders" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'populate=bookings,coupon,partner'

Separa varios campos con comas. Úsalo con moderación: expandir todo en consultas grandes puede hacer la respuesta muy pesada.

Consultar una reserva concreta

curl "https://app.bukyapp.com/api/orders/65f1a2b3c4d5e6f7a8b9c0d1" \
  -H "auth: bk_TU_TOKEN"

Este endpoint devuelve la reserva con sus bookings ya expandidos (incluye sesiones, recursos, pax detallados).

Campos útiles del objeto Order

Un Order tiene muchos más campos (checkin online, seguimiento de emails, etiquetas…). Usa fields para traer solo los que necesites y populate para expandir las relaciones cuando te haga falta.

Consejos

• Empieza siempre filtrando por fecha. Sin filter obtienes reservas ordenadas por creación, pero paginarás mucho. Un createdAt: {$gte: ...} reduce resultados y acelera la respuesta.
• Guarda el último `createdAt` procesado. Para sincronizaciones incrementales, pide solo reservas posteriores al último timestamp que ya procesaste.
• No expandas lo que no vayas a usar. Cada populate añade joins. Si solo necesitas el email del cliente, pídelo en fields en lugar de expandir el cliente completo.
• Respeta el ritmo. Paginaciones agresivas o llamadas en bucle sin pausa pueden saturar. Usa limit=100 y espacia las peticiones.

Preguntas frecuentes

¿Puedo crear reservas por la API?

No. Los API Tokens son de solo lectura. Sirven para consultar datos, no para modificarlos.

¿Hay límite de peticiones?

Hay topes sensatos para evitar abuso. Si haces integraciones pesadas (sincronización masiva a un data warehouse, por ejemplo), contacta con soporte para acordar límites.

¿La API es estable? ¿Puede cambiar sin aviso?

La estructura de los objetos que devuelve la API está ligada al modelo interno de Buky. Hacemos lo posible por no romper integraciones existentes, pero los campos marcados como beta o internos pueden cambiar. Los listados en la tabla "Campos útiles" son estables.

No veo la pestaña API Tokens en mi configuración.

La función está en fase beta y se activa progresivamente. Contacta con soporte de Buky para solicitar acceso.