Sistema de gestión de pagos y domiciliaciones bancarias desarrollado en Django REST Framework, diseñado para procesar y administrar cobros automáticos entre diferentes instituciones bancarias mexicanas.
- Framework Backend: Django 5.2.1 + Django REST Framework 3.16.0
- Autenticación: JWT (JSON Web Tokens) con Simple JWT
- Base de Datos: SQLite (desarrollo) / PostgreSQL (producción)
- Lenguaje: Python 3.x
- Gestión de Variables: python-dotenv para configuración de entorno
PaymentManager/
├── PaymentManager/ # Configuración principal del proyecto
│ ├── settings.py # Configuraciones Django
│ ├── urls.py # Routing principal
│ ├── wsgi.py # Interfaz WSGI
│ └── asgi.py # Interfaz ASGI
├── apps/ # Aplicaciones Django
│ ├── AuthSystem/ # Sistema de autenticación
│ └── MagicTool/ # Módulo de gestión de pagos
├── .env # Variables de entorno
├── manage.py # Comando Django
└── requirements.txt # Dependencias Python
Sistema completo de gestión de usuarios con autenticación JWT, que incluye:
- Modelo de Usuario Personalizado: Extiende AbstractUser con email como identificador único
- Autenticación JWT: Tokens de acceso y refresh con rotación automática
- Gestión de Sesiones: Login, logout con blacklist de tokens
- Administración de Usuarios: Registro, actualización de perfil, cambio de contraseñas
POST /api/auth/login/ # Autenticación de usuario
POST /api/auth/register/ # Registro de nuevo usuario
GET /api/auth/profile/ # Obtener perfil del usuario autenticado
PUT /api/auth/profile/update/ # Actualizar perfil
POST /api/auth/change-password/ # Cambiar contraseña
POST /api/auth/logout/ # Cerrar sesión
GET /api/auth/verify-token/ # Verificar validez del token
GET /api/auth/users/ # Listar usuarios (solo admin)
- Access Token: 60 minutos de vigencia
- Refresh Token: 7 días de vigencia con rotación automática
- Blacklist: Los tokens se invalidan automáticamente al cerrar sesión
Módulo central para el procesamiento de domiciliaciones bancarias y gestión de cobros.
RespuestaBanco: Catálogo de códigos de respuesta bancaria (>100 códigos diferentes)
- Respuestas exitosas: 'DOM1', 'INC0', etc.
- Errores de cuenta: Inexistente, bloqueada, cancelada, fondos insuficientes
- Errores de proceso: Duplicados, fuera de horario, datos inválidos
Banco: Catálogo de instituciones financieras mexicanas
- Bancos principales: BBVA, Santander, Banamex, HSBC, Banorte
- Instituciones especializadas: NAFIN, BANOBRAS, STP
- Casas de bolsa y cambio
Credito: Registro de créditos del sistema
- Identificador único por crédito
Emisora: Configuración de emisores de domiciliación
- Asociación banco-emisora
- Tipos de envío: TRADICIONAL, CUENTA, TARJETA, INTERBANCARIO, etc.
ListaCobro: Listas de cobro organizadas
- Agrupación por banco, fecha y emisora
- Control de horarios de procesamiento
Cobro: Transacciones individuales de cobro
- Montos: exigible, a cobrar, cobrado
- Referencias: crédito, banco, respuesta, lista
- Trazabilidad completa de la transacción
Logs: Sistema de auditoría
- Registro timestamped de eventos
- Niveles de logging
- Resultados de operaciones
Cada modelo cuenta con endpoints CRUD completos:
GET /api/magic-tool/{modelo}/ # Listar registros
POST /api/magic-tool/{modelo}/ # Crear registro
GET /api/magic-tool/{modelo}/{id}/ # Obtener registro específico
PUT /api/magic-tool/{modelo}/{id}/ # Actualizar registro
DELETE /api/magic-tool/{modelo}/{id}/ # Eliminar registro
- Python 3.8+
- pip (gestor de paquetes Python)
- PostgreSQL (para producción)
- Clonar el repositorio
git clone <repository-url>
cd PaymentManager- Crear entorno virtual
python -m venv venv
source venv/bin/activate # Linux/Mac
# o
venv\Scripts\activate # Windows- Instalar dependencias
pip install -r requirements.txt- Configurar variables de entorno
Crear archivo
.enven la raíz del proyecto:
DB_NAME=credifiel
DB_USER=django_user
DB_PASSWORD=your_password
SECRET_KEY=your-secret-key-here
DEBUG=True- Ejecutar migraciones
python manage.py makemigrations
python manage.py migrate- Crear superusuario
python manage.py createsuperuser- Iniciar servidor de desarrollo
python manage.py runserverPor defecto, el sistema usa SQLite para desarrollo local. No requiere configuración adicional.
Para usar PostgreSQL, descomentar la configuración en settings.py y configurar las variables de entorno correspondientes:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': os.getenv('DB_NAME'),
'USER': os.getenv('DB_USER'),
'PASSWORD': os.getenv('DB_PASSWORD'),
'HOST': os.getenv('DB_HOST', 'localhost'),
'PORT': os.getenv('DB_PORT', '5432'),
}
}El sistema incluye un comando personalizado para importar cobros desde archivos CSV:
python manage.py importar_creditos archivo.csvEl archivo CSV debe contener las siguientes columnas:
idCredito: Identificador del créditomontoExigible: Monto total exigiblemontoCobrar: Monto a cobrar en esta transacciónmontoCobrado: Monto efectivamente cobradoidRespuestaBanco: Código de respuesta del bancoidBanco: Identificador del bancoidListaCobro: Identificador de la lista de cobro
Alternativamente, existe un script load_data.py para cargas masivas con manejo de errores:
# Modificar la ruta del archivo en load_data.py
archivo = "resources/tu_archivo.csv"- JWT Security: Tokens firmados con HS256
- Permission Classes: Todos los endpoints requieren autenticación
- Token Rotation: Los refresh tokens se rotan automáticamente
- Blacklisting: Invalidación segura de tokens al logout
- CORS: Configurado para desarrollo (ajustar para producción)
- DEBUG: Deshabilitado en producción
- SECRET_KEY: Gestionado por variables de entorno
- Password Validation: Validadores Django habilitados
Todas las peticiones (excepto login y registro) requieren header de autorización:
Authorization: Bearer <access_token>
Las respuestas siguen un formato JSON consistente:
{
"message": "Mensaje descriptivo",
"data": { ... },
"errors": { ... }
}Los endpoints de listado incluyen paginación automática:
- PAGE_SIZE: 10 registros por página
- Navegación: URLs next/previous en la respuesta
El proyecto sigue la arquitectura de aplicaciones separadas:
- Separación de responsabilidades: AuthSystem vs MagicTool
- Modularidad: Cada app maneja su dominio específico
- Reutilización: Componentes independientes y reutilizables
- Settings por Entorno: Configuración mediante variables de entorno
- Serializers Específicos: Validación y transformación de datos
- Generic Views: Uso de vistas genéricas de DRF para consistencia
- Model Choices: Catálogos definidos como choices en modelos
- Logging System: Registro de eventos para auditoría
Los archivos de tests están preparados en cada aplicación:
apps/AuthSystem/tests.pyapps/MagicTool/tests.py
El sistema está configurado para México:
- Idioma: Español (es-mx)
- Zona Horaria: America/Monterrey
- Monedas: Configurado para pesos mexicanos
DEBUG=False
SECRET_KEY=<strong-secret-key>
DB_NAME=<database-name>
DB_USER=<database-user>
DB_PASSWORD=<database-password>
DB_HOST=<database-host>
DB_PORT=<database-port>
ALLOWED_HOSTS=<your-domain.com>- Configurar servidor web (Nginx/Apache)
- Implementar cache (Redis/Memcached)
- Configurar logs de aplicación
- Backup automático de base de datos
- Monitoring y alertas
Este sistema está diseñado para manejar el flujo completo de domiciliaciones bancarias, desde la creación de listas de cobro hasta el procesamiento de respuestas bancarias, con un enfoque en la trazabilidad, auditoría y seguridad de las transacciones financieras.