Listar citas

GET

https://app.recurrente.com/api/bookings

GET

/api/bookings

curl https://app.recurrente.com/api/bookings \
     -H "X-SECRET-KEY: <apiKey>" \
     -H "Content-Type: application/json"

[
  {
    "id": "bk_9f8e7d6c",
    "account_id": "ac_4b3a2c1d",
    "status": "pending",
    "source": "storefront",
    "starts_at": "2024-05-10T14:00:00Z",
    "ends_at": "2024-05-10T14:30:00Z",
    "customer": {
      "id": "cus_7a6b5c4d",
      "name": "Ana Gómez",
      "email": "ana.gomez@example.com",
      "phone": "+502 5555 1234"
    },
    "segments": [
      {
        "service_id": "svc_1234abcd",
        "product_id": "prd_5678efgh",
        "product_variant_id": "var_90ab12cd",
        "staff_member_id": "stf_3456efgh",
        "resource_id": "res_7890ijkl",
        "kind": "service",
        "starts_at": "2024-05-10T14:00:00Z",
        "ends_at": "2024-05-10T14:30:00Z"
      }
    ],
    "staff_member_id": "stf_3456efgh",
    "resource_id": "res_7890ijkl",
    "class_session_id": null,
    "stay": {
      "room_type_id": "svc_ab12cd34",
      "unit_id": "res_ab12cd34",
      "unit_name": "Cabaña 1",
      "check_in_on": "2026-10-09",
      "check_out_on": "2026-10-11",
      "nights": 2,
      "guests": 2,
      "service_tab_id": "tab_1234abcd",
      "registered_guests": [
        {
          "name": "Lucía Pérez",
          "document": "DPI 1234 56789 0101",
          "nationality": "Guatemalteca"
        }
      ],
      "guests_registered_at": "2024-05-10T14:00:00Z"
    },
    "payment_policy": "deposit",
    "currency": "GTQ",
    "total_in_cents": 20000,
    "paid_in_cents": 10000,
    "balance_in_cents": 10000,
    "balance_paid_outside_at": "2024-05-05T10:00:00Z",
    "checkout_id": "chk_5678efgh",
    "checkout_url": "https://app.recurrente.com/payments/checkout/chk_5678efgh",
    "balance_checkout_id": "chk_90ab12cd",
    "balance_checkout_url": "https://app.recurrente.com/payments/checkout/chk_90ab12cd",
    "no_show_fee_checkout_id": "chk_3456ijkl",
    "booking_series_id": "ser_7890mnop",
    "access_url": "https://app.recurrente.com/bookings/access/bk_9f8e7d6c?token=abc123",
    "customer_note": "Prefiere ventana cerca",
    "merchant_note": "Confirmar llegada 10 minutos antes",
    "accepted_at": "2024-05-01T08:00:00Z",
    "hold_expires_at": "2024-05-03T08:00:00Z",
    "cancelled_by": null,
    "cancellation_reason": null,
    "rescheduled_from_id": null,
    "metadata": {
      "promo_code": "MAYO2024",
      "internal_ref": "INT-20240510-001"
    },
    "created_at": "2024-04-25T12:00:00Z"
  }
]

Lista las citas en orden de hora. Filtra por estado, rango de inicio, profesional, cliente o sesión de clase. Con una llave de organización y sin X-ACCOUNT-ID, lista las de todas las cuentas de la organización.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Query parameters

statusenumOptional

fromdatetimeOptional

Citas que empiezan desde este momento (ISO 8601)

todatetimeOptional

Citas que empiezan hasta este momento (ISO 8601)

staff_member_idstringOptional

customer_idstringOptional

class_session_idstringOptional

qstringOptional

Busca por nombre, correo o teléfono del cliente (“Ana”, “5555 1234”).

kindenumOptional

appointment (citas), class_seat (lugares en clases) o stay (estadías de alojamiento).

Allowed values:

pageintegerOptionalDefaults to 1

per_pageintegerOptionalDefaults to 25

Response

Lista de citas

idstringOptional

account_idstringOptional

Cuenta (sucursal) de la cita.

statusenumOptional

pending mientras el cliente paga o el negocio decide; confirmed cuando la hora es del cliente.

sourceenumOptional

Por dónde entró la reserva.

starts_atdatetimeOptional

ends_atdatetimeOptional

customerobjectOptional

segmentslist of objectsOptional

Los tramos de la cita, uno por servicio (dos si el servicio tiene tiempo de proceso). Vacío en un lugar de una clase.

staff_member_idstring or nullOptional

resource_idstring or nullOptional

class_session_idstring or nullOptional

La sesión, si la cita es un lugar en una clase.

stayobject or nullOptional

Las noches en una habitación, si la reserva es una estadía de alojamiento.

payment_policyenumOptional

Allowed values:

currencystringOptional

total_in_centsintegerOptional

Lo que cuesta la cita.

paid_in_centsintegerOptional

Lo que el cliente ya pagó (anticipo, total o protección).

balance_in_centsintegerOptional

Lo que falta cobrar el día de la cita. 0 en una sesión de paquete o un saldo cobrado afuera.

balance_paid_outside_atdatetime or nullOptional

Cuándo el negocio marcó el saldo como cobrado fuera de Recurrente.

checkout_idstring or nullOptional

checkout_urlstring or nullOptional

Donde el cliente paga lo que la política pide, o deja su tarjeta.

balance_checkout_idstring or nullOptional

balance_checkout_urlstring or nullOptional

El link del saldo, después de POST /bookings/{booking_id}/balance_charge.

no_show_fee_checkout_idstring or nullOptional

El checkout del cargo por inasistencia, cobrado o rechazado.

booking_series_idstring or nullOptional

La serie que la reservó, si se repite.

access_urlstringOptional

La página del cliente para ver, pagar o cancelar su cita (link firmado).

customer_notestring or nullOptional

merchant_notestring or nullOptional

accepted_atdatetime or nullOptional

hold_expires_atdatetime or nullOptional

Hasta cuándo se aparta la hora si nadie paga.

cancelled_byenum or nullOptional

Allowed values:

cancellation_reasonstring or nullOptional

rescheduled_from_idstring or nullOptional

La cita que esta reemplazó al moverse de hora.

metadataobjectOptional

created_atdatetimeOptional

Errors

403

Forbidden Error