Aperturar caja
POST /api/cash/open
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Apertura una caja para el usuario (o edita una caja abierta si envías id). Es el endpoint recomendado para iniciar el turno.
Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor).
Formato de respuesta: heredado {success, message?, data?} sin paginación. Ante reglas de negocio puede responder HTTP 200 con success: false: revisa siempre success. Devuelve data.cash_id.
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
beginning_balance |
numeric | Sí | Saldo inicial en soles (efectivo en el cajón al abrir), ≥ 0. |
beginning_balance_usd |
numeric | No | Saldo inicial en dólares, ≥ 0. Si no se envía se conserva el actual (o 0 en una caja nueva). |
user_id |
integer | No | Usuario dueño de la caja. Vacío o 0 = el usuario autenticado. |
reference_number |
string | No | Referencia libre de la caja (p. ej. CAJA-0004, número de turno). |
id |
integer | No | Solo para editar una caja abierta (saldo inicial, referencia o usuario). Omitido o null = apertura. |
Reglas:
- Apertura: si el usuario ya tiene una caja abierta no se crea otra ni se modifica: responde
success: truecon el id de la caja abierta y el mensaje La caja ya se encontraba aperturada. - La fecha y hora de apertura las fija el servidor; el saldo inicial se registra como el primer movimiento de efectivo de la caja.
- Edición (
id): solo cajas abiertas; no se puede asignar la caja a un usuario que ya tiene otra abierta.
Errores:
422{success: false, message: {campo: [errores]}}si falla la validación de campos. (p. ej.beginning_balancenegativo).200consuccess: falseymessagesi la caja a editar no existe, está cerrada o el usuario destino ya tiene una caja abierta.
Cuerpo
Content-Type: application/json
{
"beginning_balance": 100.0,
"beginning_balance_usd": 0,
"user_id": null,
"reference_number": "CAJA-0004",
"id": null
}
Respuestas
200 — Caja aperturada
{
"success": true,
"message": "Caja aperturada con éxito",
"data": {
"cash_id": 4
}
}
200 — Ya tenía caja abierta
{
"success": true,
"message": "La caja ya se encontraba aperturada.",
"data": {
"cash_id": 4
}
}
422 — Saldo inválido
{
"success": false,
"message": {
"beginning_balance": [
"El campo beginning balance es obligatorio."
]
}
}
200 — Caja cerrada (edición)
{
"success": false,
"message": "La caja está cerrada y su arqueo no puede cambiar. Si hubo un error, corrígelo en la caja abierta."
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.