使用说明
🏥 Sistema de Pagos con Webhooks - Django
Sistema completo de gestión de pagos integrado con MercadoPago y GoHighLevel
Procesamiento asíncrono de webhooks • Reintentos automáticos • Integración CRM
🚀 Características Principales
💳 Gestión de Pagos
|
🔗 Webhooks Inteligentes
|
🏢 Integración GoHighLevel
|
🛡️ Robustez y Confiabilidad
|
🏗️ Arquitectura del Sistema
graph TB
A[🌐 Frontend<br/>HTML/CSS/JS] --> B[⚡ Django API<br/>Backend]
B --> C[💳 MercadoPago<br/>Pagos]
B --> D[🏢 GoHighLevel<br/>CRM]
B --> E[🗄️ Base de Datos<br/>SQLite]
B --> F[📝 Sistema de Logs<br/>Webhook Events]
C -.->|Webhooks| B
D -.->|API Calls| B
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#fff3e0
style D fill:#e8f5e8
style E fill:#fce4ec
style F fill:#f1f8e9
🔄 Flujo de Datos
| Paso | Componente | Acción | Estado |
|---|---|---|---|
| 1️⃣ | Frontend | Usuario solicita pago | pending |
| 2️⃣ | Django API | Crea preferencia MP | created |
| 3️⃣ | MercadoPago | Procesa pago | processing |
| 4️⃣ | Webhook | Notifica resultado | webhook_received |
| 5️⃣ | GoHighLevel | Actualiza contacto | synced |
| 6️⃣ | Base de Datos | Almacena evento | completed |
🛠️ Stack Tecnológico
| 🎯 Categoría | 🛠️ Tecnología | 📊 Versión | 🎨 Color |
|---|---|---|---|
| Backend | Django | 5.2.7 | 🟢 |
| Lenguaje | Python | 3.13+ | 🔵 |
| Base de Datos | SQLite | 3.x | 🟡 |
| Frontend | HTML5/CSS3/JS | Latest | 🟠 |
| APIs | MercadoPago | v1 | 🟠 |
| CRM | GoHighLevel | v1 | 🟣 |
🔧 Herramientas de Desarrollo
|
🔧 Black |
📦 isort |
🔍 flake8 |
🧪 pytest |
📊 coverage |
🏗️ Infraestructura
Servidor: Django Development Server
Logs: Sistema estructurado con colores
Webhooks: Procesamiento asíncrono
Base de Datos: SQLite (dev) / PostgreSQL (prod)
Monitoreo: Logs en tiempo real
🔄 CI/CD Pipeline
🚀 Pipeline de Calidad
graph LR
A[📝 Código] --> B[🔍 Django Check]
B --> C[🎨 Black Format]
C --> D[📦 isort Imports]
D --> E[🔍 flake8 Lint]
E --> F[🧪 pytest Tests]
F --> G[✅ Deploy Ready]
style A fill:#e3f2fd
style G fill:#e8f5e8
📊 Métricas de Calidad
| 🎯 Métrica | 📈 Valor | 🎨 Estado |
|---|---|---|
| Tests | 5/5 | ✅ PASSED |
| Cobertura | 41% | 🟡 GOOD |
| Linting | 0 errores | ✅ CLEAN |
| Formato | 100% | ✅ PERFECT |
| Imports | Ordenados | ✅ SORTED |
🔧 Comando de Verificación
# 🚀 Ejecutar todas las verificaciones
python run_ci_checks.py
# 📊 Resultado esperado
✅ Django System Check - PASSED
✅ Code Formatting (Black) - PASSED
✅ Import Sorting (isort) - PASSED
✅ Linting (flake8) - PASSED
✅ Testing (pytest) - PASSED
🎉 SUCCESS: 5/5
⚙️ GitHub Actions
name: 🚀 CI Pipeline
on: [push, pull_request]
jobs:
quality-check:
runs-on: ubuntu-latest
steps:
- name: 📥 Checkout Code
uses: actions/checkout@v4
- name: 🐍 Setup Python 3.13
uses: actions/setup-python@v4
with:
python-version: '3.13'
- name: 📦 Install Dependencies
run: pip install -r requirements.txt
- name: 🔍 Run Quality Checks
run: python run_ci_checks.py
- name: 📊 Upload Coverage
uses: codecov/codecov-action@v3
📦 Instalación Rápida
🚀 Setup en 5 minutos
graph TD
A[📥 Clone Repo] --> B[🐍 Create Venv]
B --> C[📦 Install Deps]
C --> D[⚙️ Setup Env]
D --> E[🗄️ Run Migrations]
E --> F[🎉 Ready!]
style A fill:#e3f2fd
style F fill:#e8f5e8
🔧 Pasos de Instalación
1️⃣ Clonar Repositorio2️⃣ Entorno Virtual3️⃣ Dependencias |
4️⃣ Variables de Entorno5️⃣ Base de Datos |
⚡ Verificación Rápida
# 🧪 Ejecutar tests
python run_ci_checks.py
# 🚀 Iniciar servidor
python manage.py runserver
# 📊 Verificar estado
python manage.py check
🚀 Uso
Iniciar el servidor
python manage.py runserver
Procesar webhooks pendientes
python manage.py process_webhooks
Ejecutar verificaciones de calidad
python run_ci_checks.py
📋 Endpoints API
| Endpoint | Método | Descripción |
|---|---|---|
/ |
GET | Página principal |
/api/contacts |
GET | Obtener contactos de GHL |
/api/payments |
GET | Historial de pagos |
/api/webhook-events |
GET | Eventos de webhook |
/api/create-payment |
POST | Crear nuevo pago |
/payments/status/<id> |
GET | Estado de pago |
/webhooks/mp |
POST | Webhook de MercadoPago |
🔄 Flujo de Webhooks
- Recepción: MercadoPago envía webhook
- Almacenamiento: Se guarda en base de datos
- Procesamiento: Se procesa de forma asíncrona
- Reintentos: Si falla, se programa reintento
- Integración: Se sincroniza con GoHighLevel
📊 Monitoreo
Logs
- Archivo:
logs/webhook.log - Consola: Logs en tiempo real con colores
- Niveles: INFO, WARNING, ERROR
Base de Datos
- Payments: Transacciones de pago
- WebhookEvents: Eventos y su estado
- Admin: Panel de administración Django
🧪 Testing
# Ejecutar todos los tests
pytest
# Con cobertura
pytest --cov=.
# Tests específicos
pytest payments/tests/test_models.py
🔧 Desarrollo
Formateo de código
black .
isort .
Verificaciones de calidad
flake8 .
python run_ci_checks.py
Estructura del proyecto
├── backend/ # Configuración Django
├── payments/ # App principal
│ ├── models.py # Modelos de datos
│ ├── views.py # Vistas API
│ ├── services/ # Lógica de negocio
│ └── tests/ # Tests unitarios
├── frontend/ # Interfaz web
├── logs/ # Archivos de log
└── docs/ # Documentación
📚 Documentación Adicional
🚨 Troubleshooting
Problemas comunes
- Webhooks no se procesan: Verificar
process_webhookscommand - Errores de API: Revisar tokens en
.env - Base de datos: Ejecutar
python manage.py migrate
Logs importantes
# Ver logs en tiempo real
tail -f logs/webhook.log
# Verificar estado de webhooks
python manage.py shell
>>> from payments.models import WebhookEvent
>>> WebhookEvent.objects.filter(processed=False).count()
🤝 Contribución
- Fork el proyecto
- Crear rama feature (
git checkout -b feature/nueva-funcionalidad) - Commit cambios (
git commit -m 'Agregar nueva funcionalidad') - Push a la rama (
git push origin feature/nueva-funcionalidad) - Crear Pull Request
📄 Licencia
Este proyecto está bajo la Licencia MIT. Ver LICENSE para más detalles.
👥 Equipo
- Desarrollo: Sistema de pagos con webhooks
- Arquitectura: Django + APIs externas
- Monitoreo: Logs estructurados y base de datos
🎉 ¡Sistema Listo para Producción!
🚀 Estado del Proyecto
|
📊 Métricas
|
🌟 ¿Te gusta el proyecto?
Desarrollado con ❤️ usando Django + Python
