Skip to main content
GET
/
api
/
cajas
Gestión de Cajas
curl --request GET \
  --url https://api.example.com/api/cajas \
  --header 'Content-Type: application/json' \
  --data '
{
  "saldo_inicial": 123,
  "billetes": [
    {
      "billetes[].id_denominacion": 123,
      "billetes[].cantidad": 123
    }
  ],
  "observaciones": "<string>",
  "tipo": "<string>",
  "monto": 123,
  "motivo": "<string>",
  "referencia": "<string>"
}
'
{
  "404": {},
  "422": {},
  "success": true,
  "data": [
    {
      "id_caja": 123,
      "nombre": "<string>",
      "estado": "<string>",
      "saldo_inicial": 123,
      "saldo_final_esperado": 123,
      "saldo_final_real": 123,
      "diferencia": 123,
      "fecha_apertura": "<string>",
      "fecha_cierre": "<string>",
      "responsable": {},
      "usuarioApertura": {},
      "usuarioCierre": {},
      "metodosPago": [
        {}
      ]
    }
  ]
}

​
Autenticación

Los endpoints de caja requieren autenticación mediante token Bearer y permisos específicos según la operación.

​
Endpoints de Caja

​
Listar Cajas

GET /api/cajas - Requiere permiso caja.view Retorna todas las cajas de la empresa con paginación (15 por página).

​
Respuesta

​
success
boolean
Indica si la operación fue exitosa
​
data
array
Lista paginada de cajas con relaciones cargadas

​
Obtener Caja Activa

GET /api/cajas/activa Retorna la caja actualmente activa para la empresa (solo puede haber una caja activa a la vez). 
{
  "success": true,
  "data": {
    "id_caja": 5,
    "nombre": "Caja Principal",
    "estado": "activa",
    "metodosPago": [
      {
        "id_metodo_pago": 1,
        "nombre": "Efectivo",
        "es_efectivo": true
      }
    ]
  }
}

​
Abrir Caja

POST /api/cajas/{id}/abrir - Requiere permiso caja.abrir Registra la apertura de caja con desglose de billetes y monedas.

​
Parámetros del Body

​
saldo_inicial
decimal
required
Monto total del saldo inicial
​
billetes
array
required
Desglose de billetes y monedas para el arqueo de apertura
​
observaciones
string
Notas u observaciones sobre la apertura

​
Ejemplo de Solicitud

curl -X POST \
  https://tudominio.com/api/cajas/5/abrir \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "saldo_inicial": 500.00,
    "observaciones": "Apertura turno mañana",
    "billetes": [
      {"id_denominacion": 1, "cantidad": 2},
      {"id_denominacion": 2, "cantidad": 3},
      {"id_denominacion": 5, "cantidad": 10}
    ]
  }'

​
Obtener Denominaciones

GET /api/cajas/denominaciones Retorna la lista de denominaciones de billetes y monedas disponibles para el arqueo. 
{
  "success": true,
  "data": [
    {"id_denominacion": 1, "valor": 200.00, "tipo": "billete"},
    {"id_denominacion": 2, "valor": 100.00, "tipo": "billete"},
    {"id_denominacion": 3, "valor": 50.00, "tipo": "billete"},
    {"id_denominacion": 4, "valor": 20.00, "tipo": "billete"},
    {"id_denominacion": 5, "valor": 10.00, "tipo": "billete"},
    {"id_denominacion": 6, "valor": 5.00, "tipo": "moneda"},
    {"id_denominacion": 7, "valor": 2.00, "tipo": "moneda"},
    {"id_denominacion": 8, "valor": 1.00, "tipo": "moneda"},
    {"id_denominacion": 9, "valor": 0.50, "tipo": "moneda"},
    {"id_denominacion": 10, "valor": 0.20, "tipo": "moneda"},
    {"id_denominacion": 11, "valor": 0.10, "tipo": "moneda"}
  ]
}

​
Obtener Resumen de Caja

GET /api/cajas/{id}/resumen - Requiere permiso caja.view Retorna el resumen financiero de la caja incluyendo ventas, movimientos y totales por método de pago. 
{
  "success": true,
  "data": {
    "saldo_inicial": 500.00,
    "total_ventas": 2450.00,
    "total_ingresos": 100.00,
    "total_egresos": 80.00,
    "saldo_esperado": 2970.00,
    "ventas_por_metodo": [
      {"metodo": "Efectivo", "total": 1200.00, "cantidad": 15},
      {"metodo": "Tarjeta", "total": 1250.00, "cantidad": 8}
    ]
  }
}

​
Obtener Ventas por Método de Pago

GET /api/cajas/{id}/ventas-por-metodo - Requiere permiso caja.view Retorna el desglose de ventas agrupadas por método de pago.

​
Obtener Arqueo Diario

GET /api/cajas/{id}/arqueo - Requiere permiso caja.view Retorna el arqueo diario de la caja con el desglose de billetes de apertura y cierre.

​
Registrar Movimiento de Caja

POST /api/cajas/{id}/movimientos - Requiere permiso caja.edit Registra un ingreso o egreso manual en la caja.

​
Parámetros del Body

​
tipo
string
required
Tipo de movimiento: ‘Ingreso’ o ‘Egreso’
​
monto
decimal
required
Monto del movimiento
​
motivo
string
required
Descripción del motivo del movimiento
​
referencia
string
Número de referencia o comprobante

​
Listar Movimientos de Caja

GET /api/cajas/{id}/movimientos - Requiere permiso caja.view Retorna todos los movimientos (ingresos/egresos) de la caja. 
{
  "success": true,
  "data": [
    {
      "id_movimiento": 1,
      "tipo": "Egreso",
      "monto": 50.00,
      "motivo": "Compra de suministros",
      "referencia": "REC-001",
      "fecha": "2024-03-05 10:30:00",
      "usuario": {
        "id": 2,
        "name": "María López"
      }
    }
  ]
}

​
Sistema de Permisos de Caja

Los permisos de caja son por usuario (no por rol):

​
Obtener Permisos de Usuario

GET /api/cajas/permisos/{usuario_id} - Requiere permiso caja.autorizar 
{
  "success": true,
  "data": {
    "id_usuario": 5,
    "puede_abrir_caja": true,
    "puede_cerrar_caja": true,
    "puede_autorizar_cierre": false,
    "puede_rechazar_cierre": false,
    "puede_registrar_movimientos": true,
    "puede_ver_reportes": true
  }
}

​
Actualizar Permisos de Usuario

POST /api/cajas/permisos/{usuario_id} - Requiere permiso caja.autorizar

​
Estados de Caja

La caja puede tener los siguientes estados:
  • activa - Caja habilitada y lista para ser abierta
  • inactiva - Caja deshabilitada (no se puede usar)
  • abierta - Caja en operación, aceptando ventas
  • cerrada - Caja cerrada y validada
  • pendiente_validacion - Cierre registrado, pendiente de autorización

​
Flujo de Operación de Caja

  1. Activar caja - Marcar caja como disponible para uso
  2. Abrir caja - Registrar saldo inicial + desglose de billetes
  3. Procesar ventas - Las ventas se asocian automáticamente a la caja abierta
  4. Registrar movimientos - Ingresos/egresos adicionales
  5. Cerrar caja - Registrar saldo final + desglose de billetes
  6. Autorizar/Rechazar - Supervisor valida el cierre

​
Tablas de Base de Datos

  • cajas - Información principal de cajas
  • movimientos_caja - Ingresos y egresos manuales
  • arqueos_diarios - Registro de arqueos diarios
  • apertura_caja_billetes - Desglose de billetes en apertura
  • cierre_caja_billetes - Desglose de billetes en cierre
  • caja_metodos_pago - Relación caja-métodos de pago
  • permiso_caja - Permisos individuales por usuario

​
Códigos de Error Comunes

​
404
object
Caja no encontrada
{
  "success": false,
  "message": "Caja no encontrada."
}
​
422
object
Estado inválido para la operación
{
  "success": false,
  "message": "La caja no está activa."
}

Build docs developers (and LLMs) love

Get started for freeTalk to us