Caja

Caja

Prefijo: /api/caja
Requiere Auth: Sí
Permiso requerido: caja, *

Módulo de caja para gestión del dinero en efectivo y electrónico. El flujo típico es: apertura de caja → operaciones (ventas, gastos) → cierre con resumen.

GET /api/caja/

Descripción: Lista los registros de caja con paginación
Requiere Auth: Sí
Permiso requerido: caja, leer

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "base": 500000,
    "cierre": 850000,
    "credito": 100000,
    "efectivo": 700000,
    "gastos": 50000,
    "total": 750000,
    "transferencia": 50000,
    "fecha": "2025-01-15",
    "hora": "18:00:00",
    "usuario": "Juan Pérez",
    "id_jornada": 1,
    "tenant_id": "uuid-tenant"
  }
]

cURL:

curl "http://localhost/api/caja/?skip=0&limit=10" -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/caja/", headers={"Authorization": f"Bearer {token}"})
caja = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/caja/', {
  headers: {'Authorization': `Bearer ${token}`}
});
const caja = await resp.json();

---

GET /api/caja/resumen-cierre

Descripción: Obtiene el resumen de cierre de jornada para un usuario
Requiere Auth: Sí
Permiso requerido: caja, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción
usuario	string	✅	Nombre del usuario

Respuesta exitosa: 200 OK

Response:

{
  "ventas_canal": {
    "local": 450000,
    "electronico": 150000
  },
  "ventas_medio": {
    "efectivo": 400000,
    "transferencia": 100000,
    "credito": 100000
  },
  "creditos_jornada": {
    "monto_total": 200000,
    "abono_inicial": 0
  },
  "abonos": {
    "efectivo": 50000,
    "digital": 30000,
    "total": 80000
  },
  "gastos": 50000,
  "retiros": 0,
  "base_inicial": 500000
}

cURL:

curl "http://localhost/api/caja/resumen-cierre?usuario=Juan%20P%C3%A9rez" -H "Authorization: Bearer <token>"

---

GET /api/caja/base-inicial

Descripción: Obtiene la base inicial de la jornada activa del usuario
Requiere Auth: Sí
Permiso requerido: caja, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción
usuario	string	✅	Nombre del usuario

Respuesta exitosa: 200 OK

Response:

500000

cURL:

curl "http://localhost/api/caja/base-inicial?usuario=Juan%20P%C3%A9rez" -H "Authorization: Bearer <token>"

---

GET /api/caja/gastos

Descripción: Obtiene el total de gastos en un rango de fechas
Requiere Auth: Sí
Permiso requerido: caja, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción
desde	date	✅	Fecha inicial
hasta	date	✅	Fecha final

Respuesta exitosa: 200 OK

Response:

{
  "total": 150000,
  "fecha": "2025-01-01"
}

cURL:

curl "http://localhost/api/caja/gastos?desde=2025-01-01&hasta=2025-01-15" -H "Authorization: Bearer <token>"

---

GET /api/caja/ultimo

Descripción: Obtiene el último ID de caja registrado
Requiere Auth: Sí
Permiso requerido: caja, leer

Respuesta exitosa: 200 OK

Response:

42

cURL:

curl http://localhost/api/caja/ultimo -H "Authorization: Bearer <token>"

---

POST /api/caja/

Descripción: Crea un nuevo registro de caja
Requiere Auth: Sí
Permiso requerido: caja, crear

Respuesta exitosa: 201 Created

cURL:

curl -X POST http://localhost/api/caja/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"base":500000,"usuario":"Juan Pérez"}'

---

POST /api/caja/apertura

Descripción: Registra la apertura de caja para un usuario
Requiere Auth: Sí
Permiso requerido: caja, crear

Request:

{
  "base": 500000,
  "usuario": "Juan Pérez"
}

Respuesta exitosa: 201 Created

Response:

{
  "id_caja": 10,
  "id_jornada": 5,
  "base": 500000,
  "mensaje": "Apertura registrada exitosamente"
}

cURL:

curl -X POST http://localhost/api/caja/apertura \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"base":500000,"usuario":"Juan Pérez"}'

---

GET /api/caja/{caja_id}

Descripción: Obtiene un registro de caja por ID
Requiere Auth: Sí
Permiso requerido: caja, leer

Respuesta exitosa: 200 OK
Errores: 404 (no encontrado)

cURL:

curl http://localhost/api/caja/1 -H "Authorization: Bearer <token>"

---

PUT /api/caja/{caja_id}

Descripción: Actualiza un registro de caja
Requiere Auth: Sí
Permiso requerido: caja, actualizar

Respuesta exitosa: 200 OK
Errores: 404 (no encontrado)

cURL:

curl -X PUT http://localhost/api/caja/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"cierre":900000,"total":850000}'

---

DELETE /api/caja/{caja_id}

Descripción: Elimina un registro de caja
Requiere Auth: Sí
Permiso requerido: caja, eliminar

Respuesta exitosa: 204 No Content
Errores: 404 (no encontrado)

cURL:

curl -X DELETE http://localhost/api/caja/1 -H "Authorization: Bearer <token>"