Estados de asientos y tipos de retención

Seatmap.pro rastrea cada asiento de cada evento mediante un modelo de estados de dos capas. La primera capa es un conjunto cerrado y reducido de estados de ciclo de vida que el motor de reservas usa para la concurrencia y la disponibilidad. La segunda capa es un holdType abierto, definido por organización, que aporta el contexto de negocio: por qué se retiene este asiento, quién puede liberarlo y cómo debe verse en el mapa de asientos.

Las dos capas

Capa	Campo	Valores	Controla
Ciclo de vida	`state`	enum cerrado	concurrencia, disponibilidad
Tipo de retención	`holdType`	cadena abierta	política de liberación, pago, visualización

El motor de reservas solo consulta si un asiento está en ACTIVE para determinar si puede bloquearse. El holdType son metadatos que rigen el flujo de negocio en torno a ese asiento.

Estados de ciclo de vida

Tres estados, fijados por la plataforma.

Estado	Significado	Reservable
`ACTIVE`	Disponible para selección	Sí
`LOCKED`	No disponible; `holdType` dice por qué	No
`SOLD`	Confirmado y completado	No

Un flujo de carrito típico mueve un asiento de ACTIVE → LOCKED → SOLD. Un carrito abandonado lo devuelve de LOCKED → ACTIVE. Un asiento fuera de servicio – dañado, con visibilidad obstruida o retirado de la venta por otro motivo – es simplemente LOCKED con un tipo de retención que registra el motivo: RESERVED lo cubre hoy, y está previsto un valor predeterminado OUT_OF_SERVICE dedicado.

NOTE El enum state de la API también incluye el valor BLOCKED. La plataforma nunca lo establece – ningún asiento se devuelve en ese estado – y se está retirando. Si haces un switch sobre state, trátalo como no disponible.

El estado de cada asiento de un evento está disponible en GET /api/private/v2.0/events/{id}/seats/, junto con su fila, sección y precio. Ese endpoint también admite lectura incremental: envía de vuelta el mayor updatedAt que hayas visto como lastUpdated para recibir solo lo que ha cambiado desde entonces.

Tipos de retención

El holdType es una cadena que asocias a un asiento cuando sale de ACTIVE. Convive junto al estado de ciclo de vida y describe el motivo por el que se retiene el asiento.

Valores predeterminados de la plataforma

Se incluyen dos tipos de retención de fábrica:

Tipo de retención	Estado válido	Liberado por	Pago	Visualización
`CART`	`LOCKED`	cliente, admin, sistema	requerido	In Cart
`RESERVED`	`LOCKED`	admin	no requerido	Reserved

CART es el valor predeterminado del endpoint /lock de reservas v2: omitir holdType en el cuerpo de la solicitud se resuelve como CART.

RESERVED es el tipo de retención para todo lo que un operador retiene fuera de una venta: un asiento apartado para un cliente concreto, o uno fuera de servicio. Solo se libera con una llamada explícita a /unlock.

WARNING El campo ttlSeconds de abajo se acepta y se almacena como parte de la definición del tipo de retención, pero la liberación automática al expirar aún no se aplica. Las retenciones persisten hasta una llamada explícita a /unlock, /sale o /revertsale. No des por hecho que una retención se libere sola.

Definir tus propios tipos de retención

Más allá de los dos valores predeterminados, los tipos de retención los aprovisiona Seatmap.pro para tu organización. Envíanos las definiciones que necesites y las aplicamos a tu organización, o a tu inquilino para que las herede cada organización que dependa de él.

NOTE Hoy no existe un endpoint de autoservicio para definir tipos de retención – escribe a soporte con las definiciones que necesites.

Una definición tiene esta forma:

{
  "holdTypes": {
    "PARTNER_HOLD": {
      "validStates": ["LOCKED"],
      "ttlSeconds": 3600,
      "releaseApi": "ADMIN,API",
      "paymentRequired": true,
      "displayName": "Partner Hold",
      "displayColor": "#8B008B"
    },
    "COMP": {
      "validStates": ["LOCKED", "SOLD"],
      "ttlSeconds": null,
      "releaseApi": "ADMIN",
      "paymentRequired": false,
      "displayName": "Complimentary",
      "displayColor": "#FFD700"
    }
  }
}

Referencia de campos:

Campo	Tipo	Descripción
`validStates`	arreglo de cadenas	Para qué estados de ciclo de vida es válido este tipo de retención. Las solicitudes que combinan un emparejamiento no válido se rechazan.
`ttlSeconds`	entero o null	Ventana de autoliberación prevista en segundos. Se almacena como metadato de configuración; la autoliberación aún no se aplica (ver nota arriba). `null` significa que la retención persiste hasta liberarse explícitamente.
`releaseApi`	cadena	Lista separada por comas de actores autorizados a liberar: `CUSTOMER`, `ADMIN`, `SYSTEM`, `API`.
`paymentRequired`	boolean	Si esta retención debe ir seguida de un pago para convertirse en `SOLD`.
`skipLockedState`	boolean	Cuando es `true`, transita directamente `ACTIVE` → `SOLD` (usado para flujos de taquilla).
`displayName`	cadena	Etiqueta legible mostrada en las interfaces de administración.
`displayColor`	cadena	Color hexadecimal para el estilo del renderizador.
`displayIcon`	cadena	Referencia opcional a una imagen o icono para el renderizador.

Herencia a nivel de inquilino

Si tu organización pertenece a un inquilino, los tipos de retención pueden definirse una sola vez a nivel de inquilino y se aplican a todas sus organizaciones. Las anulaciones por organización tienen prioridad campo por campo, de modo que una organización puede, por ejemplo, anular el displayColor de CART sin reescribir la definición completa.

Orden de resolución para cualquier búsqueda de tipo de retención:

Definición a nivel de organización
Definición a nivel de inquilino
Valores predeterminados de la plataforma

Estas tres capas se combinan. Si solo anulas displayColor a nivel de organización, el resto de la definición se hereda del inquilino o del valor predeterminado de la plataforma.

Uso de tipos de retención en la API de reservas

El payload de bloqueo de reservas v2 acepta un campo opcional holdType:

POST /api/private/v2.0/booking/lock?eventId=123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json

{
  "sessionId": "abc123",
  "seats": [{ "id": 42 }],
  "holdType": "PARTNER_HOLD"
}

Cuando un asiento sale de ACTIVE, el tipo de retención se valida:

Debe estar definido para la organización que realiza la llamada, como valor predeterminado de la plataforma, entrada a nivel de inquilino o entrada a nivel de organización.
Su validStates debe incluir el estado de ciclo de vida de destino.

Los tipos de retención desconocidos o no coincidentes devuelven 400 Bad Request. Los endpoints /unlock y /revertsale no aceptan holdType: devolver un asiento a ACTIVE borra cualquier retención asociada.

Concurrencia

Cada transición de estado afirma el estado actual esperado del asiento como parte del cambio. Dos solicitudes concurrentes que bloquean el mismo asiento no pueden tener éxito ambas: la segunda encuentra que el asiento ya no está en el estado que esperaba, y ese asiento vuelve en la lista de intentos fallidos. La doble reserva queda así descartada sin importar cómo se solapen en el tiempo los flujos de carrito, y sin ninguna coordinación por parte de quien llama.

Registro de auditoría

Cada transición de estado exitosa se registra de forma inmutable, capturando:

Estado de ciclo de vida anterior y nuevo
Tipo de retención en el momento de la transición
ID de sesión (cuando está disponible)
Asiento o grupo de asientos afectado
Marca de tiempo

Este registro respalda los informes de conversión, por ejemplo qué porcentaje de retenciones CART pasó a SOLD en una semana dada. Hoy no se expone como API. Si un historial de transiciones por asiento resultara útil en tus herramientas de administración, escribe a soporte y lo estudiamos.

Integración con el renderizador

El Booking Renderer aplica estilo a los asientos según su estado de ciclo de vida (ACTIVE, LOCKED, SOLD) de fábrica.

Para visualizar valores holdType – o cualquier otra distinción que tu personal necesite – con tus propios colores, animaciones o iconos, el SDK del renderizador proporciona setSeatsState(seats, stateKey) y clearSeatsState(seats), controlados por una configuración declarativa theme.seatStyles.

IMPORTANT El endpoint de asientos devuelve el estado de ciclo de vida state, pero por ahora no devuelve holdType por asiento. Registra en tu lado los tipos de retención que hayas aplicado y asócialos a claves de estado del renderizador al dibujar el mapa. Devolver holdType en el payload del asiento está previsto.

Consulta Estados de asiento personalizados (Renderer SDK) para conocer la API completa, la referencia de tipos y ejemplos resueltos.

Relacionado

Booking Renderer Estados de asiento personalizados (Renderer SDK) – aplicar y estilizar estados de asiento arbitrarios en el navegador.
Booking Renderer Estados y estilo de secciones – el concepto equivalente aplicado a los contornos de sección (resaltado, seleccionado, no disponible, filtrado).
Admin Renderer Admin Renderer – modos de selección y herramientas de personal sobre el mismo modelo de asientos.