Operaciones de reservas

Juan José Vélez Medina · Equipo Bukyapp· 3 min de lectura·Actualizado 17 sept 2026

Lista y consulta las reservas de tu cuenta con sus productos, participantes y pagos por API v1 o MCP.

Una reserva (order) es lo que queda registrado cuando alguien compra en tu motor de reservas o cuando das de alta una venta desde el panel: comprador, participantes, lo reservado (actividades, alojamientos, packs, alquileres o tienda), pagos y estado. list-orders y get-order sirven para consultar esas reservas ya hechas, no para crearlas.

Reservar no es una operación de esta página: no hay create-order. El motor de reservas es quien crea las reservas cuando el cliente completa la compra. Si lo que necesitas es comprobar qué días y con cuántas plazas se puede reservar un producto (el paso previo, con el enlace al motor de reservas ya incluido), esas son las operaciones de Operaciones de disponibilidad, calendario y precios.

Si vienes de la API pública anterior de Buky, la consulta de reservas con filtros de base de datos (paginación, rango de fechas, estado) está documentada aparte en API pública — Reservas (orders). Esta página cubre la v1 nueva.

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-orders: lista reservas con filtros y totales

Es una operación de solo lectura: vale con cualquier token. Devuelve las reservas que cumplen los filtros, en vista compacta, más un desglose de importes por estado y origen.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/list-orders?from=2026-01-01T00:00:00.000Z&to=2026-09-15T23:59:59.999Z&pending_payment=true&limit=20" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame las reservas con pago pendiente de este año» o «Reservas del 1 de enero al 15 de septiembre con pago pendiente».

Parámetros

Qué devuelve

Ejemplo real, recortado, de las últimas reservas:

{
  "success": true,
  "operation": "list-orders",
  "count": 5,
  "total": 32,
  "breakdown": {
    "by_status": {
      "active": { "count": 16, "total_cents": 65800, "pending_cents": 58400 },
      "cancelled": { "count": 16, "total_cents": 229800, "pending_cents": 221000 }
    },
    "by_origin": {
      "manual": { "count": 10, "total_cents": 59200, "pending_cents": 58000 },
      "booking": { "count": 12, "total_cents": 16400, "pending_cents": 1400 },
      "channel": { "count": 10, "total_cents": 220000, "pending_cents": 220000 }
    },
    "total_cents": 295600,
    "pending_cents": 279400
  },
  "items": [
    { "_id": "69a6cbb0afbedf1dee60bce3", "name": "Laura Gómez", "total": 1000, "amount_pending": 0, "status": "active", "origin": "booking", "createdAt": "2026-03-03T11:53:20.971Z", "start": "2026-03-24T11:00:00.000Z", "end": "2026-03-24T12:00:00.000Z", "bookings_count": 1 },
    { "_id": "69a6c304c076529dd7891487", "name": "Marcos Ibáñez", "total": 10000, "amount_pending": 10000, "status": "active", "origin": "manual", "createdAt": "2026-03-03T11:16:20.952Z", "start": null, "end": null, "bookings_count": 0 },
    "…"
  ],
  "warnings": []
}

Errores propios de esta operación

Consejos

• from/to filtran por cuándo se compró; booked_from/booked_to filtran por cuándo se disfruta. No son intercambiables: para «reservas de mañana» usa booked_from/booked_to.
• Pide full:true solo si necesitas los pagos o los participantes de varias reservas a la vez; para una sola, get-order es más ligero y siempre trae el documento fresco.

get-order: detalle completo de una reserva

Es una operación de solo lectura: vale con cualquier token. Devuelve el documento completo y actualizado de una reserva a partir de su identificador, que sale de list-orders.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-order?order=69a6cbb0afbedf1dee60bce3" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Dame el detalle de la reserva 69a6cbb0afbedf1dee60bce3» (normalmente después de pedir una lista y elegir una).

Parámetros

Qué devuelve

Ejemplo real, recortado, de una reserva de una actividad:

{
  "success": true,
  "operation": "get-order",
  "_id": "69a6cbb0afbedf1dee60bce3",
  "resolved": { "id": "69a6cbb0afbedf1dee60bce3", "reason": "lookup directo por _id" },
  "item": {
    "_id": "69a6cbb0afbedf1dee60bce3",
    "status": "active",
    "origin": "booking",
    "name": "Laura Gómez",
    "surname": "Ruiz",
    "email": "laura@example.com",
    "phone": "600 000 000",
    "total": 1000,
    "amountToPay": 1000,
    "amountPending": 0,
    "createdAt": "2026-03-03T11:53:20.971Z",
    "start": "2026-03-24T11:00:00.000Z",
    "end": "2026-03-24T12:00:00.000Z",
    "buyer": "69a6cbb1afbedf1dee60bd06",
    "products": [
      {
        "product_id": "64245a449362b0005fbd7119",
        "product_type": "activity",
        "product_title": { "es": "Actividad con personal estricto" },
        "total": 1000,
        "pax": [ { "name": "Laura Gómez", "surname": "Ruiz" } ],
        "bookings": ["69a6cbb1afbedf1dee60bcf7"]
      }
    ],
    "payments": [
      { "mode": "redsys", "status": "completed", "total": 1000, "date": "2026-03-03T11:54:40.247Z" }
    ]
  },
  "warnings": []
}

Errores propios de esta operación

Consejos

• Usa siempre get-order para confirmar «cómo quedó» una reserva después de un pago o un cambio: list-orders es la vista compacta, esta es la fresca y completa.
• El identificador no se adivina por nombre de cliente: primero list-orders (con q o client) para localizarla, luego get-order con su _id.