Reservar una cita
Reserva una hora que GET /availability ofreció (service_id y
starts_at, y staff_member_id si el cliente eligió con quién), o un
lugar en una clase (class_session_id). Identifica al cliente con
customer_id, o con customer.phone y customer.name para crearlo si no
existe.
La política de pago del servicio decide qué pasa: sin pago la cita queda
confirmed (o pending si el negocio acepta cada cita a mano); con
anticipo, pago total o tarjeta en archivo queda pending con
checkout_url, la hora apartada mientras el cliente paga, y se confirma
al pagarse. Si alguien tomó la hora antes, responde 422 con
code: slot_taken; si la clase se llenó, code: full.
Usa un Idempotency-Key único por cita.
Authentication
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
ID del servicio o del producto. Requerido salvo con class_session_id.
El inicio exacto que ofreció GET /availability.
Con quién. Sin él, quien tenga menos citas ese día.
La variante del servicio, si tiene (su duración y precio mandan).
Un lugar en esta sesión de clase, en vez de una hora.
Con política card_on_file: card deja la tarjeta; deposit paga el monto de la protección como anticipo, para quien no tiene tarjeta.
A dónde vuelve el cliente después de pagar. Por defecto, su página de la cita.
Response
Cuenta (sucursal) de la cita.
pending mientras el cliente paga o el negocio decide; confirmed cuando la hora es del cliente.
Por dónde entró la reserva.
Los tramos de la cita, uno por servicio (dos si el servicio tiene tiempo de proceso). Vacío en un lugar de una clase.
La sesión, si la cita es un lugar en una clase.
Las noches en una habitación, si la reserva es una estadía de alojamiento.
Lo que el cliente ya pagó (anticipo, total o protección).
Lo que falta cobrar el día de la cita. 0 en una sesión de paquete o un saldo cobrado afuera.
Cuándo el negocio marcó el saldo como cobrado fuera de Recurrente.
Donde el cliente paga lo que la política pide, o deja su tarjeta.
El link del saldo, después de POST /bookings/{booking_id}/balance_charge.
La serie que la reservó, si se repite.
La página del cliente para ver, pagar o cancelar su cita (link firmado).
Hasta cuándo se aparta la hora si nadie paga.
La cita que esta reemplazó al moverse de hora.