API Pública de Reservas

Ejemplo de request

curl https://app.artechia.com/api/public/property\
  ?org_slug=hotel-costa\
  &property_slug=mar-azul

Respuesta 200

{
  "ok": true,
  "property": {
    "name": "Hotel Mar Azul",
    "description": null,          // LEGADO — ver nota abajo; no construyas sobre este campo
    "address": "Av. Costanera 1234, Mar del Plata",               // puede ser null
    "currency": "ARS",
    "timezone": "America/Argentina/Buenos_Aires",  // puede ser null
    "check_in_time": "14:00",       // HH:MM — horario de check-in del hotel
    "check_out_time": "11:00",      // HH:MM — horario de check-out del hotel
    "closed_periods": [             // el hotel NO toma reservas en estas fechas
      { "start": "2026-08-03",      // inclusivo
        "end":   "2026-11-01",      // EXCLUSIVO: se puede reservar desde este día
        "reason": "Solo abrimos en temporada de verano." }   // puede ser null
    ],
    "branding": {                   // los 3 campos pueden venir null
      "primary_color": "#2D4F3C",
      "logo_url": "https://mi-hotel.com/logo.svg",
      "hero_image_url": "https://mi-hotel.com/hero.jpg"
    },
    "checkout": {
      "special_requests_enabled": true,
      "terms": "Política de cancelación: ...",  // null si no configurados
      "bookings_enabled": true,          // ← ver abajo: si es false, NO muestres el flujo
      "bookings_disabled_reason":  null, // "hotel_paused" | "no_payment_method"
      "bookings_disabled_message": null, // texto en español, mostrable al huésped
      "payment_methods": {
        "mercadopago": true,
        "transferencia": false,
        "contact_hotel": false,      // "coordinar con el alojamiento" (sin pago online)
        "card_manual": false         // el huésped manda la tarjeta y el hotel la cobra a mano
      },
      "contact_hotel": {             // null salvo que contact_hotel === true
        "email": "reservas@mi-hotel.com",   // puede ser null
        "phone": "+54 9 223 444-5555",      // el primero; null si no hay ninguno
        "phones": ["+54 9 223 444-5555", "+54 9 11 1234-5678"]  // todos los cargados
      },
      "custom_fields": [             // máx 10 por propiedad
        {
          "id": "uuid",
          "key": "hora_llegada",
          "label": "Hora estimada de llegada",
          "type": "select",            // "text" | "textarea" | "select"
          "required": true,
          "placeholder": "",           // PUEDE FALTAR (campo opcional del hotel)
          "options": ["Antes de 14hs", "14-18hs", "Después de 18hs"]  // PUEDE FALTAR
        }
      ]
    }
  }
}

// ⚠️ description — CAMPO DE LEGADO, NO LO USES
//   El panel ya no le pide una descripción al hotel, así que este campo llega
//   null en todo alojamiento creado desde el 27/08/2026. En los anteriores
//   trae lo que tenía cargado y ya no se puede cambiar.
//   Se sigue devolviendo para no romper integraciones que lo leen. Si tu página
//   necesita un texto de presentación, ponelo de tu lado.

// ⚠️ bookings_enabled — LO PRIMERO QUE TENÉS QUE MIRAR
//   false ⇒ el hotel NO toma reservas online. Hay dos motivos y conviene
//   distinguirlos, porque uno es una decisión del hotel y el otro un descuido:
//
//   1) "hotel_paused" — apagó el interruptor "Aceptar reservas online" en su
//      panel: temporada cerrada, obras, se va de viaje. bookings_disabled_message
//      trae EL TEXTO QUE ESCRIBIÓ EL HOTEL, que suele decir cuándo vuelve a abrir
//      ("Las reservas abren el 1 de noviembre."). Mostralo tal cual.
//
//   2) "no_payment_method" — no configuró ningún método de cobro. No es una
//      decisión: probablemente no sabe que está así, y no puede recibir plata.
//
//   En los dos casos NO muestres el calendario ni el buscador: mostrá
//   bookings_disabled_message junto a los datos de contacto del hotel (los de
//   tu propio sitio: teléfono, WhatsApp, mail).
//
//   Esto NO es un chequeo de cortesía que podés saltearte: /checkout/start y
//   /checkout/confirm validan lo mismo del lado del servidor y rechazan con
//   422 BOOKINGS_DISABLED. Ignorarlo solo hace que el huésped complete todo el
//   formulario para chocar contra un error al final.
//
// payment_methods refleja exactamente lo que /confirm va a aceptar: ofrecé solo
//   los que estén en true y no deduzcas nada por tu cuenta. La clave de acá es
//   el valor que va en payment_method — "contact_hotel" incluido. En las
//   RESPUESTAS ese método sale como "manual", que es como lo guarda el sistema.

// closed_periods — temporadas cerradas (solo las que no terminaron).
//   Grisá esas fechas en tu calendario y mostrá el "reason": el huésped tiene
//   que entender que no es que esté lleno, sino que el hotel abre más adelante.
//   "end" es EXCLUSIVO: con end 2026-11-01 se puede entrar el 1 de noviembre.
//   /checkout/start y /confirm rechazan esas fechas con 422 PROPERTY_CLOSED.

// custom_fields — placeholder y options son OPCIONALES en el objeto: usá
//   (f.placeholder ?? "") y (f.options ?? []). options solo tiene sentido con
//   type === "select".

// 404 ORG_NOT_FOUND también cuando la organización existe pero está suspendida
//   (aunque hayas omitido org_slug).

Ejemplo de request

curl "https://app.artechia.com/api/public/availability\
  ?org_slug=hotel-costa\
  &property_slug=mar-azul\
  &from=2025-07-01\
  &to=2025-07-31"

Respuesta 200

{
  "ok": true,
  "days": [
    {
      "date": "2025-07-01",
      "status": "available",
      "free_units": 8,          // unidades LIBRES reales ese día
      "total_units": 8,         // unidades operativas del hotel
      "has_offer": false,
      "promotion": null,
      "closed": false,          // el hotel no toma reservas ese día
      "closed_reason": null     // motivo que cargó el hotel, para mostrarlo
    },
    {
      "date": "2025-07-04",
      "status": "limited",
      "free_units": 1,
      "total_units": 8,
      "has_offer": true,
      "promotion": {
        "id": "promo-uuid",
        "name": "Oferta de verano",
        "rule_type": "percent",   // "percent" | "fixed" | "stay_pay"
        "rule_value": "10",       // "10" (%) | "5000" ($) | "3/2" (stay/pay)
        "label": "10% off"        // legible: "10% off" | "-5000" | "3×2"
      }
    },
    { "date": "2025-07-10", "status": "unavailable", "free_units": 0, "total_units": 8, "has_offer": false, "promotion": null }
  ]
}

// status (calculado con ocupación REAL: reservas + locks + cupo + mantenimiento):
//   "available"   → verde / accent. Hay lugar.
//   "limited"     → amarillo. Quedan pocas (umbral PROPORCIONAL al tamaño:
//                   nunca "limited" si total_units === 1). free_units === 1 →
//                   "¡Última!". Mostrar free_units para dar urgencia real.
//   "unavailable" → free_units === 0 (lleno / cerrado) o fecha pasada. Gris,
//                   no clickeable — salvo como fecha de CHECK-OUT (el día de
//                   salida no consume noche; validá que todas las noches del
//                   rango [check_in, check_out) sean != unavailable).
// closed === true → el alojamiento está CERRADO ese día (temporada baja,
//   refacciones). Siempre viene con status "unavailable" y free_units 0, pero
//   no es lo mismo que "lleno": mostrá closed_reason para que el huésped sepa
//   que puede volver en otra fecha, en vez de creer que no hay lugar.
//   Ponelo al PIE del calendario, no solo en el tooltip del día: esos días no
//   se pueden clickear y en celular no hay hover, así que nadie lo lee.
// promotion !== null → pintar VERDE con badge (promotion.label). Vale también
//   para promos GLOBALES del hotel (aplican a todas las propiedades).
//   Explicá stay_pay en la leyenda: rule_value "3/2" = "quedate 3, pagá 2".
// has_offer === (promotion !== null) — campo de retrocompat
//
// OJO: la promo del calendario es informativa (es la promo activa ese día por
//   fecha/prioridad). Puede tener condiciones que la reserva concreta no cumpla
//   (min_nights, room_type_ids). El descuento REAL lo dice /search o /quote.
//
// from/to inválidos (formato, from >= to, rango > 93 días) → 400 VALIDATION,
//   NO 422 INVALID_DATES.

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/search\
  -H "Content-Type: application/json" \
  -d '{
    "org_slug": "hotel-costa",
    "property_slug": "mar-azul",
    "check_in": "2025-07-10",
    "check_out": "2025-07-13",
    "adults": 2
  }'

Respuesta 200

{
  "ok": true,
  "currency": "ARS",
  "check_in": "2025-07-10",
  "check_out": "2025-07-13",
  "adults": 2,
  "children": 0,

  // Una sola frase para mostrar cuando NADA se puede reservar, ya escrita para
  // un huésped: "Esta habitación no admite niños", "La estadía mínima en estas
  // fechas es de 3 noches", "No quedan habitaciones libres para esas fechas".
  // null si alguna habitación sí se puede reservar, o si los motivos difieren
  // entre sí (ahí mostrá el de cada results[].error).
  "notice": null,

  "results": [
    {
      "room_type": {
        "id": "uuid",
        "name": "Suite Panorámica",
        "slug": "suite-panoramica",
        "description": "Vista al mar con jacuzzi.",
        "tagline": "Lujo frente al mar",
        "size_m2": 38,
        "max_occupancy": 3,
        "capacity_children": 1,
        "photo_url": "https://...",      // primera foto (thumbnail)
        "photos": [                       // galería completa — para slider/lightbox
          { "url": "https://foto1.jpg", "alt": "Vista principal",
            "thumb_url": "https://foto1-thumb.webp" },   // ~640px, null en fotos viejas
          { "url": "https://foto2.jpg", "alt": "Baño", "thumb_url": null }
        ],
        "amenities": ["WiFi", "Aire acondicionado", "TV", "Jacuzzi"]
      },
      "available_units": 3,              // unidades LIBRES reales del tipo en ese rango
      "quote": {
        "nights_count": 3,
        "totals": {
          "subtotal_base":   90000,     // suma de noches sin descuentos
          "discount_amount":  9000,     // descuento aplicado (promo + cupón)
          "extras_total":        0,     // extras obligatorios pre-incluidos
          "taxes_total":         0,     // impuestos si aplica
          "tax_pct":             0,
          "total":           81000,     // total final a pagar
          "deposit_pct":        50,     // % de seña (0 si el plan no pide seña)
          "deposit_due":     40500,     // seña a pagar con MP
          "currency":        "ARS"
        },
        // ⚠️ OJO CON EL NOMBRE: acá el total se llama "total", pero la respuesta
        // de /checkout/confirm y la de /booking/lookup lo llaman "grand_total".
        // Es el mismo número. Leer el campo equivocado devuelve undefined y
        // termina mostrando "$undefined" en pantalla.
        "validation": {
          "has_rate":     true,
          "stop_sell":    false,
          "closed":       false,   // fecha cerrada a la venta por el hotel
          "min_stay_ok":  true,
          "max_stay_ok":  true,
          "occupancy_ok": true,
          "min_stay":     1,
          "max_stay":     30
        },
        "promotion": { "id": "uuid", "description": "10% off temporada alta", "discount_amount": 9000 } | null
      },
      "error": null
    },
    {
      "room_type": { ... },
      "quote": null,
      "error": { "code": "BASE_RATE_NOT_FOUND", "message": "..." }  // no cotizable
    }
  ]
}

// ── REGLA PARA MOSTRAR "Reservar" ──────────────────────────────────────────
//   const v = r.quote?.validation;
//   const reservable = !!r.quote && r.available_units > 0 &&
//     v.has_rate && !v.stop_sell && !v.closed &&
//     v.min_stay_ok && v.max_stay_ok && v.occupancy_ok;
//
// available_units es la disponibilidad REAL (reservas + holds + cupo manual +
// unidades en mantenimiento) del tipo en ese rango. "validation" NO la mira:
// una habitación agotada puede tener validation impecable. Sin este chequeo
// mostrarías como reservable algo que revienta con 409 NO_AVAILABILITY recién
// en /checkout/start, después de que el huésped completó todo el formulario.
// Con available_units === 1 podés mostrar "¡Última disponible!".

// NOTA: /search devuelve un quote REDUCIDO (sin policy / nights / coupon /
// coupon_error / extras). Para la política de cancelación o el desglose noche
// por noche, usá /quote.
//
// /search NUNCA falla por una habitación: devuelve TODOS los tipos activos y
// pone el motivo en results[].error (quote: null). Los códigos posibles ahí son
// los mismos del loader/pricing: BASE_RATE_NOT_FOUND, RATE_PLAN_NOT_FOUND,
// VALIDATION_FAILED, INVALID_DATES. El HTTP sigue siendo 200.
//
// results[].error.message ya viene escrito para el huésped y dice QUÉ cambiar:
// "Esta habitación no admite niños", "Esta habitación admite hasta 2 adultos",
// "La estadía mínima en estas fechas es de 3 noches. Elegiste 2 noches".
// Mostralo tal cual en la tarjeta en vez de un "no disponible" genérico: es la
// diferencia entre que la persona corrija la búsqueda o se vaya del sitio.
//
// check_out <= check_in → 400 VALIDATION (acá, a diferencia de /quote, que
// devuelve 422 INVALID_DATES). check_in en el pasado → 422 INVALID_DATES.

Ejemplo de request

curl "https://app.artechia.com/api/public/room-type\
  ?org_slug=hotel-costa\
  &property_slug=mar-azul\
  &room_type_slug=suite-panoramica"

Respuesta 200

{
  "ok": true,
  "room_type": {
    "id":                "uuid",
    "name":              "Suite Panorámica",
    "slug":              "suite-panoramica",
    "description":       "Vista al mar con jacuzzi.",
    "tagline":           "Lujo frente al mar",   // frase corta marketing
    "size_m2":           38,                      // null si no configurada
    "max_occupancy":     3,
    "max_adults":        2,
    "capacity_children": 1,
    "base_occupancy":    2,
    "photo_url":         "https://...",           // thumbnail
    "photos":            [{ "url": "...", "alt": "...", "thumb_url": "...|null" }],
    "amenities":         ["WiFi", "AC", "TV"]
  }
}

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/quote\
  -H "Content-Type: application/json" \
  -d '{
    "org_slug": "hotel-costa",
    "property_slug": "mar-azul",
    "room_type_slug": "suite-panoramica",
    "check_in": "2025-07-10",
    "check_out": "2025-07-13",
    "adults": 2,
    "coupon_code": "VERANO10"
  }'

Respuesta 200

{
  "ok": true,
  "quote": {
    "nights_count": 3,
    "nights": [   // desglose noche por noche (NO se llama "nightly_breakdown")
      { "date": "2025-07-10", "base": 30000, "occ_adj": 0,
        "single_use": 0, "total": 30000, "rate_plan_id": "uuid", "source": "base" }
      // source: "base" (tarifa base) | "daily" (override por día)
      // single_use: descuento por uso individual (siempre <= 0)
    ],
    "extras": [   // líneas de extras (incluye obligatorios con mandatory:true)
      { "extra_id": "uuid", "name": "Spa", "unit_price": 5000,
        "qty": 1, "total": 5000, "mandatory": false }
    ],
    "coupon": {   // null si no se aplicó cupón
      "id": "uuid", "code": "VERANO10", "type": "percent", "value": 10, "amount": 9000
    },
    "coupon_error": null,   // ← ver abajo: por qué NO se aplicó el cupón
    "promotion": {  // null si no hay promo automática
      "id": "uuid", "description": "10% off temporada alta", "discount_amount": 9000
    },
    "totals": {
      "subtotal_base":  90000,
      "discount_amount": 9000,
      "extras_total":       0,
      "taxes_total":        0,
      "tax_pct":            0,
      "total":          81000,
      "deposit_pct":       50,
      "deposit_due":    40500,
      "currency":       "ARS"
    },
    "validation": {  // mismos campos que /search + min_stay / max_stay
      "has_rate": true, "stop_sell": false, "closed": false, "min_stay_ok": true,
      "max_stay_ok": true, "occupancy_ok": true, "min_stay": 1, "max_stay": 30
    },
    "policy": {   // ← POLÍTICA DE CANCELACIÓN (solo en /quote, no en /search)
      "is_refundable": true,
      "cancellation_type": "flexible",          // flexible|moderate|strict|non_refundable
      "cancellation_deadline_date": "2025-07-08", // hasta cuándo se cancela sin penalidad
      "cancellation_deadline_days": 2,
      "penalty_type": "first_night"             // tipo de penalidad si cancela tarde
    }
  }
}

// Para mostrar la POLÍTICA DE CANCELACIÓN en tu sitio: usá quote.policy.
// /search NO la incluye (devuelve un quote reducido), así que si la querés
// por habitación tenés que llamar a /quote para cada una.

// ── CUPONES: un cupón inválido NO hace fallar el request ────────────────────
// Si mandás coupon_code y el código no sirve, la respuesta sigue siendo 200 y
// el quote se calcula SIN el descuento (con la promo automática si aplica).
// La única señal está en quote.coupon_error:
//
//   "coupon_error": {
//     "code":    "VERANO10",              // el código que mandaste
//     "reason":  "EXPIRED",
//     "message": "El código de descuento venció."   // en español, mostrable
//   }
//
// reason: NOT_FOUND | NOT_STARTED | EXPIRED | MIN_NIGHTS_NOT_MET |
//         ROOM_NOT_ELIGIBLE | RATE_NOT_ELIGIBLE | LIMIT_REACHED |
//         USER_LIMIT_REACHED | NO_DISCOUNT | PROMO_IS_BETTER
//         (PROMO_IS_BETTER: la promoción automática ya descuenta más;
//          se mantiene la promoción)
//
// Regla para tu UI: cupón aplicado ⟺ quote.coupon !== null && discount > 0.
// Si quote.coupon_error !== null, mostrá coupon_error.message y NO marques el
// cupón como aceptado. Nunca existió un error 422 COUPON_INVALID.
//
// El límite por email (USER_LIMIT_REACHED) solo se puede evaluar si mandás
// "email". Sin él, un cupón agotado para ese huésped se ve válido acá y recién
// lo rechaza /checkout/confirm con 409 COUPON_USER_LIMIT_REACHED.

// check_out <= check_in → 422 INVALID_DATES. check_in en el pasado → 422 INVALID_DATES.

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/checkout/start\
  -H "Content-Type: application/json" \
  -d '{
    "org_slug": "hotel-costa",
    "property_slug": "mar-azul",
    "room_type_slug": "suite-panoramica",
    "check_in": "2025-07-10",
    "check_out": "2025-07-13",
    "adults": 2,
    "ttl_minutes": 15,
    "coupon_code": "VERANO10",
    "extras": [{ "extra_id": "uuid-del-extra", "qty": 2 }]
  }'

Respuesta 200

{
  "ok": true,
  "checkout_token": "eyJ...",   // token firmado con HMAC, ~600–900 chars
  "lock_key": "2a6527aa61dea2808a45b18fe9e38ae2d28174f3a34c20bc",  // hex 48, opaco
  "expires_at": "2026-07-24T23:45:19.605738+00:00",  // ISO con OFFSET (no "Z")
  "ttl_minutes": 15,
  "holds_inventory": true, // false si el alojamiento no guarda la habitación durante el checkout: sigue a la venta y /confirm puede dar 409 NO_AVAILABILITY
  "available_after": 4,   // ← ver nota: es el conteo ANTES de tomar este lock
  "quote": { ... }        // mismo formato que /quote (incluye coupon_error)
}

// El checkout_token va en el body de /checkout/confirm
// y como Bearer en /checkout/extras. Tratalo como opaco.
//
// ⚠️ available_after — el nombre engaña. Es la disponibilidad medida ANTES de
//    insertar este lock, así que después de tu request quedan
//    (available_after − 1) unidades. available_after === 1 significa que
//    acabás de tomar la ÚLTIMA: "¡Era la última!" es correcto, "queda 1" NO.
//
// ⚠️ lock_key NO se usa desde el front: todo se hace con el checkout_token.
//
// ⚠️ expires_at viene con offset "+00:00", no con "Z". new Date() lo parsea
//    igual; no lo cortes con slice() ni asumas el sufijo Z.

Ejemplo de request

curl https://app.artechia.com/api/public/checkout/extras\
  -H "Authorization: Bearer eyJ..."

Respuesta 200

{
  "ok": true,
  "extras": [
    {
      "id": "uuid-extra-spa",
      "name": "Acceso al spa",
      "description": "Acceso ilimitado durante la estadía.",
      "price": 5000,
      "price_type": "per_booking",   // 9 valores posibles — ver abajo, NO son solo 3
      "max_qty": 1
    },
    {
      "id": "uuid-extra-parking",
      "name": "Estacionamiento",
      "description": null,
      "price": 1500,
      "price_type": "per_night",
      "max_qty": 2
    }
  ]
}

// price_type — el hotel puede configurar CUALQUIERA de estos valores:
//   per_booking / per_stay / fixed → precio único por toda la reserva
//   per_night                      → precio × cantidad de noches
//   per_person                     → precio × (adultos + niños)
//   per_person_per_stay            → precio × huéspedes (una vez)
//   per_pax_night / per_person_per_night → precio × huéspedes × noches
//   percent_of_room                → porcentaje del subtotal de habitación
//
// NO hardcodees la multiplicación: el total que vale es el de /quote o
// /checkout/start con el extra ya incluido. Si necesitás mostrar el importe
// antes de pedirlo, tratá price_type desconocido como "por reserva".
//
// max_qty puede venir null → sin tope (usá un máximo razonable, ej. 10).
// description puede ser null.
// Si extras está vacío → no mostrar sección de extras.
// Los extras seleccionados se envían en /confirm: extras: [{ extra_id, qty }]
//
// Errores (mismo formato que el resto: { ok:false, error:{ code, message } }):
//   401 TOKEN_MALFORMED / TOKEN_BAD_SIGNATURE / TOKEN_INVALID_JSON
//   410 TOKEN_EXPIRED   → el lock venció, reiniciá desde /checkout/start
//   429 RATE_LIMITED

Ejemplo de request

curl -X PATCH https://app.artechia.com/api/public/checkout/guest-preview\
  -H "Content-Type: application/json" \
  -d '{
    "checkout_token": "eyJ...",
    "guest": {
      "first_name": "María",
      "last_name": "González",
      "email": "maria@ejemplo.com"
    }
  }'

Respuesta 200

{ "ok": true }

// Devuelve 200 aunque el lock ya no exista o no hayas mandado ningún campo
// dentro de "guest" (el objeto guest sí tiene que estar presente).
// Errores posibles: 400 VALIDATION / INVALID_BODY, 401 TOKEN_MALFORMED,
// 410 TOKEN_EXPIRED, 429 RATE_LIMITED — todos con { ok:false, error:{...} }.
//
// Es fire-and-forget: NUNCA bloquees el checkout por lo que devuelva.

Ejemplo de request

curl "https://app.artechia.com/api/public/checkout/lock-status\
  ?checkout_token=eyJ..."

Respuesta 200

// Lock activo:
{
  "active": true,
  "expires_at": "2026-07-24T23:45:19.605738+00:00",
  "seconds_remaining": 600
}

// Lock inactivo:
{
  "active": false,
  "reason": "confirmed" | "expired" | "cancelled" | "invalid" | "rate_limited"
}

// reason:
//   "confirmed"  → el lock se consumió porque la reserva SE CREÓ. Es el final
//                  feliz, no un error. Cortá el polling apenas confirmás y, si
//                  igual llega, no muestres ningún cartel de cancelación.
//   "expired"    → venció el TTL → reiniciar desde /checkout/start.
//   "cancelled"  → el hotel dio de baja el hold desde el panel.
//   "invalid"    → token ausente, mal formado o con firma inválida.
//   "rate_limited" → único caso con status 429.
//
// Siempre devuelve 200 (excepto rate_limited → 429) para no revelar si el
// token es válido a través del status code. Este endpoint NO usa el formato
// { ok, error } del resto de la API.
//
// ⚠️ NO confundir con GET /api/public/checkout/status?token=... — existe, pero
// NO es un alias: es un endpoint viejo que usa la página de checkout alojada en
// Artechia, y contesta distinto.
//
//   caso                  /lock-status                     /status
//   lock vivo             active:true + expires_at +       active:true
//                         seconds_remaining                (sin contador)
//   reserva ya creada     active:FALSE, reason:"confirmed"  active:TRUE, reason:"confirmed"
//
// O sea que "active" sale INVERTIDO una vez que la reserva se creó. Si armás el
// countdown contra /status vas a mostrar el lock como vivo para siempre.
// Usá /lock-status.

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/checkout/confirm\
  -H "Content-Type: application/json" \
  -d '{
    "checkout_token": "eyJ...",
    "guest": {
      "first_name": "María",
      "last_name": "González",
      "email": "maria@ejemplo.com",
      "phone": "+5491122334455",
      "document_type": "DNI",
      "document_number": "30123456",
      "country": "AR"
    },
    "payment_method": "mercadopago",
    "special_requests": "Llegada tardía, cuna extra",
    "accept_terms": true
  }'

Respuesta 200

{
  "ok": true,
  "booking_id":    "uuid-de-la-reserva",
  "booking_code":  "ART260705A647",  // código legible para mostrar
  "access_token":  "<64-char-hex-token>",
  "manage_url":    "https://app.artechia.com/my-booking?code=...&token=...",
  "grand_total":   81000,
  "deposit_due":   40500,
  "deposit_pct":   50,                    // % de seña del plan (0 si no hay seña)
  "currency":      "ARS",
  "status":        "pending",             // ver nota
  "idempotent":    false,                 // true si fue un re-submit y devolvió la reserva existente

  // SOLO si payment_method === "mercadopago" (preference generada inline):
  "payment_link": {
    "init_point":    "https://www.mercadopago.com.ar/checkout/v1/redirect?pref_id=...",
    "preference_id": "1234567-abc",
    "pay_mode":      "deposit",           // "deposit" | "total" | "balance"
    "amount":        40500
  },
  // SOLO si payment_method === "transferencia":
  "bank_data": { "cbu": "...", "alias": "...", "bank": "...", "holder": "..." },
  // SOLO si payment_method === "manual" (coordinar con el alojamiento):
  // "phone" es el primero de la lista; "phones" los trae todos.
  "contact_hotel": {
    "email": "reservas@hotel.com",
    "phone": "+54 9 11 5555-0000",
    "phones": ["+54 9 11 5555-0000", "+54 9 223 444-5555"]
  },
  // SOLO si payment_method === "card_manual": lo único que devolvemos de la
  // tarjeta. Los datos completos no vuelven nunca.
  "card_on_file": { "brand": "Visa", "last4": "3704" }
}

// status: una reserva recién creada SIEMPRE nace "pending". Si idempotent es
//   true, status es el estado ACTUAL de la reserva que ya existía y puede ser
//   cualquiera de: pending | confirmed | checked_in | checked_out | no_show |
//   cancelled. No existe el estado "hold".
//
// idempotent: true → NO es un error. El mismo checkout_token ya había creado
//   una reserva y te la devolvemos igual (booking_code, access_token y
//   payment_link son los de esa reserva, incluida su seña real y el link de
//   pago ya emitido). Nunca reintentes ni dupliques.
//
// MercadoPago: si payment_link viene presente, redirigí directo a
//   payment_link.init_point — NO hace falta llamar a /checkout/payment-link.
//   payment_link puede ser null si MP falló, si el hotel no tiene credenciales
//   cargadas, o si la reserva ya está saldada: en ese caso usá
//   /checkout/payment-link como fallback (o para cobrar el "balance").
//   pay_mode === "balance" solo aparece en un re-submit de una reserva que ya
//   tenía pagos aplicados.
// Transferencia: mostrá bank_data (puede tener campos null si el hotel no los
//   cargó). Es null si el método no está habilitado.
// Manual ("coordinar con el alojamiento"): viene contact_hotel con el email y
//   el teléfono a los que escribir. La reserva queda pending hasta que el hotel
//   marque el pago a mano. Es null si el método no está habilitado.
// card_manual: la tarjeta queda guardada cifrada del lado del hotel, que la
//   cobra con su posnet. NO hay autorización online: la reserva queda pending
//   hasta que el hotel registre el pago, y card_on_file sólo trae marca y
//   últimos 4 para que le muestres al huésped cuál dejó. Los datos se borran
//   solos a los 7 días o cuando el hotel marca el cobro. No los guardes de tu
//   lado ni los pidas por otro canal.
// Si el hotel configuró custom_booking_url, manage_url apunta ahí.
// Guardá booking_code + access_token.

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/checkout/payment-link\
  -H "Content-Type: application/json" \
  -d '{
    "booking_code": "ART260705A647",
    "access_token": "<64-char-hex-token>",
    "pay_mode": "deposit"
  }'

Respuesta 200

// La respuesta tiene SIEMPRE la misma forma (cambie o no reused):
{
  "ok": true,
  "init_point": "https://www.mercadopago.com.ar/checkout/v1/redirect?pref_id=...",
  "preference_id": "1234567-abc",
  "amount": 40500,
  "pay_mode": "deposit",
  "currency": "ARS",
  "reused": false        // true = se reusó la preference cacheada del booking
}

// reused: true significa que ya existía una preference con el MISMO pay_mode y
// el MISMO amount, así que no se volvió a llamar a MercadoPago. El link es
// igual de válido. No cambia nada de tu lado.
//
// Redirigir al usuario: window.location.href = init_point
// El webhook de MP confirma la reserva automáticamente cuando se paga.
//
// Una reserva eliminada por el hotel devuelve 404 NOT_FOUND (no se puede
// seguir cobrando algo que el hotel dio de baja).

Ejemplo de request

curl "https://app.artechia.com/api/public/booking/lookup\
  ?booking_code=ART260705A647\
  &email=maria@ejemplo.com"

Respuesta 200

{
  "ok": true,
  "booking": {
    "booking_code":     "ART260705A647",
    "status":           "confirmed",   // pending|confirmed|checked_in|checked_out|no_show|cancelled
    "payment_status":   "partial",     // unpaid|partial|paid|refunded|chargeback
    "check_in":         "2025-07-10",
    "check_out":        "2025-07-13",
    "nights":           3,
    "adults":           2,
    "children":         0,
    "grand_total":        81000,      // lo cotizado al reservar
    "consumptions_total": 2500,       // consumos cargados durante la estadía
    "total_due":          83500,      // grand_total + consumptions_total
    "amount_paid":        40500,
    "balance_due":        43000,      // total_due − amount_paid (nunca negativo)
    "currency":           "ARS",
    "payment_method":   "mercadopago", // mercadopago|transferencia|manual|card_manual|null
    "special_requests": "Cuna para bebé",
    "cancelled_at":     null,
    "cancel_reason":    null,
    "created_at":       "2025-07-01T10:00:00.000Z"
  },
  "guest":     { "first_name": "...", "last_name": "...", "email": "...", "phone": null },
  "property":  { "name": "...", "address": "...", "slug": "mar-azul" } | null,
  "room":      { "room_type_name": "Suite Panorámica", "room_unit_name": "Suite 301",
                 "room_unit_pending": false } | null,
  //   ⚠️ Mientras la reserva esté pendiente y sin pagar, room_unit_name viene
  //   en null y room_unit_pending en true: la habitación todavía puede
  //   cambiar, porque el hotel se la puede dar a alguien que pague antes.
  //   No le muestres un número al huésped hasta que room_unit_pending sea false.
  "rate_plan": { "name": "Tarifa Estándar" } | null,

  // Cómo pagar lo que falta. Es lo que necesitás para armar tu propia página
  // "mi reserva" sin haber guardado la respuesta de /checkout/confirm.
  "payment": {
    // null si no queda nada por pagar (o la reserva está cancelada/no_show/checked_out).
    "due": {
      "mode":        "deposit",  // deposit (seña) | balance (saldo tras un pago parcial) | total
      "amount":      40500,      // lo que hay que pagar AHORA
      "grand_total": 81000,
      "amount_paid": 40500,
      "balance":     40500,      // todo lo que falta (≥ amount: con seña, el resto va después)
      "currency":    "ARS"
    },
    // Sólo con payment_method "transferencia". Cualquier campo puede ser null.
    "bank_data": { "cbu": "...", "alias": "...", "bank": "...", "holder": "..." },
    // Con "transferencia" (para mandar el comprobante), "manual" y "card_manual".
    "contact_hotel": {
      "email": "...",
      // El primero y su link, por compatibilidad. "phones" trae todos los
      // teléfonos del alojamiento, cada uno con su propio link de WhatsApp.
      "phone": "+54 9 11 ...",
      "whatsapp_url": "https://wa.me/549...?text=...",  // mensaje ya armado
      "phones": [
        { "phone": "+54 9 11 ...", "whatsapp_url": "https://wa.me/549...?text=..." }
      ]
    },
    // Sólo con "card_manual": la tarjeta que dejó, para que la reconozca.
    // null si los datos ya se borraron (a los 7 días, o cuando el hotel marcó
    // el cobro como hecho).
    "card_on_file": { "brand": "Visa", "last4": "3704" }
  },
  "manage_url": "https://app.artechia.com/my-booking?code=...&token=..."
}

// MercadoPago no devuelve link acá (crear una preference es un efecto de lado
// y esto es un GET): pedilo con POST /checkout/payment-link.
// 404 si el booking_code no existe O si el email no coincide.
// Comparación timing-safe: no se revela cuál de los dos falló.

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/review\
  -H "Content-Type: application/json" \
  -d '{
    "code": "ART260705A647",
    "token": "<64-char-hex-token>",
    "rating": 5,
    "feedback": "Excelente atención, volveríamos."
  }'

Respuesta 200

{ "ok": true }

// Errores con el formato estándar { ok: false, error: { code, message } }:
//   400 INVALID_BODY / VALIDATION  → body mal formado o rating fuera de 1–5
//   404 NOT_FOUND                  → booking_code inexistente, eliminado, o
//                                    access_token que no coincide (timing-safe)
//   429 RATE_LIMITED

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/marketing/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "property_slug": "hotel-mar-azul",
    "email": "maria@example.com",
    "first_name": "María",
    "last_name": "González",
    "accept_marketing": true
  }'

Respuesta 200

{ "ok": true, "subscribed": true }

// La respuesta es SIEMPRE la misma, exista o no el email. Es a propósito: si
// contestara distinto, cualquiera podría averiguar quién es cliente del hotel
// probando direcciones.
//
// Tres cosas que este endpoint NO hace, y conviene saberlas:
//
//   1. NO pisa los datos de alguien que ya está en la base. Si el email
//      corresponde a un huésped que ya reservó, su nombre queda como estaba.
//   2. NO revierte una baja. Si la persona se dio de baja de los emails, sigue
//      dada de baja. Para volver a suscribirla, el hotel lo hace desde su panel.
//   3. NO manda ningún email de confirmación. Si querés doble opt-in, mandalo
//      vos desde tu sitio antes de llamar acá.
//
// Errores:
//   400 CONSENT_REQUIRED → falta accept_marketing: true
//   400 VALIDATION       → email/first_name/last_name inválidos o faltantes
//   404 PROPERTY_NOT_FOUND
//   429 RATE_LIMITED

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/group/quote \
  -H "Content-Type: application/json" \
  -d '{
    "property_slug": "cabanas-franco",
    "check_in": "2026-12-28", "check_out": "2026-12-31",
    "units": [
      { "key": "c7",  "room_type_slug": "cabana-para-7", "adults": 7 },
      { "key": "c4a", "room_type_slug": "cabana-para-4", "adults": 4 },
      { "key": "c4b", "room_type_slug": "cabana-para-4", "adults": 4 },
      { "key": "c6",  "room_type_slug": "cabana-para-6", "adults": 6 }
    ],
    "coupon_code": "FAMILIA",
    "email": "titular@example.com"
  }'

Respuesta 200

{
  "ok": true,
  "quote": {
    "check_in": "2026-12-28", "check_out": "2026-12-31", "nights_count": 3, "currency": "ARS",
    "units": [
      { "key": "c7", "room_type": { "id": "…", "slug": "cabana-para-7", "name": "Cabaña para 7" },
        "adults": 7, "children": 0, "coupon_eligible": true,
        "totals": { "subtotal_base": 300000, "promotion_discount": 0, "coupon_discount": 3225.81,
                    "discount_amount": 3225.81, "extras_total": 0, "taxes_total": 0,
                    "total": 296774.19, "deposit_pct": 30, "deposit_due": 89032.26, "balance_due": 207741.93 },
        "promotion": null, "nights": [ … ], "extras": [ … ], "policy": { … } },
      …
    ],
    "totals": { "subtotal_base": 930000, "promotions_discount": 0, "coupon_discount": 10000,
                "discount_amount": 10000, "extras_total": 0, "taxes_total": 0,
                "total": 920000, "deposit_due": 276000, "balance_due": 644000 },
    "coupon": { "code": "FAMILIA", "type": "fixed", "value": 10000, "amount": 10000,
                "eligible_unit_keys": ["c7","c4a","c4b","c6"], "excluded": [] },
    "coupon_error": null
  }
}
// La suma de las unidades es EXACTAMENTE la del grupo (total, seña, saldo, descuentos).
// coupon_error (si el cupón no aplica): { code, reason, message, excluded? }
//   reason: NOT_FOUND | NOT_STARTED | EXPIRED | MIN_NIGHTS_NOT_MET | ROOM_NOT_ELIGIBLE |
//           RATE_NOT_ELIGIBLE | LIMIT_REACHED | USER_LIMIT_REACHED | NO_DISCOUNT | PROMO_IS_BETTER
// coupon.excluded: unidades que no califican (tipo o tarifa), con su motivo.
//
// Errores (error.code + error.reason + error.unit_errors[{ key, code, reason, message }]):
//   409 NO_AVAILABILITY  reason SOLD_OUT (agotado) | TEMPORARILY_HELD (otro checkout en curso)
//   422 STAY_RESTRICTED  reason MIN_STAY | MAX_STAY | CAPACITY | CLOSED_TO_SALES | NO_RATE
//   422 PROPERTY_CLOSED  (período de cierre) · 422 BOOKINGS_DISABLED (reason HOTEL_PAUSED | NO_PAYMENT_METHOD)
//   422 INVALID_DATES (reason ADVANCE_WINDOW si es por anticipación) · 422 INVALID_UNITS

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/group/checkout/start \
  -H "Content-Type: application/json" \
  -d '{ "property_slug": "cabanas-franco", "check_in": "2026-12-28", "check_out": "2026-12-31",
        "units": [ { "key": "c7", "room_type_slug": "cabana-para-7", "adults": 7 } ],
        "coupon_code": "FAMILIA", "email": "titular@example.com",
        "idempotency_key": "web-7f3c9a2e-1" }'

Respuesta 200

{
  "ok": true,
  "checkout_token": "eyJ…",          // opaco; va a /group/checkout/confirm
  "expires_at": "2026-11-02T15:20:00.000Z",
  "ttl_minutes": 15,
  "idempotent": false,
  "quote": { … }                     // mismo formato que /group/quote
}
// 409 NO_AVAILABILITY → no quedó NADA bloqueado; error.unit_errors dice qué unidad y por qué
//     (SOLD_OUT o TEMPORARILY_HELD: otra persona terminando de reservar, reintentar en minutos).
// 409 IDEMPOTENCY_CONFLICT · 409 LOCK_TIMEOUT · 422 como /group/quote

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/group/checkout/confirm \
  -H "Content-Type: application/json" \
  -d '{ "checkout_token": "eyJ…",
        "guest": { "first_name": "Ana", "last_name": "Pérez", "email": "ana@example.com", "document_number": "30111222" },
        "payment_method": "contact_hotel", "accept_terms": true, "expected_total": 920000 }'

Respuesta 200

{
  "ok": true,
  "group_code": "GRP-037CBA6B4B",
  "group_access_token": "…",
  "summary_url": "https://…/my-booking?code=GRP-037CBA6B4B&token=…",
  "idempotent": false,
  "currency": "ARS",
  "totals": { "total": 494000, "deposit_due": 148199.99, "balance_due": 345800.01, "coupon_discount": 100000 },
  "bookings": [
    { "key": "c7", "booking_code": "ART…", "access_token": "…", "manage_url": "…",
      "room_type_name": "Cabaña para 7", "grand_total": 230631.58, "deposit_due": 69189.47, "status": "pending" },
    …
  ],
  "payment_method": "manual",
  "contact_hotel": { "email": "…", "phone": "…", "phones": ["…"] }   // o bank_data / card_on_file según el método
}
// Con payment_method "mercadopago", en vez de contact_hotel/bank_data viene:
//   "payment_link": { "init_point": "https://www.mercadopago.com.ar/checkout/v1/redirect?pref_id=…",
//                     "preference_id": "…", "pay_mode": "deposit", "amount": 148199.99 }   // o null si MP falló
//   Redirigí a init_point: es UN pago por la seña (o el total) de TODO el grupo. Al volver, MP lleva al
//   huésped a summary_url. Si vino null, pedilo con GET /api/public/group (lo crea ahí).
// 409 PRICE_CHANGED → { error: { details: { previous_total, new_total, coupon_error } }, quote: { … } }
//     Mostrá el total nuevo y reenviá con expected_total = new_total.
// 409 COUPON_LIMIT_REACHED | COUPON_USER_LIMIT_REACHED → el último uso lo tomó otro grupo: recotizá sin cupón.
// 410 TOKEN_EXPIRED | LOCK_EXPIRED | LOCK_NOT_FOUND → el plazo venció: volver a /group/checkout/start.
// 422 PAYMENT_METHOD_NOT_AVAILABLE | TERMS_NOT_ACCEPTED | VALIDATION_FAILED | GUEST_BLACKLISTED | TOKEN_INVALID

Ejemplo de request

curl -X POST https://app.artechia.com/api/public/group/checkout/release \
  -H "Content-Type: application/json" -d '{ "checkout_token": "eyJ…" }'

Respuesta 200

{ "ok": true, "released": 4 }   // 0 si ya estaban sueltos o eran reservas

Ejemplo de request

curl "https://app.artechia.com/api/public/group?code=GRP-037CBA6B4B&token=…"

Respuesta 200

{
  "ok": true,
  "group": {
    "group_code": "GRP-037CBA6B4B", "status": "active",   // active | partially_cancelled | cancelled
    "property": { "name": "…", "slug": "…" }, "check_in": "…", "check_out": "…", "currency": "ARS",
    "payment_method": "manual", "coupon": { "code": "FAMILIA", "discount": 10000 },
    "totals": { "total": 920000, "deposit_due": 276000, "paid": 0, "balance_due": 920000 },
    "payment_link": null,   // si el alojamiento cobra con MercadoPago y falta pagar: { init_point, preference_id, pay_mode, amount }
                            // pay_mode "deposit" (seña de todo el grupo) si no pagó nada; "balance" (saldo de TODAS las reservas) si ya pagó la seña
    "bookings": [ { "booking_code": "ART…", "room_type_name": "…", "unit_name": "…", "status": "pending",
                    "grand_total": 296774.19, "coupon_share": 3225.81, "amount_paid": 0,
                    "balance_due": 296774.19, "manage_url": "…" }, … ]
  }
}
// 404 GROUP_NOT_FOUND si el código o el token no son válidos.