Documentación del Módulo de Finanzas

Versión: 1.1 Fecha: 2026-01-12

1. Resumen Ejecutivo

El módulo de Finanzas es el núcleo contable y financiero del ERP. Su propósito es gestionar de manera integral el ciclo de vida de las transacciones comerciales, desde la emisión de comprobantes hasta el cierre contable, garantizando la integridad de datos, el cumplimiento tributario (SUNAT/Perú) y la trazabilidad completa de operaciones.

Valor para el Negocio:

Control Financiero Integral: Gestión unificada de ventas, compras, pagos, cobros y contabilidad.
Cumplimiento Tributario: Generación de Libros Electrónicos (PLE) según normativa SUNAT, retenciones/percepciones, IGV, detracciones y manejo multimoneda.
Integridad Contable: Asientos contables automáticos balanceados, control de períodos cerrados y trazabilidad polimórfica de documentos fuente.
Visibilidad de Tesorería: Control de cuentas bancarias, conciliación bancaria, caja chica y flujo de efectivo.
Gestión de Activos: Control de activos fijos, depreciación automática y valorización.

2. Flujo del Proceso

El módulo opera bajo macro-procesos principales interconectados.

2.1. Ciclo de Facturación (Ventas)

graph TD A[Crear Factura/Boleta] -->|Guardar| B(Estado: BORRADOR) B -->|Emitir| C(Estado: EMITIDO) C -->|Generar Asiento| D{Asiento Contable} D --> E[Libro de Ventas] C -->|Cobrar Parcial| F(PARCIALMENTE_PAGADO) C -->|Cobrar Total| G(Estado: PAGADO) F -->|Completar Cobro| G C -->|Vence Plazo| H(Estado: VENCIDO) H -->|Cobrar| G B -->|Anular| I(Estado: ANULADO) C -->|Anular| I F -->|Revertir Pagos + Anular| I subgraph Notas[Notas de Crédito/Débito] C -.->|NC/ND| J[Nota Referenciada] end

2.2. Ciclo de Compras

graph TD A[Registrar Factura Proveedor] -->|Guardar| B(Estado: BORRADOR) B -->|Aprobar| C(Estado: APROBADO) C -->|Generar Asiento| D{Crédito Fiscal} D --> E[Libro de Compras] C -->|Pagar Parcial| F(PARCIALMENTE_PAGADO) C -->|Pagar Total| G(Estado: PAGADO) F -->|Completar Pago| G B -->|Anular| H(Estado: ANULADO) subgraph Validaciones[Validaciones SUNAT] A -.->|Validar| V1[Número Único] A -.->|Validar| V2[RUC Válido] end

2.3. Ciclo de Pagos/Cobros

stateDiagram-v2 [*] --> BORRADOR BORRADOR --> CONTABILIZADO: Contabilizar BORRADOR --> ANULADO: Anular CONTABILIZADO --> ANULADO: Anular (Extorno Automático) ANULADO --> [*] state CONTABILIZADO { [*] --> GenerarAsiento GenerarAsiento --> ActualizarSaldos ActualizarSaldos --> [*] } note right of CONTABILIZADO Genera asiento contable y actualiza saldos de facturas end note

2.4. Ciclo de Asientos Contables

graph LR A[Crear Asiento] --> B(BORRADOR) B -->|Validar Balance| C{¿Cuadrado?} C -->|No| B C -->|Sí| D[Contabilizar] D --> E(CONTABILIZADO) E -->|Crear Extorno| F[Asiento Reversión] F --> G[Líneas Invertidas D↔H] E -->|Anular| H(ANULADO) B -->|Eliminar| I((Eliminado))

3. Lógica de Negocio y Reglas

3.1. Reglas de Facturación (Ventas)

Regla	Descripción	Implementación
Unicidad de Número	Serie + Correlativo debe ser único por tipo de documento.	`getNextCorrelative()`
Validación de Período	No se pueden crear/editar documentos en períodos contables cerrados.	`validateBusinessRules()` → `is_in_closed_period`
Inmutabilidad	Solo facturas en estado `BORRADOR` pueden editarse o eliminarse.	`canBeEdited()`, `canBeDeleted()`
Notas de Crédito	Solo pueden emitirse sobre facturas `EMITIDO`, `PAGADO`, o `PARCIALMENTE_PAGADO`.	`canCreateCreditNote()`
Correlativo Automático	El sistema genera el siguiente correlativo disponible por serie.	Auto en `creating` boot
Detracción	Facturas pueden tener `has_detraccion`, código, número, fecha y monto.	Campos en modelo
Tipo de Cambio	Obligatorio para monedas extranjeras (USD, EUR).	`validateExchangeRate()`
Cliente según Documento	Facturas (01) solo para RUC, Boletas (03) para DNI/otros.	`scopeFacturaCustomers()`, `scopeBoletaCustomers()`

3.2. Reglas de Compras

Regla	Descripción
Número Único Proveedor	Combinación `tipo_doc + serie + correlativo + partner_id` debe ser única.
Validación Cruzada	`validateUniqueInvoiceNumber()` antes de guardar.
Aprobación Requerida	Las compras pasan de `BORRADOR` → `APROBADO` antes de generar asiento.
Recálculo Totales	`recalculateTotals()` recalcula subtotal, IGV y total desde líneas.

3.3. Reglas de Pagos/Cobros

Regla	Descripción	Método de Validación
Tipo Coherente	`INBOUND` (Cobro) = Clientes, `OUTBOUND` (Pago) = Proveedores.	`validatePartner()`
Cuenta Bancaria	Obligatoria para métodos: Transferencia, Cheque, Depósito.	`validateBankAccount()`
Cuenta Activa	La cuenta bancaria seleccionada debe tener `is_active = true`.	`validateBankAccount()`
Tipo de Cambio	Obligatorio para transacciones en moneda extranjera (USD, EUR).	`validateExchangeRate()`
Monto Positivo	El monto del pago debe ser mayor a cero.	`validateAmount()`
Período Cerrado	No se pueden registrar pagos en períodos contables cerrados.	`validateClosedPeriod()`
Transición de Estado	Valida que los cambios de estado sean permitidos.	`validateStatusTransition()`
Asignación Completa	Para contabilizar, `total_allocated = amount` (tolerancia 0.01).	`canBePosted()`
Anulación con Extorno	Al anular un pago `CONTABILIZADO`, se anula su asiento y se revierten saldos.	`cancel()` → `revertInvoiceBalances()`

3.4. Reglas Contables (Asientos)

Regla	Descripción	Método
Balance Obligatorio	Σ Débitos = Σ Créditos (tolerancia < 0.01).	`is_balanced`, `validateBalance()`
Cuentas Postables	Solo cuentas con `is_postable = true` aceptan movimientos.	Validación en líneas
Cuenta Padre	El tipo de cuenta debe coincidir con su cuenta padre.	`validateBusinessRules()`
Centro de Costos	Obligatorio si la cuenta tiene `requires_cost_center = true`.	Validación en líneas
Socio de Negocio	Obligatorio si la cuenta tiene `requires_partner = true`.	Validación en líneas
Período Cerrado	No se permiten asientos en fechas de períodos cerrados.	`validateEntryDate()`
Límite de Antigüedad	Configurable: máximo X días en el pasado.	`days_limit_past_entries`
Extorno	Solo asientos `CONTABILIZADO` pueden generar extorno.	`canBeReversed()`
Extorno Único	Un asiento solo puede ser extornado una vez.	`hasBeenReversed()`

3.5. Métodos de Pago

Método	Cuenta Bancaria	Documento	Inmediato
Efectivo	❌	❌	✅
Transferencia	✅	❌	❌
Cheque	✅	✅	❌
Tarjeta	❌	❌	✅
Depósito	✅	✅	❌

3.6. Cálculos Automáticos

// Saldo de factura
$balance = $invoice->total - $invoice->paid_amount;

// Monto pagado (excluyendo pagos anulados)
$paid_amount = $payments->where('status', '!=', 'anulado')->sum('amount');

// Balance de cuenta contable (según naturaleza)
$balance = $nature === 'deudor'
    ? ($debits - $credits)
    : ($credits - $debits);

// Total en moneda funcional
$functional_total = $total * $exchange_rate;

// Días vencido
$days_overdue = DATEDIFF(today, due_date);

4. Modelo de Datos Detallado

4.1. Entidades Principales

Entidad	Descripción	Atributos Clave
SalesInvoice	Comprobantes de venta (Facturas/Boletas/NC/ND).	`series`, `correlative`, `issue_date`, `due_date`, `status`, `total`, `currency`, `igv_amount`, `has_detraccion`, `note_type`, `original_invoice_id`
SalesInvoiceLine	Líneas de detalle de factura venta.	`product_id`, `description`, `quantity`, `unit_price`, `igv`, `subtotal`
PurchaseInvoice	Comprobantes de compra (Facturas proveedores).	`series`, `correlative`, `issue_date`, `status`, `total`, `igv`, `document_type_code`
PurchaseInvoiceLine	Líneas de detalle de factura compra.	Similar a SalesInvoiceLine
Payment	Pagos y cobros.	`type` (INBOUND/OUTBOUND), `amount`, `status`, `payment_method`, `payment_date`, `operation_number`, `company_bank_account_id`
PaymentAllocation	Asignación pago-documento.	`payment_id`, `payable_type`, `payable_id`, `amount`
JournalEntry	Asientos contables.	`entry_date`, `entry_type`, `status`, `description`, `currency`, `exchange_rate`, `source_document_type/id`, `reversal_of_id`, `reversed_by_id`
JournalEntryLines	Líneas de asiento.	`account_id`, `debit`, `credit`, `debit_functional`, `credit_functional`, `partner_id`, `cost_center_id`
ChartOfAccount	Plan de cuentas jerárquico.	`code`, `name`, `type`, `nature`, `level`, `is_postable`, `parent_id`, `requires_cost_center`, `requires_partner`
Partner	Socios de negocio (Clientes/Proveedores).	`document_type_id`, `document_number`, `legal_name`, `is_customer`, `is_supplier`, `is_retention_agent`, `default_receivable_account_id`, `default_payable_account_id`
CompanyBankAccount	Cuentas bancarias de la empresa.	`bank_id`, `account_number`, `cci`, `currency`, `chart_of_account_id`, `is_active`
Bank	Catálogo de bancos.	`code`, `name`, `swift_code`
BankStatement	Estados de cuenta bancarios.	`company_bank_account_id`, `period_start/end`, `initial_balance`, `final_balance`, `calculated_balance`, `difference`, `status`
BankStatementLine	Movimientos del estado de cuenta.	`bank_statement_id`, `date`, `description`, `debit`, `credit`, `is_reconciled`
PettyCash	Cajas chicas.	`name`, `fixed_fund`, `current_balance`, `min_balance_alert`, `responsible_id`, `chart_of_account_id`, `status`
PettyCashMovement	Movimientos de caja chica.	`petty_cash_id`, `type`, `amount`, `description`, `document_number`
Retention	Comprobantes de retención.	`series`, `correlative`, `issue_date`, `rate`, `total_amount`, `partner_id`
RetentionLine	Detalle de documentos retenidos.	`purchase_invoice_id`, `base_amount`, `retention_amount`
FixedAsset	Activos fijos.	`code`, `name`, `purchase_cost`, `residual_value`, `accumulated_depreciation`, `status`, `category_id`
FixedAssetCategory	Categorías de activos.	`name`, `depreciation_method`, `useful_life_years`
AssetDepreciation	Registro de depreciaciones.	`fixed_asset_id`, `period`, `amount`, `journal_entry_id`
PleLog	Log de generación de Libros Electrónicos.	`book_type`, `period`, `file_path`, `status`, `generated_at`
CostCenter	Centros de costo.	`code`, `name`, `is_active`
AccountingConfiguration	Configuración contable por período.	Ver sección 7.1
SunatDocumentType	Tipos de documento SUNAT.	`code`, `name` (01=Factura, 03=Boleta, 07=NC, 08=ND)

4.2. Estados Posibles (Status Codes)

InvoiceStatus (Facturas)

Estado	Código	Descripción	Editar	Eliminar	Pagar	Anular	Generar Asiento
Borrador	`borrador`	En elaboración	✅	✅	❌	✅	❌
Emitido	`emitido`	Factura emitida	❌	❌	✅	✅	✅
Aprobado	`aprobado`	Aprobado (solo compras)	❌	❌	✅	✅	✅
Pagado	`pagado`	Totalmente pagada	❌	❌	❌	❌	✅
Parcialmente Pagado	`parcialmente_pagado`	Pago parcial	❌	❌	✅	✅*	✅
Vencido	`vencido`	Fecha expirada	❌	❌	✅	❌	❌
Anulado	`anulado`	Documento anulado	❌	❌	❌	❌	❌

*Requiere revertir pagos previamente.

PaymentStatus (Pagos)

Estado	Código	Editar	Eliminar	Contabilizar	Anular
Borrador	`borrador`	✅	✅	✅	✅
Contabilizado	`contabilizado`	❌	❌	❌	✅
Anulado	`anulado`	❌	❌	❌	❌

JournalEntryStatus (Asientos)

Estado	Código	Editar	Eliminar	Contabilizar	Anular	Extornar
Borrador	`borrador`	✅	✅	✅	✅	❌
Contabilizado	`contabilizado`	❌	❌	❌	✅	✅
Anulado	`anulado`	❌	❌	❌	❌	❌

JournalEntryType (Tipos de Asiento)

Tipo	Código	Creación	Uso
Apertura	`apertura`	Automático	Inicio ejercicio fiscal
Manual	`manual`	Manual	Ajustes manuales del contador
Ventas	`ventas`	Automático	Desde facturas de venta
Compras	`compras`	Automático	Desde facturas de compra
Nómina	`nómina`	Automático	Desde PayrollRun
Depreciación	`depreciación`	Automático	Proceso mensual de activos
Cierre	`cierre`	Automático	Cierre de ejercicio
Ajuste	`ajuste`	Manual	Correcciones y extornos
Provisión	`provisión`	Manual	Provisiones de gastos
Diferencia Cambio	`diferencia_cambio`	Automático	Ajuste cambiario
Transferencia	`transferencia`	Automático	Movimientos entre cuentas

AccountType (Tipos de Cuenta)

Tipo	Código	Naturaleza	Reporte	Aumenta con
Activo	`activo`	Deudor	Balance General	Débito
Pasivo	`pasivo`	Acreedor	Balance General	Crédito
Patrimonio	`patrimonio`	Acreedor	Balance General	Crédito
Ingreso	`ingreso`	Acreedor	Estado Resultados	Crédito
Gasto	`gasto`	Deudor	Estado Resultados	Débito
Costo de Ventas	`costo_de_ventas`	Deudor	Estado Resultados	Débito

4.3. Diagrama de Relaciones

erDiagram Partner ||--o{ SalesInvoice : "cliente" Partner ||--o{ PurchaseInvoice : "proveedor" Partner ||--o{ Payment : "socio" Partner ||--o{ JournalEntryLines : "auxiliar" SalesInvoice ||--o{ SalesInvoiceLine : "líneas" SalesInvoice ||--o| JournalEntry : "asiento" SalesInvoice }o--o{ Payment : "pagos (morph)" SalesInvoice ||--o{ SalesInvoice : "notas NC/ND" PurchaseInvoice ||--o{ PurchaseInvoiceLine : "líneas" PurchaseInvoice ||--o| JournalEntry : "asiento" PurchaseInvoice }o--o{ Payment : "pagos (morph)" Payment ||--o| JournalEntry : "asiento" Payment ||--o| CompanyBankAccount : "cuenta" Payment ||--o{ PaymentAllocation : "asignaciones" JournalEntry ||--o{ JournalEntryLines : "líneas" JournalEntry ||--o| JournalEntry : "extorno" JournalEntryLines }o--|| ChartOfAccount : "cuenta" JournalEntryLines }o--o| CostCenter : "centro costo" ChartOfAccount ||--o{ ChartOfAccount : "subcuentas" CompanyBankAccount }o--|| Bank : "banco" CompanyBankAccount ||--o| ChartOfAccount : "cuenta contable" BankStatement ||--o{ BankStatementLine : "movimientos" BankStatement }o--|| CompanyBankAccount : "cuenta" PettyCash ||--o{ PettyCashMovement : "movimientos" PettyCash }o--|| ChartOfAccount : "cuenta" FixedAsset ||--o{ AssetDepreciation : "depreciaciones" FixedAsset }o--|| FixedAssetCategory : "categoría" AssetDepreciation ||--o| JournalEntry : "asiento" Retention ||--o{ RetentionLine : "líneas" RetentionLine }o--|| PurchaseInvoice : "doc retenido"

5. Interdependencias

5.1. Módulos Afectados por Finanzas

Módulo	Relación	Impacto
Recursos Humanos	Nómina → Finanzas	Cada `PayrollRun` procesado genera asiento contable tipo `nómina`. Usa cuentas configuradas en `AccountingConfiguration`: gastos planilla, EsSalud, ONP, AFP, 5ta categoría, CTS, gratificaciones, vacaciones.
Inventario	Compras ↔ Stock	Las facturas de compra pueden estar vinculadas a `StockMove` de ingresos. El costo de productos afecta el costo de ventas.
Logística	Pre-facturación → Ventas	Los servicios de courier completados pasan a `PrefacturingQueue` para generar `SalesInvoice` automáticas.
Configuración	Usuarios/Roles → Finanzas	Permisos granulares por recurso y acción via `ModelPermissionPolicy`.

5.2. Flujos de Integración

flowchart LR subgraph RRHH["Recursos Humanos"] PR[PayrollRun] end subgraph Finanzas["Finanzas"] JE[JournalEntry] SI[SalesInvoice] PI[PurchaseInvoice] PAY[Payment] COA[ChartOfAccount] end subgraph Inventario["Inventario"] SM[StockMove] PROD[Product] end subgraph Logística["Logística"] PQ[PrefacturingQueue] end PR -->|"Genera Asiento (nómina)"| JE PI -->|"Ingreso Stock"| SM SI ---|"Egreso Stock"| SM PQ -->|"Genera Factura"| SI PAY -->|"Genera Asiento"| JE SI -->|"Genera Asiento (ventas)"| JE PI -->|"Genera Asiento (compras)"| JE JE -->|"Afecta"| COA PROD -.->|"Costo"| JE

6. Casos de Uso Principales

CU-01: Emisión de Factura de Venta

Actor: Facturador

Precondiciones: Cliente registrado con RUC válido.

Camino Feliz:

Usuario crea comprobante seleccionando tipo (01=Factura) y cliente.
Selecciona sucursal y moneda (PEN/USD/EUR).
Agrega líneas con productos/servicios, cantidad y precio.
Sistema calcula automáticamente subtotal, IGV (18%) y total.
Si aplica detracción, marca checkbox y completa datos (código, número, monto).
Usuario guarda en estado BORRADOR.
Revisa y presiona "Emitir".
Sistema valida: período abierto, cliente válido, líneas completas.
Genera correlativo automático con formato SERIE-00000001.
Cambia estado a EMITIDO.
(Opcional) Genera asiento contable automático:
- Débito: Cuentas por Cobrar (12)
- Crédito: Ingresos (70) + IGV por Pagar (40)

Excepciones:

Cliente sin RUC: Cambiar a Boleta (03) o corregir datos del cliente.
Período cerrado: Sistema bloquea con mensaje "La fecha de emisión corresponde a un período contable cerrado."
Falta configuración: "No existe configuración contable para la fecha de emisión."

CU-02: Registro de Factura de Compra

Actor: Contador / Compras

Precondiciones: Proveedor registrado con RUC.

Camino Feliz:

Usuario registra datos del comprobante recibido: tipo doc, serie, número, fecha.
Sistema valida que no exista duplicado (mismo proveedor + serie + número).
Ingresa líneas con detalle de gastos/inventario.
Sistema recalcula totales.
Guarda en BORRADOR, luego aprueba a APROBADO.
Genera asiento contable:
- Débito: Gastos (6x) o Inventario (20)
- Débito: Crédito Fiscal - IGV (40)
- Crédito: Cuentas por Pagar (42)

Excepciones:

Número duplicado: "Ya existe una factura con este número para este proveedor."
RUC inválido: Validación contra catálogo SUNAT.

CU-03: Registro de Pago/Cobro

Actor: Tesorero

Camino Feliz:

Usuario crea pago indicando tipo (Cobro/Pago), socio y monto.
Selecciona método de pago y cuenta bancaria (si aplica).
Ingresa número de operación y fecha.
En la sección de asignación, selecciona facturas pendientes.
Distribuye el monto entre las facturas (puede pagar múltiples).
Valida que total_allocated = amount.
Presiona "Contabilizar".
Sistema genera asiento contable:
- Cobro (INBOUND): Débito Banco, Crédito Cuentas por Cobrar
- Pago (OUTBOUND): Débito Cuentas por Pagar, Crédito Banco
Actualiza estado de facturas según saldo restante.

Excepciones:

Tipo de cambio faltante: "El tipo de cambio es obligatorio para moneda Dólares (USD)."
Cuenta bancaria inactiva: "La cuenta bancaria seleccionada no está activa."
Socio incorrecto: "Para un cobro, debe seleccionar un cliente."

CU-04: Conciliación Bancaria

Actor: Contador

Camino Feliz:

Usuario crea nuevo Estado de Cuenta seleccionando cuenta bancaria y período.
Ingresa saldo inicial y saldo final según extracto del banco.
Carga movimientos (manual o importación CSV).
Por cada línea, marca como "Conciliada" al encontrar el pago/cobro correspondiente.
Sistema calcula: saldo_calculado = inicial + créditos - débitos.
Cuando diferencia = saldo_final - saldo_calculado ≈ 0 y todas las líneas conciliadas:
Usuario marca como CONCILIADO.

Excepciones:

Diferencia no cuadra: Usuario debe investigar partidas en tránsito o errores.
Período cerrado: No permite crear estados de cuenta que intersecten períodos cerrados.

CU-05: Gestión de Caja Chica

Actor: Responsable de Caja

Camino Feliz:

Caja chica configurada con fondo fijo y responsable.
Usuario registra egreso por gasto menor (taxi, útiles, etc.).
Sistema valida saldo suficiente y estado ACTIVA.
Actualiza current_balance.
Cuando current_balance < min_balance_alert, sistema alerta.
Usuario registra reposición de fondos hasta el fondo fijo.

Excepciones:

Saldo insuficiente: "El saldo actual es insuficiente para este egreso."
Caja suspendida: "La caja chica está suspendida. No permite movimientos."

CU-06: Cierre de Período Contable

Actor: Contador / Gerente

Camino Feliz:

Usuario verifica que todos los documentos del período estén contabilizados.
Genera Libros Electrónicos (PLE) del período:
- 5.1 Libro Diario
- 6.1 Libro Mayor
- 8.1 Registro de Compras
- 14.1 Registro de Ventas
Revisa y corrige diferencias detectadas.
En AccountingConfiguration, marca is_closed = true.
Sistema bloquea nuevas operaciones en fechas del período.

Excepciones:

Asientos sin contabilizar: Lista los asientos en estado BORRADOR.
Facturas en borrador: Debe emitir o anular antes de cerrar.

CU-07: Emisión de Notas de Crédito/Débito

Actor: Facturador

Precondiciones: Factura original en estado EMITIDO, PAGADO, o PARCIALMENTE_PAGADO.

Camino Feliz:

Desde la factura original, usuario selecciona "Crear Nota de Crédito" o "Crear Nota de Débito".
Sistema crea documento con referencia a original_invoice_id y note_type.
Usuario completa motivo (note_reason) y detalle.
Sistema genera correlativo con serie de NC (07) o ND (08).
Emite la nota, generando asiento inverso o complementario.

Excepciones:

Factura anulada: "No se pueden crear notas sobre facturas anuladas."
Ya es una nota: "No se pueden crear notas sobre otras notas."

CU-08: Extorno de Asiento Contable

Actor: Contador

Precondiciones: Asiento en estado CONTABILIZADO.

Camino Feliz:

Usuario selecciona asiento y presiona "Crear Extorno".
Sistema valida que no haya sido extornado previamente.
Crea nuevo asiento tipo AJUSTE con reversal_of_id apuntando al original.
Copia todas las líneas invirtiendo Débito ↔ Crédito.
Marca original con reversed_by_id.
Usuario revisa y contabiliza el extorno.

Excepciones:

Ya extornado: "Este asiento ya ha sido extornado."
Estado incorrecto: "Solo se pueden extornar asientos contabilizados."

7. Guía de Configuración

7.1. Configuración Contable (`AccountingConfiguration`)

Define parámetros globales por período fiscal. Campos principales:

Campo	Descripción
`start_date`, `end_date`	Rango del período fiscal
`is_closed`	Bloquea operaciones en el período
`functional_currency`	Moneda funcional (PEN)
`presentation_currency`	Moneda de presentación
`block_past_entries`	Limitar asientos antiguos
`days_limit_past_entries`	Días máximos en el pasado

Cuentas de Ventas:

sales_receivables_account_id → Cuentas por Cobrar (12)
sales_income_account_id → Ingresos (70)
sales_tax_account_id → IGV por Pagar (40)

Cuentas de Compras:

purchase_payables_account_id → Cuentas por Pagar (42)
purchase_expense_account_id → Gastos (6x)
purchase_tax_credit_account_id → Crédito Fiscal (40)

Cuentas de Nómina (integración con RRHH):

payroll_expense_account_id / payroll_payable_account_id
essalud_expense_account_id / essalud_payable_account_id
onp_payable_account_id / afp_payable_account_id
income_tax_5th_payable_account_id
cts_provision_account_id / cts_expense_account_id
gratification_provision_account_id / gratification_expense_account_id
vacation_provision_account_id / vacation_expense_account_id

Series de Comprobantes:

factura_series → Serie para Facturas (F001)
boleta_series → Serie para Boletas (B001)

7.2. Plan de Cuentas (`ChartOfAccount`)

Estructura jerárquica según PCGE (Plan Contable General Empresarial):

Nivel	Ejemplo	Postable	Descripción
1	10	❌	Efectivo y Equivalentes (clase)
2	101	❌	Caja (subcuenta)
3	10101	✅	Caja MN (analítica)

Configuración por cuenta:

is_postable: ¿Acepta movimientos directos?
requires_cost_center: ¿Obliga centro de costo?
requires_partner: ¿Obliga socio de negocio (auxiliar)?
is_cash_flow: ¿Aparece en flujo de efectivo?
is_taxable: ¿Afecta cálculos tributarios?

7.3. Socios de Negocio (`Partner`)

Configurar campos clave:

Tipo de documento: IdentityDocument (6=RUC, 1=DNI, etc.)
Roles: is_customer, is_supplier, is_employee, is_other
Cuentas por defecto: Define cuenta por cobrar y por pagar
Agentes tributarios: is_retention_agent, is_perception_agent

7.4. Monedas Soportadas

Moneda	Código	Símbolo	Funcional	Requiere TC
Soles	PEN	S/	✅	❌
Dólares	USD	$	❌	✅
Euros	EUR	€	❌	✅

8. Widgets del Dashboard Financiero

El módulo incluye 4 widgets especializados para monitoreo en tiempo real:

8.1. AccountsOverviewWidget

Descripción: Resumen de cuentas principales (activos, pasivos, patrimonio). Datos: Saldos calculados desde JournalEntryLines de asientos CONTABILIZADO.

8.2. BankBalancesWidget

Descripción: Saldos actuales de todas las cuentas bancarias activas. Datos: Balance por cuenta desde CompanyBankAccount.

8.3. OverdueInvoicesWidget

Descripción: Tabla de facturas vencidas (CXC y CXP) con días de mora. Datos: Union de SalesInvoice y PurchaseInvoice donde due_date < today. Columnas: Tipo, Comprobante, Cliente/Proveedor, Vencimiento, Días Vencido, Monto. Colores: ≤30 días (warning), ≤60 días (orange), >60 días (danger).

8.4. RevenueExpenseChartWidget

Descripción: Gráfico de barras comparando ingresos vs gastos de los últimos 6 meses. Datos: Suma de movimientos en cuentas tipo INGRESO vs GASTO desde JournalEntryLines. Formato: Monto en S/ con formato de miles.

9. Matriz de Roles y Permisos (RBAC)

Recurso	Super-Admin	Contador	Tesorero	Facturador	Consulta
Facturas Venta	Total	Ver	Ver	CRUD + Emitir	Ver
Facturas Compra	Total	Total	Ver	-	Ver
Pagos/Cobros	Total	Ver	Total	-	Ver
Asientos Contables	Total	Total	Ver	-	Ver
Plan de Cuentas	Total	CRUD	Ver	-	Ver
Conciliación Bancaria	Total	Total	Total	-	Ver
Caja Chica	Total	Ver	Total	-	-
Retenciones	Total	Total	Ver	-	Ver
Activos Fijos	Total	Total	-	-	Ver
Cierre de Período	Total	Ejecutar	-	-	-
Configuración Contable	Total	Ver	-	-	-
Socios de Negocio	Total	CRUD	CRUD	CRUD	Ver

Permisos Especiales:

restore.finanzas.*: Restaurar registros eliminados (Papelera)
force_delete.finanzas.*: Eliminación definitiva (Solo Super-Admin)
post.payments: Contabilizar pagos
cancel.payments: Anular pagos
post.journal_entries: Contabilizar asientos
reverse.journal_entries: Crear extornos

10. Reportes y Exportación

10.1. Libros Electrónicos (PLE SUNAT)

Libro	Código	Descripción	Período
Libro Diario	5.1	Todos los asientos contabilizados	Mensual
Libro Mayor	6.1	Movimientos por cuenta	Mensual
Registro de Compras	8.1	Facturas de compra con IGV	Mensual
Registro de Ventas	14.1	Facturas emitidas con IGV	Mensual

10.2. Reportes Financieros

Balance de Comprobación: Sumas y saldos de todas las cuentas
Estado de Situación Financiera: Balance General (Activo = Pasivo + Patrimonio)
Estado de Resultados: Ingresos - Gastos = Utilidad/Pérdida
Flujo de Efectivo: Movimientos en cuentas is_cash_flow = true
Antigüedad de Saldos: CXC y CXP por rangos de vencimiento
Conciliación Bancaria: Estado de cuenta vs libros

10.3. Exportadores Disponibles

BankExporter: Catálogo de bancos
Próximamente: SalesInvoiceExporter, PurchaseInvoiceExporter, PaymentExporter, JournalEntryExporter

11. Solución de Problemas (Troubleshooting)

Error: "La fecha de emisión corresponde a un período contable cerrado"

Causa: Intentas crear/editar un documento en un período ya cerrado.
Solución: Verifica la fecha del documento. Si necesitas operar en ese período, solicita al contador reabrir temporalmente modificando is_closed = false en AccountingConfiguration.

Error: "El asiento contable no está balanceado"

Causa: Σ Débitos ≠ Σ Créditos.
Solución: Revisa las líneas del asiento. El sistema muestra la diferencia exacta. Recuerda que la tolerancia es de ±0.01.

Error: "No se puede eliminar porque tiene pagos asociados"

Causa: La factura tiene pagos registrados (aunque sean borradores).
Solución: Primero anula o elimina todos los pagos vinculados. Luego podrás anular la factura.

Error: "Cuenta bancaria requerida para este método de pago"

Causa: Seleccionaste Transferencia, Cheque o Depósito sin indicar cuenta.
Solución: Selecciona una cuenta bancaria activa de la empresa.

Error: "La cuenta bancaria seleccionada no está activa"

Causa: La cuenta tiene is_active = false.
Solución: Activa la cuenta en el módulo de Bancos o selecciona otra cuenta activa.

Error: "El socio debe ser cliente/proveedor según el tipo de pago"

Causa: Un cobro (INBOUND) requiere cliente, un pago (OUTBOUND) requiere proveedor.
Solución: Edita el socio de negocio y marca el rol correspondiente (is_customer o is_supplier).

Error: "Ya existe un documento con este número de serie y correlativo"

Causa: Duplicidad en el identificador del comprobante.
Solución: Para ventas, el sistema genera correlativos automáticos. Para compras, verifica que no hayas registrado antes la misma factura del proveedor.

Error: "El tipo de cambio es obligatorio para moneda Dólares (USD)"

Causa: Transacción en moneda extranjera sin tipo de cambio.
Solución: Ingresa el tipo de cambio del día (SUNAT) en el campo correspondiente.

Error: "No se puede modificar un pago en estado Contabilizado"

Causa: Los pagos contabilizados son inmutables.
Solución: Si necesitas corregir, primero anula el pago (se creará extorno automático) y luego crea uno nuevo con los datos correctos.

Error: "Solo se pueden extornar asientos contabilizados"

Causa: Intentas extornar un asiento en BORRADOR o ANULADO.
Solución: El extorno solo aplica a asientos ya CONTABILIZADO. Si está en borrador, simplemente edítalo o elimínalo.

Error: "Este asiento ya ha sido extornado"

Causa: El asiento ya tiene un reversed_by_id asignado.
Solución: Un asiento solo puede ser extornado una vez. Revisa el asiento de extorno existente.

Error: "No existe configuración contable para la fecha de emisión"

Causa: No hay AccountingConfiguration que cubra la fecha del documento.
Solución: Crea una configuración contable que incluya el rango de fechas necesario.

Error: "No se permiten asientos con más de X días de antigüedad"

Causa: Configuración block_past_entries activa con límite excedido.
Solución: Ajusta la fecha del asiento o modifica el parámetro days_limit_past_entries en la configuración contable.

Finance Module Documentation

Documentación del Módulo de Finanzas

1. Resumen Ejecutivo

2. Flujo del Proceso

2.1. Ciclo de Facturación (Ventas)

2.2. Ciclo de Compras

2.3. Ciclo de Pagos/Cobros

2.4. Ciclo de Asientos Contables

3. Lógica de Negocio y Reglas

3.1. Reglas de Facturación (Ventas)

3.2. Reglas de Compras

3.3. Reglas de Pagos/Cobros

3.4. Reglas Contables (Asientos)

3.5. Métodos de Pago

3.6. Cálculos Automáticos

4. Modelo de Datos Detallado

4.1. Entidades Principales

4.2. Estados Posibles (Status Codes)

InvoiceStatus (Facturas)

PaymentStatus (Pagos)

JournalEntryStatus (Asientos)

JournalEntryType (Tipos de Asiento)

AccountType (Tipos de Cuenta)

4.3. Diagrama de Relaciones

5. Interdependencias

5.1. Módulos Afectados por Finanzas

5.2. Flujos de Integración

6. Casos de Uso Principales

CU-01: Emisión de Factura de Venta

CU-02: Registro de Factura de Compra

CU-03: Registro de Pago/Cobro

CU-04: Conciliación Bancaria

CU-05: Gestión de Caja Chica

CU-06: Cierre de Período Contable

CU-07: Emisión de Notas de Crédito/Débito

CU-08: Extorno de Asiento Contable

7. Guía de Configuración

7.1. Configuración Contable (AccountingConfiguration)

7.2. Plan de Cuentas (ChartOfAccount)

7.3. Socios de Negocio (Partner)

7.4. Monedas Soportadas

8. Widgets del Dashboard Financiero

8.1. AccountsOverviewWidget

8.2. BankBalancesWidget

8.3. OverdueInvoicesWidget

8.4. RevenueExpenseChartWidget

9. Matriz de Roles y Permisos (RBAC)

10. Reportes y Exportación

10.1. Libros Electrónicos (PLE SUNAT)

10.2. Reportes Financieros

10.3. Exportadores Disponibles

11. Solución de Problemas (Troubleshooting)

Error: "La fecha de emisión corresponde a un período contable cerrado"

Error: "El asiento contable no está balanceado"

Error: "No se puede eliminar porque tiene pagos asociados"

Error: "Cuenta bancaria requerida para este método de pago"

Error: "La cuenta bancaria seleccionada no está activa"

Error: "El socio debe ser cliente/proveedor según el tipo de pago"

Error: "Ya existe un documento con este número de serie y correlativo"

Error: "El tipo de cambio es obligatorio para moneda Dólares (USD)"

Error: "No se puede modificar un pago en estado Contabilizado"

Error: "Solo se pueden extornar asientos contabilizados"

Error: "Este asiento ya ha sido extornado"

Error: "No existe configuración contable para la fecha de emisión"

Error: "No se permiten asientos con más de X días de antigüedad"

7.1. Configuración Contable (`AccountingConfiguration`)

7.2. Plan de Cuentas (`ChartOfAccount`)

7.3. Socios de Negocio (`Partner`)