Introducción
Como desarrolladores, estamos acostumbrados a trabajar con datos y relaciones, pero cuando nos enfrentamos a implementar estados financieros, la tarea puede parecer abrumadora. ¿Te has preguntado alguna vez por qué Activo = Pasivo + Patrimonio? Es similar a cuando trabajamos con git, donde staged_changes + committed_changes = total_changes.
Este tutorial te mostrará cómo implementar los dos estados financieros principales (Balance General y Estado de Resultados) en Django, usando analogías de programación que ya conoces. Aprenderás a modelar la ecuación contable como una invariante del sistema y a generar reportes financieros precisos usando solo el admin de Django.
Prerrequisitos
CODE
# Crear un nuevo entorno virtual
python -m venv venv
source venv/bin/activate # En Windows: venv\Scripts\activate
# Instalar dependencias
pip install django==5.0
pip install django-mptt==0.16.0 # Para jerarquías de cuentas
pip install django-money==3.4.0 # Para manejo preciso de dinero
Conceptos Clave: Traduciendo Contabilidad a Código
La Ecuación Contable como Invariante del Sistema
CODE
# En contabilidad:
assert Activo == Pasivo + Patrimonio
# En programación:
def validate_accounting_equation(self):
assets = self.get_total_assets()
liabilities = self.get_total_liabilities()
equity = self.get_total_equity()
assert abs(assets - (liabilities + equity)) < Decimal('0.01')
Estados Financieros como Vistas de Base de Datos
- Balance General = SELECT snapshot del estado financiero
- Estado de Resultados = Aggregación de transacciones en un período
Implementación
CODE
# accounting/models.py
from django.db import models
from django.core.exceptions import ValidationError
from django.db.models import Sum, Q
from mptt.models import MPTTModel, TreeForeignKey
from djmoney.models.fields import MoneyField
from decimal import Decimal
from datetime import date
class AccountType(models.TextChoices):
ASSET = 'ASSET', 'Activo'
LIABILITY = 'LIABILITY', 'Pasivo'
EQUITY = 'EQUITY', 'Patrimonio'
INCOME = 'INCOME', 'Ingreso'
EXPENSE = 'EXPENSE', 'Gasto'
class AccountCategory(models.TextChoices):
CURRENT_ASSET = 'CURRENT_ASSET', 'Activo Corriente'
NON_CURRENT_ASSET = 'NON_CURRENT_ASSET', 'Activo No Corriente'
CURRENT_LIABILITY = 'CURRENT_LIABILITY', 'Pasivo Corriente'
NON_CURRENT_LIABILITY = 'NON_CURRENT_LIABILITY', 'Pasivo No Corriente'
CAPITAL = 'CAPITAL', 'Capital'
REVENUE = 'REVENUE', 'Ingresos'
OPERATING_EXPENSE = 'OPERATING_EXPENSE', 'Gastos Operativos'
OTHER = 'OTHER', 'Otros'
class FiscalYear(models.Model):
"""
Representa un año fiscal para reportes financieros.
Similar a una rama en Git que agrupa commits relacionados.
"""
year = models.IntegerField(unique=True)
start_date = models.DateField()
end_date = models.DateField()
is_closed = models.BooleanField(default=False)
def clean(self):
if self.start_date >= self.end_date:
raise ValidationError(
'La fecha de inicio debe ser anterior a la fecha de fin'
)
def __str__(self):
return f"Año Fiscal {self.year}"
class Account(MPTTModel):
"""
Modelo para cuentas contables con jerarquía y categorización.
"""
code = models.CharField(max_length=20, unique=True)
name = models.CharField(max_length=100)
type = models.CharField(max_length=10, choices=AccountType.choices)
category = models.CharField(
max_length=20,
choices=AccountCategory.choices,
help_text="Categoría para reportes financieros"
)
parent = TreeForeignKey(
'self',
on_delete=models.PROTECT,
null=True,
blank=True,
related_name='children'
)
is_leaf = models.BooleanField(default=True)
def get_balance(self, start_date=None, end_date=None):
"""Calcula el balance de la cuenta incluyendo subcuentas."""
entries = self.journalentry_set.all()
if start_date:
entries = entries.filter(transaction__date__gte=start_date)
if end_date:
entries = entries.filter(transaction__date__lte=end_date)
debit_sum = entries.aggregate(
Sum('debit_amount')
)['debit_amount__sum'] or Decimal('0')
credit_sum = entries.aggregate(
Sum('credit_amount')
)['credit_amount__sum'] or Decimal('0')
if self.type in ['ASSET', 'EXPENSE']:
balance = debit_sum - credit_sum
else:
balance = credit_sum - debit_sum
for child in self.get_children():
balance += child.get_balance(start_date, end_date)
return balance
class Meta:
ordering = ['code']
class FinancialStatement:
"""
Clase base para estados financieros.
Similar a una vista materializada en bases de datos.
"""
def __init__(self, date=None, fiscal_year=None):
self.date = date or date.today()
self.fiscal_year = fiscal_year
if fiscal_year:
self.start_date = fiscal_year.start_date
self.end_date = fiscal_year.end_date
else:
self.start_date = None
self.end_date = self.date
class BalanceSheet(FinancialStatement):
"""
Balance General: Activo = Pasivo + Patrimonio
"""
def get_assets(self):
return {
'current': Account.objects.filter(
category='CURRENT_ASSET'
).aggregate(
total=Sum('journalentry__debit_amount') -
Sum('journalentry__credit_amount')
)['total'] or Decimal('0'),
'non_current': Account.objects.filter(
category='NON_CURRENT_ASSET'
).aggregate(
total=Sum('journalentry__debit_amount') -
Sum('journalentry__credit_amount')
)['total'] or Decimal('0')
}
def get_liabilities(self):
return {
'current': Account.objects.filter(
category='CURRENT_LIABILITY'
).aggregate(
total=Sum('journalentry__credit_amount') -
Sum('journalentry__debit_amount')
)['total'] or Decimal('0'),
'non_current': Account.objects.filter(
category='NON_CURRENT_LIABILITY'
).aggregate(
total=Sum('journalentry__credit_amount') -
Sum('journalentry__debit_amount')
)['total'] or Decimal('0')
}
def get_equity(self):
return Account.objects.filter(
type='EQUITY'
).aggregate(
total=Sum('journalentry__credit_amount') -
Sum('journalentry__debit_amount')
)['total'] or Decimal('0')
def validate_equation(self):
"""
Verifica la ecuación contable: Activo = Pasivo + Patrimonio
"""
assets = sum(self.get_assets().values())
liabilities = sum(self.get_liabilities().values())
equity = self.get_equity()
if abs(assets - (liabilities + equity)) >= Decimal('0.01'):
raise ValidationError(
'La ecuación contable no está balanceada'
)
class IncomeStatement(FinancialStatement):
"""
Estado de Resultados: Utilidad = Ingresos - Gastos
"""
def get_revenues(self):
return Account.objects.filter(
type='INCOME'
).aggregate(
total=Sum('journalentry__credit_amount') -
Sum('journalentry__debit_amount')
)['total'] or Decimal('0')
def get_expenses(self):
return Account.objects.filter(
type='EXPENSE'
).aggregate(
total=Sum('journalentry__debit_amount') -
Sum('journalentry__credit_amount')
)['total'] or Decimal('0')
def get_net_income(self):
return self.get_revenues() - self.get_expenses()
CODE
# accounting/admin.py
from django.contrib import admin
from mptt.admin import MPTTModelAdmin
from .models import (
Account, Transaction, JournalEntry,
FiscalYear, BalanceSheet, IncomeStatement
)
@admin.register(FiscalYear)
class FiscalYearAdmin(admin.ModelAdmin):
list_display = ('year', 'start_date', 'end_date', 'is_closed')
search_fields = ('year',)
@admin.register(Account)
class AccountAdmin(MPTTModelAdmin):
list_display = (
'code', 'name', 'type', 'category',
'get_balance', 'is_leaf'
)
list_filter = ('type', 'category', 'is_leaf')
search_fields = ('code', 'name')
def get_readonly_fields(self, request, obj=None):
if obj and obj.journalentry_set.exists():
return ['type', 'category']
return []
def has_delete_permission(self, request, obj=None):
if obj and obj.journalentry_set.exists():
return False
return super().has_delete_permission(request, obj)
class JournalEntryInline(admin.TabularInline):
model = JournalEntry
extra = 2
def formfield_for_foreignkey(self, db_field, request, **kwargs):
if db_field.name == "account":
kwargs["queryset"] = Account.objects.filter(is_leaf=True)
return super().formfield_for_foreignkey(db_field, request, **kwargs)
@admin.register(Transaction)
class TransactionAdmin(admin.ModelAdmin):
list_display = ('date', 'description', 'reference')
search_fields = ('description', 'reference')
date_hierarchy = 'date'
inlines = [JournalEntryInline]
def save_model(self, request, obj, form, change):
obj.full_clean()
super().save_model(request, obj, form, change)
def save_formset(self, request, form, formset, change):
instances = formset.save(commit=False)
# Validar balance de la transacción
total_debit = sum(
form.cleaned_data.get('debit_amount', 0)
for form in formset.forms
if hasattr(form, 'cleaned_data')
)
total_credit = sum(
form.cleaned_data.get('credit_amount', 0)
for form in formset.forms
if hasattr(form, 'cleaned_data')
)
if total_debit != total_credit:
raise ValidationError(
'Los débitos deben ser iguales a los créditos'
)
for instance in instances:
instance.save()
Ejemplo Real: Registro de Operaciones
CODE
# Configuración inicial de cuentas
def setup_accounts():
# Activos
assets = Account.objects.create(
code='1',
name='Activos',
type='ASSET',
category='CURRENT_ASSET',
is_leaf=False
)
bank = Account.objects.create(
code='1.1',
name='Banco',
type='ASSET',
category='CURRENT_ASSET',
parent=assets
)
# Pasivos
liabilities = Account.objects.create(
code='2',
name='Pasivos',
type='LIABILITY',
category='CURRENT_LIABILITY',
is_leaf=False
)
accounts_payable = Account.objects.create(
code='2.1',
name='Cuentas por Pagar',
type='LIABILITY',
category='CURRENT_LIABILITY',
parent=liabilities
)
# Patrimonio
equity = Account.objects.create(
code='3',
name='Patrimonio',
type='EQUITY',
category='CAPITAL',
is_leaf=False
)
capital = Account.objects.create(
code='3.1',
name='Capital Social',
type='EQUITY',
category='CAPITAL',
parent=equity
)
# Ejemplo de transacción: Aporte de capital
def register_capital_contribution():
transaction = Transaction.objects.create(
date=date.today(),
description='Aporte inicial de capital',
reference='CAPITAL-001'
)
# Débito a Banco
JournalEntry.objects.create(
transaction=transaction,
account=Account.objects.get(code='1.1'),
debit_amount=Decimal('10000.00')
)
# Crédito a Capital Social
JournalEntry.objects.create(
transaction=transaction,
account=Account.objects.get(code='3.1'),
credit_amount=Decimal('10000.00')
)
# Verificar Balance General
balance_sheet = BalanceSheet()
balance_sheet.validate_equation() # Debe pasar sin errores
# Consultar Estado de Resultados
income_statement = IncomeStatement()
print(f"Utilidad Neta: {income_statement.get_net_income()}")
Tests Unitarios Completos
CODE
# accounting/tests.py
from django.test import TestCase
from django.core.exceptions import ValidationError
from decimal import Decimal
from datetime import date
from .models import (
Account, Transaction, JournalEntry,
BalanceSheet, IncomeStatement, FiscalYear
)
class FinancialStatementsTestCase(TestCase):
def setUp(self):
"""Configura el ambiente de pruebas con cuentas básicas"""
# Activos
self.bank = Account.objects.create(
code='1.1',
name='Banco',
type='ASSET',
category='CURRENT_ASSET'
)
# Pasivos
self.accounts_payable = Account.objects.create(
code='2.1',
name='Cuentas por Pagar',
type='LIABILITY',
category='CURRENT_LIABILITY'
)
# Patrimonio
self.capital = Account.objects.create(
code='3.1',
name='Capital',
type='EQUITY',
category='CAPITAL'
)
# Ingresos
self.sales = Account.objects.create(
code='4.1',
name='Ventas',
type='INCOME',
category='REVENUE'
)
# Gastos
self.expenses = Account.objects.create(
code='5.1',
name='Gastos Operativos',
type='EXPENSE',
category='OPERATING_EXPENSE'
)
# Año Fiscal
self.fiscal_year = FiscalYear.objects.create(
year=2024,
start_date=date(2024, 1, 1),
end_date=date(2024, 12, 31)
)
def test_accounting_equation(self):
"""Prueba la ecuación básica: Activo = Pasivo + Patrimonio"""
# Registrar aporte de capital
transaction = Transaction.objects.create(
date=date.today(),
description='Aporte inicial de capital'
)
JournalEntry.objects.create(
transaction=transaction,
account=self.bank,
debit_amount=Decimal('10000.00')
)
JournalEntry.objects.create(
transaction=transaction,
account=self.capital,
credit_amount=Decimal('10000.00')
)
balance_sheet = BalanceSheet(date=date.today())
self.assertEqual(
sum(balance_sheet.get_assets().values()),
sum(balance_sheet.get_liabilities().values()) +
balance_sheet.get_equity()
)
def test_income_statement(self):
"""Prueba el cálculo correcto del Estado de Resultados"""
# Registrar una venta
sale_transaction = Transaction.objects.create(
date=date.today(),
description='Venta al contado'
)
JournalEntry.objects.create(
transaction=sale_transaction,
account=self.bank,
debit_amount=Decimal('5000.00')
)
JournalEntry.objects.create(
transaction=sale_transaction,
account=self.sales,
credit_amount=Decimal('5000.00')
)
# Registrar un gasto
expense_transaction = Transaction.objects.create(
date=date.today(),
description='Gasto operativo'
)
JournalEntry.objects.create(
transaction=expense_transaction,
account=self.expenses,
debit_amount=Decimal('2000.00')
)
JournalEntry.objects.create(
transaction=expense_transaction,
account=self.bank,
credit_amount=Decimal('2000.00')
)
income_statement = IncomeStatement(fiscal_year=self.fiscal_year)
self.assertEqual(
income_statement.get_net_income(),
Decimal('3000.00') # 5000 - 2000
)
def test_invalid_transaction(self):
"""Prueba que no se pueden crear transacciones desbalanceadas"""
transaction = Transaction.objects.create(
date=date.today(),
description='Transacción inválida'
)
JournalEntry.objects.create(
transaction=transaction,
account=self.bank,
debit_amount=Decimal('1000.00')
)
# Debería fallar al validar
with self.assertRaises(ValidationError):
transaction.clean()
def test_account_restrictions(self):
"""Prueba las restricciones en las cuentas"""
# Intentar crear cuenta con tipo inválido
with self.assertRaises(ValidationError):
Account.objects.create(
code='1.2',
name='Cuenta Inválida',
type='INVALID_TYPE'
)
# Intentar crear cuenta con código duplicado
with self.assertRaises(ValidationError):
Account.objects.create(
code='1.1', # Ya existe
name='Otra Cuenta',
type='ASSET'
)
Queries Complejas para Reportes Financieros
CODE
# accounting/reports.py
from django.db.models import Sum, F, Q
from django.db.models.functions import ExtractYear, ExtractMonth
from decimal import Decimal
class FinancialReports:
@staticmethod
def get_monthly_balance_sheet(year):
"""
Genera balance general mensual para un año específico
"""
return Account.objects.filter(
journalentry__transaction__date__year=year
).annotate(
month=ExtractMonth('journalentry__transaction__date')
).values('type', 'category', 'month').annotate(
balance=Sum(
F('journalentry__debit_amount') -
F('journalentry__credit_amount'),
filter=Q(type__in=['ASSET', 'EXPENSE'])
) + Sum(
F('journalentry__credit_amount') -
F('journalentry__debit_amount'),
filter=Q(type__in=['LIABILITY', 'EQUITY', 'INCOME'])
)
).order_by('type', 'category', 'month')
@staticmethod
def get_profit_and_loss_trend(fiscal_year):
"""
Calcula la tendencia de utilidad por mes
"""
return Account.objects.filter(
type__in=['INCOME', 'EXPENSE'],
journalentry__transaction__date__range=[
fiscal_year.start_date,
fiscal_year.end_date
]
).annotate(
month=ExtractMonth('journalentry__transaction__date')
).values('type', 'month').annotate(
amount=Sum(
F('journalentry__credit_amount') -
F('journalentry__debit_amount'),
filter=Q(type='INCOME')
) + Sum(
F('journalentry__debit_amount') -
F('journalentry__credit_amount'),
filter=Q(type='EXPENSE')
)
).order_by('month')
@staticmethod
def get_account_movements(account, start_date, end_date):
"""
Obtiene el detalle de movimientos de una cuenta
"""
return JournalEntry.objects.filter(
account=account,
transaction__date__range=[start_date, end_date]
).select_related('transaction').order_by(
'transaction__date'
).annotate(
running_balance=Sum(
F('debit_amount') - F('credit_amount')
) if account.type in ['ASSET', 'EXPENSE']
else Sum(F('credit_amount') - F('debit_amount'))
)
Validaciones Adicionales
CODE
# accounting/validators.py
from django.core.exceptions import ValidationError
from django.db.models import Sum
from decimal import Decimal
def validate_transaction_balance(transaction):
"""
Valida que una transacción esté balanceada
"""
entries = transaction.journalentry_set.all()
total_debit = entries.aggregate(
Sum('debit_amount')
)['debit_amount__sum'] or Decimal('0')
total_credit = entries.aggregate(
Sum('credit_amount')
)['credit_amount__sum'] or Decimal('0')
if total_debit != total_credit:
raise ValidationError(
f'La transacción no está balanceada. '
f'Débitos: {total_debit}, Créditos: {total_credit}'
)
def validate_account_type_consistency(account):
"""
Valida la consistencia del tipo de cuenta
"""
if account.parent and account.type != account.parent.type:
raise ValidationError(
'El tipo de cuenta debe ser consistente con su cuenta padre'
)
def validate_fiscal_year_transactions(fiscal_year):
"""
Valida que no haya transacciones fuera del período fiscal
"""
if Transaction.objects.filter(
date__lt=fiscal_year.start_date
).exists() or Transaction.objects.filter(
date__gt=fiscal_year.end_date
).exists():
raise ValidationError(
'Existen transacciones fuera del período fiscal'
)
Ejemplos de Uso
CODE
# Ejemplo 1: Generar Balance General
def generate_balance_sheet(date):
balance_sheet = BalanceSheet(date=date)
assets = balance_sheet.get_assets()
liabilities = balance_sheet.get_liabilities()
equity = balance_sheet.get_equity()
print("BALANCE GENERAL")
print("==============")
print("\nACTIVOS")
print(f"Corriente: {assets['current']}")
print(f"No Corriente: {assets['non_current']}")
print(f"Total Activos: {sum(assets.values())}")
print("\nPASIVOS")
print(f"Corriente: {liabilities['current']}")
print(f"No Corriente: {liabilities['non_current']}")
print(f"Total Pasivos: {sum(liabilities.values())}")
print(f"\nPATRIMONIO: {equity}")
try:
balance_sheet.validate_equation()
print("\nEl balance está cuadrado ✓")
except ValidationError:
print("\n⚠️ El balance no está cuadrado")
# Ejemplo 2: Generar Estado de Resultados
def generate_income_statement(fiscal_year):
income_stmt = IncomeStatement(fiscal_year=fiscal_year)
revenues = income_stmt.get_revenues()
expenses = income_stmt.get_expenses()
net_income = income_stmt.get_net_income()
print("ESTADO DE RESULTADOS")
print("===================")
print(f"\nIngresos: {revenues}")
print(f"Gastos: {expenses}")
print(f"Utilidad Neta: {net_income}")
Mejores Prácticas y Recomendaciones
Transacciones Atómicas
- Usar
transaction.atomic()para operaciones críticas - Implementar rollbacks automáticos en caso de error
- Mantener la consistencia de datos
- Usar
Seguridad
- Validar todos los inputs numéricos
- Usar Decimal para cálculos monetarios
- Implementar permisos granulares en el admin
Optimización
- Usar select_related() para queries eficientes
- Implementar índices en campos críticos
- Cachear resultados de reportes pesados
Mantenibilidad
- Documentar todas las funciones contables
- Mantener logs de auditoría
- Usar nombres descriptivos para las cuentas
Conclusión
Este tutorial te ha mostrado cómo implementar un sistema robusto de estados financieros en Django. Los conceptos clave que hemos cubierto incluyen:
- La ecuación contable como invariante del sistema
- Estados financieros como vistas agregadas de datos
- Validaciones robustas para mantener la integridad
- Tests automatizados para asegurar la calidad
Vollständiger Original-Bericht
Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.
SOCIAL SHARE CARD GENERATOR