Saltar al contenido
Facturador

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: true con 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_balance negativo).
  • 200 con success: false y message si 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.