Reservar una estadía

POST

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

POST

/api/stays

curl -X POST https://app.recurrente.com/api/stays \
     -H "X-SECRET-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "room_type_id": "svc_9876abcd",
  "check_in_on": "2024-07-20",
  "check_out_on": "2024-07-25"
}'

{
  "id": "bk_4f5e6d7c",
  "account_id": "ac_1234abcd",
  "status": "pending",
  "source": "storefront",
  "starts_at": "2024-07-20T15:00:00Z",
  "ends_at": "2024-07-25T11:00:00Z",
  "customer": {
    "id": "cus_7890efgh",
    "name": "Carlos Méndez",
    "email": "carlos.mendez@example.com",
    "phone": "+50255567890"
  },
  "segments": [
    {
      "service_id": "svc_9876abcd",
      "product_id": "prd_1234abcd",
      "product_variant_id": "pv_5678efgh",
      "staff_member_id": "stf_4321dcba",
      "resource_id": "res_8765hgfe",
      "kind": "service",
      "starts_at": "2024-07-20T15:00:00Z",
      "ends_at": "2024-07-25T11:00:00Z"
    }
  ],
  "staff_member_id": "stf_4321dcba",
  "resource_id": "res_8765hgfe",
  "class_session_id": "cls_1357aceg",
  "stay": {
    "room_type_id": "svc_9876abcd",
    "unit_id": "res_8765hgfe",
    "unit_name": "Suite Jardín",
    "check_in_on": "2024-07-20",
    "check_out_on": "2024-07-25",
    "nights": 5,
    "guests": 2,
    "service_tab_id": "tab_2468bdfh",
    "registered_guests": [
      {
        "name": "Carlos Méndez",
        "document": "DPI 4567 89123 4567",
        "nationality": "Guatemalteco"
      }
    ],
    "guests_registered_at": "2024-07-20T15:00:00Z"
  },
  "payment_policy": "card_on_file",
  "currency": "GTQ",
  "total_in_cents": 500000,
  "paid_in_cents": 150000,
  "balance_in_cents": 350000,
  "balance_paid_outside_at": "2024-07-18T10:00:00Z",
  "checkout_id": "chk_11223344",
  "checkout_url": "https://checkout.recurrente.com/pay/chk_11223344",
  "balance_checkout_id": "chk_55667788",
  "balance_checkout_url": "https://checkout.recurrente.com/pay/chk_55667788",
  "no_show_fee_checkout_id": "chk_99887766",
  "booking_series_id": "ser_33445566",
  "access_url": "https://app.recurrente.com/bookings/bk_4f5e6d7c/access",
  "customer_note": "Por favor, habitación con vista al jardín.",
  "merchant_note": "Cliente frecuente, ofrecer upgrade si hay disponibilidad.",
  "accepted_at": "2024-06-15T12:00:00Z",
  "hold_expires_at": "2024-06-20T12:00:00Z",
  "cancelled_by": "customer",
  "cancellation_reason": "Cambio de planes",
  "rescheduled_from_id": "bk_1234abcd",
  "metadata": {},
  "created_at": "2024-06-15T11:45:00Z"
}

Reserva noches en un tipo de habitación que GET /lodging/availability ofreció: llegada, salida y huéspedes. El huésped recibe la habitación que deja menos noches sueltas. La política de pago del tipo decide qué pasa, como en la página pública: sin pago queda confirmed; con anticipo, pago total o tarjeta en archivo queda pending con checkout_url mientras el huésped paga. Responde la reserva (stay trae la habitación y las fechas); se lee, cambia y cancela como cualquier otra en /bookings. Usa un Idempotency-Key único por estadía.

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.

room_type_idstringRequired

El tipo de habitación (un servicio kind: lodging).

check_in_ondateRequired

check_out_ondateRequired

guestsintegerOptionalDefaults to 1

customer_idstringOptional

customerobjectOptional

customer_notestringOptional

merchant_notestringOptional

protectionenumOptional

Con política card_on_file: card deja la tarjeta; deposit paga la primera noche, para quien no tiene tarjeta.

Allowed values:

success_urlstringOptional

Response

Estadía reservada

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

422

Unprocessable Entity Error