Requerimientos Backend: Módulo Caja Chica
Documento de especificación técnica para la implementación del API y
Base de Datos del módulo de Caja Chica (Petty Cash).
Diagrama de Flujo del Proceso
graph TD A["Inicio: Crear Caja"] -->|Definir Límite y Custodio|
B("Caja Activa") B --> C{"Acción"} C -->|"Registrar Gasto"| D{"Validar
Saldo"} D -- "Insuficiente" --> E["Error: Fondos Insuficientes"] D --
"Suficiente" --> F["Validar Fiscal NCF/RNC"] F --> G["Registrar
Transacción - EXPENSE"] G -->|"Resta del Balance"| B C -->|"Solicitar
Reposición"| H["Seleccionar Gastos"] H --> I["Agrupar Transacciones"]
I --> J["Generar Solicitud de Pago"] J -->|"Integración CXP"|
K["Aprobación Financiera"] K -->|"Reembolso"| L["Registrar Transacción
- REPLENISHMENT"] L -->|"Suma al Balance"| B
1. Base de Datos (Modelos)
A. PettyCashFund (La Caja)
| Campo |
Tipo |
Descripción |
id |
PK |
Identificador único |
name |
string |
Nombre de la caja (ej. Caja Recepción) |
description |
string |
Detalles adicionales (opcional). |
amountLimit |
decimal |
Monto fijo máximo (Fondo Fijo) |
currentBalance |
decimal |
Saldo disponible actual |
custodianId |
FK |
Usuario responsable |
currency |
string |
Moneda (DOP, USD). Default: DOP. |
isActive |
boolean |
Estado de la caja |
companyId |
FK |
Empresa a la que pertenece. |
B. PettyCashTransaction (Movimientos)
| Campo |
Tipo |
Descripción |
id |
PK |
Identificador único |
fundId |
FK |
Caja asociada |
type |
enum |
EXPENSE, REPLENISHMENT, ADJUSTMENT |
amount |
decimal |
Monto del movimiento |
date |
datetime |
Fecha de registro |
concept |
string |
Descripción del gasto |
receiptImg |
string |
URL de la foto del recibo/factura |
status |
enum |
PENDING, APPROVED, REJECTED, REIMBURSED |
ncfType |
string |
Tipo de NCF (e.g. "B01", "B13") (Opcional) |
ncf |
string |
Número de Comprobante Fiscal (Opcional) |
rnc |
string |
RNC del proveedor (Opcional) |
supplierName |
string |
Nombre del proveedor |
2. Endpoints API
Gestión de Fondos
-
GET
/api/petty-cash/funds - Listar cajas
-
POST
/api/petty-cash/funds - Crear caja
-
PUT
/api/petty-cash/funds/{id} - Editar caja
Transacciones
-
POST
/api/petty-cash/funds/{id}/expense - Registrar Gasto
Payload:
{ amount, concept, date, rnc, ncf, supplierName, receiptImg,
ncfType }
Validación: El monto no puede exceder el
currentBalance.
-
GET
/api/petty-cash/funds/{id}/transactions - Historial
Reposición
-
POST
/api/petty-cash/replenishment - Solicitar Reembolso
Agrupa gastos no reembolsados y genera una cuenta por pagar al
custodio o proveedor genérico.
3. Lógica Crítica
-
Atomicidad: El registro de un gasto y la
actualización del balance deben ser atómicos.
-
Validación Fiscal: Si se provee RNC, validar formato
(1.0). Si se provee NCF, validar longitud y prefijo (B01, B02, etc).
-
Seguridad: Solo el custodio asignado puede registrar
gastos en su caja.