POST/api/mod/productos/{espacio}/inventory/reservations

Reserva stock

Aparta unidades de una variante por un tiempo, mientras tu cliente paga. Lo reservado no se puede vender a otro; si vence el plazo, vuelve solo.

PARÁMETROS

CAMPO	TIPO	REQUERIDO	QUÉ ES
espacio	string	SÍ	El id del espacio (sale en GET /api/companies). Tiene que tener el módulo Productos.

CAMPO	TIPO	REQUERIDO	QUÉ ES
variant_id	string	SÍ	La variante.
cantidad	number \| string	no	Cuántas. Por defecto 1.
ttl_s	integer	no	Cuántos segundos dura. Por defecto 900 (15 minutos).
bodega	string	no	Por defecto, la única.
session_id · sale_ref	string	no	Tus referencias: el carrito y el pedido.

La reserva, activa.

CAMPO	TIPO	QUÉ ES
id · variant_id · bodega	string	La reserva y qué retiene.
cantidad	string	Lo retenido.
estado	string	Ver estados.
session_id · sale_ref	string \| null	Los que diste.
expires_at · created_at	number	Cuándo vence y cuándo se creó, en segundos desde 1970.
released_at	number \| null	Cuándo dejó de retener. null mientras está activa.

CAMPO	TIPO	QUÉ ES
activa	retiene	Descuenta de lo disponible hasta expires_at.
liberada	terminada	La liberaste: el stock vuelve.
consumida	terminada	Se convirtió en venta (venta con su reservation_id).
expirada	terminada	Venció su plazo: el stock vuelve solo.

STATUS	CUÁNDO	DETAIL LITERAL
403	El espacio no tiene el módulo Productos	módulo no habilitado para este espacio.
403	La clave es de solo lectura	Tu cuenta es de solo lectura en este espacio.
409	No alcanza lo disponible, la variante no tiene stock cargado o la cantidad no es mayor que 0	sin disponibilidad suficiente para reservar.
422	Falta un campo obligatorio o uno no es de su tipo (detail es una lista)	—

Y los de cualquier ruta —clave inválida, cuenta no al día, IP, límites—, en Errores, límites y créditos.

Al confirmar la venta, pasa el id como reservation_id de la línea en Confirma una venta: la reserva se consume y no se descuenta dos veces.
Si tu cliente abandona, libérala sin esperar al plazo.