Registrar a los huéspedes

PUT

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

PUT

/api/stays/:stay_id/guest_registration

curl -X PUT https://app.recurrente.com/api/stays/stay_id/guest_registration \
     -H "X-SECRET-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "guests": [
    {}
  ]
}'

200Updated

{
  "id": "bk_9f8e7d6c",
  "account_id": "ac_4b3a2c1d",
  "status": "pending",
  "source": "storefront",
  "starts_at": "2024-01-15T09:30:00Z",
  "ends_at": "2024-01-15T10:30:00Z",
  "customer": {
    "id": "cus_7a6b5c4d",
    "name": "Carlos Méndez",
    "email": "carlos.mendez@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-01-15T09:30:00Z",
      "ends_at": "2024-01-15T10:30:00Z"
    }
  ],
  "staff_member_id": "stf_3456efgh",
  "resource_id": "res_7890ijkl",
  "class_session_id": "cls_1122aabb",
  "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_3344ccdd",
    "registered_guests": [
      {
        "name": "Lucía Pérez",
        "document": "DPI 1234 56789 0101",
        "nationality": "Guatemalteca"
      }
    ],
    "guests_registered_at": "2024-01-15T09:30:00Z"
  },
  "payment_policy": "none",
  "currency": "GTQ",
  "total_in_cents": 20000,
  "paid_in_cents": 10000,
  "balance_in_cents": 10000,
  "balance_paid_outside_at": "2024-01-15T09:30:00Z",
  "checkout_id": "chk_55667788",
  "checkout_url": "https://checkout.recurrente.com/pay/chk_55667788",
  "balance_checkout_id": "bal_99887766",
  "balance_checkout_url": "https://checkout.recurrente.com/pay/bal_99887766",
  "no_show_fee_checkout_id": "noshow_11223344",
  "booking_series_id": "ser_22334455",
  "access_url": "https://app.recurrente.com/bookings/bk_9f8e7d6c/access",
  "customer_note": "Prefiere habitación con vista al lago",
  "merchant_note": "Cliente frecuente, ofrecer upgrade si disponible",
  "accepted_at": "2024-01-10T08:00:00Z",
  "hold_expires_at": "2024-01-12T08:00:00Z",
  "cancelled_by": "customer",
  "cancellation_reason": "Cambio de planes",
  "rescheduled_from_id": "bk_7e6d5c4b",
  "metadata": {},
  "created_at": "2024-01-01T12:00:00Z"
}

El registro de huéspedes que INGUAT pide: nombre, documento y nacionalidad de cada uno, hasta 20. Reemplaza la lista; una fila sin nombre se ignora.

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.

Path parameters

stay_idstringRequired

Request

This endpoint expects an object.

guestslist of objectsRequired

Response

La estadía con su registro

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