支付管理系统

一个集成MercadoPago和GoHighLevel的支付管理系统,支持异步Webhook处理和自动重试机制。

  • by Adrian-nex
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Adrian-nex/GHL-Link-de-Pago-y-Confirmacion-MCP

使用说明

🏥 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

  • ✅ Integración completa con MercadoPago
  • ✅ Creación de preferencias de pago
  • ✅ Seguimiento de estados de pago
  • ✅ Historial de transacciones

🔗 Webhooks Inteligentes

  • ✅ Procesamiento asíncrono de eventos
  • ✅ Sistema de reintentos con backoff exponencial
  • ✅ Almacenamiento de payloads completos
  • ✅ Observabilidad completa con logs detallados

🏢 Integración GoHighLevel

  • ✅ Sincronización automática de contactos
  • ✅ Aplicación de tags automáticos
  • ✅ Gestión de citas y seguimiento

🛡️ Robustez y Confiabilidad

  • ✅ Sistema de reintentos automáticos (3 intentos)
  • ✅ Manejo de errores detallado
  • ✅ Logs estructurados para debugging
  • ✅ Base de datos para persistencia de eventos

🏗️ 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
Formateador

📦 isort
Organizador

🔍 flake8
Linter

🧪 pytest
Testing

📊 coverage
Cobertura

🏗️ 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 Repositorio

git clone <repository-url>
cd Ejer02_done

2️⃣ Entorno Virtual

# Crear entorno
python -m venv .venv

# Activar (Windows)
.venv\Scripts\activate

# Activar (Linux/Mac)
source .venv/bin/activate

3️⃣ Dependencias

pip install -r requirements.txt

4️⃣ Variables de Entorno

# Crear archivo .env
touch .env
# MercadoPago
MP_ACCESS_TOKEN=tu_access_token
MP_PUBLIC_KEY=tu_public_key
BASE_URL=http://localhost:8000

# GoHighLevel
GHL_TOKEN=tu_ghl_token
GHL_BASE_URL=https://services.leadconnectorhq.com
GHL_LOCATION_ID=tu_location_id

5️⃣ Base de Datos

python manage.py migrate
python manage.py createsuperuser

⚡ 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

  1. Recepción: MercadoPago envía webhook
  2. Almacenamiento: Se guarda en base de datos
  3. Procesamiento: Se procesa de forma asíncrona
  4. Reintentos: Si falla, se programa reintento
  5. 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

  1. Webhooks no se procesan: Verificar process_webhooks command
  2. Errores de API: Revisar tokens en .env
  3. 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

  1. Fork el proyecto
  2. Crear rama feature (git checkout -b feature/nueva-funcionalidad)
  3. Commit cambios (git commit -m 'Agregar nueva funcionalidad')
  4. Push a la rama (git push origin feature/nueva-funcionalidad)
  5. 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

  • ✅ CI/CD: 5/5 verificaciones
  • ✅ Tests: 100% pasando
  • ✅ Código: Formato perfecto
  • ✅ Documentación: Completa

📊 Métricas

  • 🧪 Tests: 5/5
  • 📈 Cobertura: 41%
  • 🔍 Linting: 0 errores
  • 🎨 Formato: 100%

🌟 ¿Te gusta el proyecto?

Desarrollado con ❤️ usando Django + Python