Reservar citas que se repiten

POST

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

POST

/api/booking_series

curl -X POST https://app.recurrente.com/api/booking_series \
     -H "X-SECRET-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "service_id": "svc_9f8e7d6c",
  "starts_at": "2026-10-07T10:00:00-06:00",
  "frequency": "week"
}'

{
  "id": "ser_4a3b2c1d",
  "frequency": "week",
  "interval": 2,
  "occurrences": 10,
  "ends_on": "2026-12-16",
  "bookings": [
    {
      "id": "bk_7e6f5d4c",
      "account_id": "ac_1234abcd",
      "status": "confirmed",
      "source": "api",
      "starts_at": "2026-10-07T10:00:00-06:00",
      "ends_at": "2026-10-07T11:00:00-06:00",
      "customer": {
        "id": "cus_5678efgh",
        "name": "María González",
        "email": "maria.gonzalez@example.com",
        "phone": "+502 5555 1234"
      },
      "segments": [
        {
          "service_id": "svc_9f8e7d6c",
          "product_id": "prd_1a2b3c4d",
          "product_variant_id": "var_5e6f7g8h",
          "staff_member_id": "stf_11223344",
          "resource_id": "res_99887766",
          "kind": "service",
          "starts_at": "2026-10-07T10:00:00-06:00",
          "ends_at": "2026-10-07T11:00:00-06:00"
        }
      ],
      "staff_member_id": "stf_11223344",
      "resource_id": "res_99887766",
      "class_session_id": "cls_55667788",
      "stay": {
        "room_type_id": "svc_9f8e7d6c",
        "unit_id": "res_33445566",
        "unit_name": "Suite 101",
        "check_in_on": "2026-10-07",
        "check_out_on": "2026-10-09",
        "nights": 2,
        "guests": 1,
        "service_tab_id": "tab_77889900",
        "registered_guests": [
          {
            "name": "María González",
            "document": "DPI 1234 56789 0123",
            "nationality": "Guatemalteca"
          }
        ],
        "guests_registered_at": "2026-10-07T09:45:00-06:00"
      },
      "payment_policy": "none",
      "currency": "GTQ",
      "total_in_cents": 15000,
      "paid_in_cents": 0,
      "balance_in_cents": 15000,
      "balance_paid_outside_at": "2026-10-07T09:50:00-06:00",
      "checkout_id": "chk_abcdef12",
      "checkout_url": "https://app.recurrente.com/payments/checkout/chk_abcdef12",
      "balance_checkout_id": "bal_1234abcd",
      "balance_checkout_url": "https://app.recurrente.com/payments/balance/bal_1234abcd",
      "no_show_fee_checkout_id": "nsf_5678efgh",
      "booking_series_id": "ser_4a3b2c1d",
      "access_url": "https://app.recurrente.com/bookings/access/bk_7e6f5d4c",
      "customer_note": "Prefiere horario por la mañana",
      "merchant_note": "Cliente frecuente, ofrecer descuento en próxima cita",
      "accepted_at": "2026-09-30T14:00:00-06:00",
      "hold_expires_at": "2026-10-01T14:00:00-06:00",
      "cancelled_by": "merchant",
      "cancellation_reason": "Reprogramación solicitada por cliente",
      "rescheduled_from_id": "bk_12345678",
      "metadata": {},
      "created_at": "2026-09-30T13:55:00-06:00"
    }
  ],
  "skipped_starts_at": [
    "2026-10-21T10:00:00-06:00"
  ],
  "created_at": "2026-09-30T13:50:00-06:00"
}

Reserva la misma cita varias veces (“cada 2 semanas, 10 veces”), como “Repetir” en Nueva cita: el mismo cliente, servicio y profesional en cada hora. Una hora ocupada o cerrada no detiene la serie: se salta y aparece en skipped_starts_at, para reservarla a mano. Cada visita se cobra el día de la cita; la serie no pide pago por adelantado.

frequency es day, week, month, year, o back_to_back (una tras otra el mismo día). Indica occurrences o ends_on.

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.

Request

This endpoint expects an object.

service_idstringRequired

starts_atdatetimeRequired

La primera cita.

frequencyenumRequired

Allowed values:

staff_member_idstringOptional

product_variant_idstringOptional

customer_idstringOptional

customerobjectOptional

intervalintegerOptional1-52Defaults to 1

Cada cuántas unidades de frequency.

occurrencesintegerOptional1-104

Cuántas citas en total.

ends_ondateOptional

Hasta qué día, en vez de occurrences.

Response

Las citas reservadas y las horas que no cupieron

idstringOptional

frequencyenumOptional

Allowed values:

intervalintegerOptional

occurrencesinteger or nullOptional

ends_ondate or nullOptional

bookingslist of objectsOptional

Las citas que la serie reservó.

skipped_starts_atlist of datetimesOptional

Las horas que no cupieron (ocupadas o cerradas), para reservarlas a mano.

created_atdatetimeOptional

Errors

403

Forbidden Error

422

Unprocessable Entity Error