Sistema de gestión de transferencias con evaluación de riesgo en tiempo real
- Descripción
- Características
- Arquitectura
- Stack Tecnológico
- Requisitos Previos
- Instalación
- Uso
- Endpoints de la API
- Testing
- Deployment
- Comandos Útiles
Financial Web API es una plataforma robusta para gestión de transferencias financieras con evaluación automática de riesgo. El sistema procesa pagos, evalúa el riesgo según reglas de negocio predefinidas y actualiza el estado de las operaciones en tiempo real.
Proporcionar un sistema escalable y mantenible que:
- ✅ Gestione operaciones de pago de manera eficiente
- ✅ Evalúe riesgos en tiempo real
- ✅ Mantenga un registro de acumulados diarios por cliente
- ✅ Proporcione APIs RESTful bien documentadas
- 🔐 Creación de Pagos: Registro de solicitudes de pago con validación
- ⚡ Evaluación de Riesgo: Análisis automático según reglas de negocio
- 📊 Consulta de Estado: Obtención del estado actual de cualquier pago
- 🔄 Procesamiento Asíncrono: Comunicación entre módulos mediante eventos
- 📈 Tracking Diario: Seguimiento de acumulados por cliente
- ❌ Rechazar si
amount > 2000 Bs - ✅ Aprobar si
amount ≤ 2000 Bs
- ❌ Rechazar si
acumulado diario > 5000 Bs - ✅ Aprobar si el nuevo pago no excede el límite diario
- 🏗️ Clean Architecture + Vertical Slices
- 🔌 Ports & Adapters (Hexagonal Architecture)
- 📦 Modular Monolith (fácil migración a microservicios)
- 🚀 Event-Driven (Kafka o InMemory Event Bus)
- 🧪 Test Coverage: 57.1% (95%+ en componentes críticos)
- 📝 Logging Estructurado (Serilog)
- 📚 Swagger/OpenAPI (documentación automática)
- 🐳 Containerizado (Docker & Docker Compose)
┌─────────────────────────────────────────────┐
│ API Layer (Controllers) │
├─────────────────────────────────────────────┤
│ Payments Module │ RiskEvaluation Module │
│ │ │
│ ┌─────────────┐ │ ┌─────────────┐ │
│ │ Application │ │ │ Application │ │
│ │ (CQRS) │ │ │ (CQRS) │ │
│ └─────────────┘ │ └─────────────┘ │
│ ┌─────────────┐ │ ┌─────────────┐ │
│ │ Domain │ │ │ Domain │ │
│ └─────────────┘ │ └─────────────┘ │
├─────────────────────────────────────────────┤
│ Infrastructure Layer │
│ (PostgreSQL, Kafka, Repositories) │
└─────────────────────────────────────────────┘
1. Client → POST /api/payments
2. API → CreatePaymentCommand
3. Handler → Save Payment (Status: Evaluating)
4. Handler → Publish to Kafka: "risk-evaluation-request"
5. Consumer → RiskEvaluationService
6. Service → Evaluate Risk (Business Rules)
7. Service → Update DailyPaymentSummary
8. Service → Publish to Kafka: "risk-evaluation-response"
9. Consumer → Update Payment Status (Accepted/Denied)
10. Client → GET /api/payments/{id} (Status: Accepted/Denied)
- ✅ SOLID principles
- ✅ DRY (Don't Repeat Yourself)
- ✅ KISS (Keep It Simple, Stupid)
- ✅ YAGNI (You Aren't Gonna Need It)
- ✅ Separation of Concerns
- ✅ Dependency Inversion
| Tecnología | Versión | Propósito |
|---|---|---|
| .NET | 8.0 | Framework principal |
| C# | 12.0 | Lenguaje de programación |
| PostgreSQL | 15 | Base de datos relacional |
| Entity Framework Core | 8.0 | ORM (Code-First) |
| Apache Kafka | 7.5.0 | Sistema de mensajería |
| Docker | Latest | Containerización |
| Serilog | Latest | Logging estructurado |
| FluentValidation | 11.9.0 | Validaciones |
| Swagger/OpenAPI | Latest | Documentación API |
| xUnit | 2.9.3 | Testing framework |
| Moq | 4.20.72 | Mocking framework |
| FluentAssertions | 8.8.0 | Assertions legibles |
- ✅ .NET 8 SDK - Descargar
- ✅ PostgreSQL 15+ - Descargar
- ✅ Docker Desktop (opcional) - Descargar
- ✅ Git - Descargar
- 🔧 Visual Studio 2022 o VS Code
- 🔧 Postman o Insomnia (para testing de APIs)
- 🔧 DBeaver o pgAdmin (para PostgreSQL)
- 🔧 Kafka UI (incluido en Docker Compose)
# 1. Clonar el repositorio
git clone https://github.com/hct-vladimir/FinancialWebAPI.git
cd FinancialWebAPI
# 2. Construir y levantar servicios
docker-compose -f docker/docker-compose.yml up -d
# 3. Esperar a que los servicios estén healthy (~30 segundos)
docker-compose -f docker/docker-compose.yml ps
# 4. La API estará disponible en:
# http://localhost:5000 (Swagger UI)
# http://localhost:8080 (Kafka UI)# 1. Clonar el repositorio
git clone https://github.com/hct-vladimir/FinancialWebAPI.git
cd FinancialWebAPI
# 2. Configurar PostgreSQL
# Crear base de datos: financialwapp
# Usuario: postgres
# Password: (tu password)
# 3. Actualizar appsettings.json
# Editar: src/FinancialWebAPI.Api/appsettings.json
# Configurar ConnectionString con tus credenciales
# 4. Aplicar migraciones
dotnet ef database update -p src/FinancialWebAPI.Infrastructure -s src/FinancialWebAPI.Api
# 5. Configurar InMemory Event Bus (sin Kafka)
# En appsettings.json:
# "UseInMemoryEventBus": true
# 6. Ejecutar la API
dotnet run --project src/FinancialWebAPI.Api
# 7. Abrir navegador
# http://localhost:5000# Si solo quieres Kafka en Docker pero ejecutar la API localmente:
# 1. Levantar Kafka
docker-compose -f docker-compose.kafka-only.yml up -d
# 2. Configurar appsettings.json
# "UseInMemoryEventBus": false
# 3. Ejecutar la API
dotnet run --project src/FinancialWebAPI.ApiNavega a: http://localhost:5000
Verás la documentación interactiva de la API donde puedes:
- 📖 Ver todos los endpoints disponibles
- 🧪 Probar los endpoints directamente
- 📋 Ver ejemplos de requests y responses
Request:
curl -X POST http://localhost:5000/api/payments \
-H "Content-Type: application/json" \
-d '{
"customerId": "cfe8b150-2f84-4a1a-bdf4-923b20e34973",
"serviceProviderId": "5fa3ab5c-645f-4cd5-b29e-5c5c116d7ea4",
"paymentMethodId": 2,
"amount": 1500.00
}'Response (201 Created):
{
"ExternalOperationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"Status": "Evaluating",
"Message": "Pago creado exitosamente..."
}Request:
curl http://localhost:5000/api/payments/a1b2c3d4-e5f6-7890-abcd-ef1234567890Response (200 OK):
{
"ExternalOperationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"Status": "Accepted",
"Amount": 1500.00,
"CustomerId": "cfe8b150-2f84-4a1a-bdf4-923b20e34973",
"CreatedAt": "2025-12-29T15:30:00Z",
"UpdatedAt": "2025-12-29T15:30:01Z"
}Crea una nueva solicitud de pago.
Request Body:
{
"customerId": "guid",
"serviceProviderId": "guid",
"paymentMethodId": 1,
"amount": 1500.00
}Validaciones:
- ✅
customerId: GUID válido y no vacío - ✅
serviceProviderId: GUID válido y no vacío - ✅
paymentMethodId: Mayor que 0 - ✅
amount: Entre 0.01 y 10,000 Bs
Responses:
201 Created: Pago creado exitosamente400 Bad Request: Validación fallida500 Internal Server Error: Error del servidor
Obtiene el estado de un pago.
Path Parameters:
externalOperationId: GUID del pago
Responses:
200 OK: Pago encontrado404 Not Found: Pago no existe500 Internal Server Error: Error del servidor
Verifica el estado de la API y sus dependencias.
Response:
{
"status": "Healthy",
"results": {
"postgresql": "Healthy"
}
}dotnet test# Generar cobertura
dotnet test --collect:"XPlat Code Coverage"
# Generar reporte HTML
reportgenerator "-reports:**/coverage.cobertura.xml" "-targetdir:coverage-report" "-reporttypes:Html"
# Abrir reporte
start coverage-report/index.htmlLine Coverage: 57.1% (327/572 líneas)
Branch Coverage: 70.0% (21/30 branches)
Method Coverage: 68.8% (64/93 métodos)
Componentes Críticos:
✅ Business Rules: 95.3%
✅ Validations: 100%
✅ Handlers: 100%
# Solo tests de Payments
dotnet test tests/FinancialWebAPI.Modules.Payments.Tests
# Solo tests de RiskEvaluation
dotnet test tests/FinancialWebAPI.Modules.RiskEvaluation.TestsLa aplicación usa Serilog para logging estructurado:
Ubicación de logs:
- 📝 Console: Logs en tiempo real
- 📝 File:
logs/log-YYYYMMDD.txt(rotación diaria)
Niveles de log:
Information: Operaciones normalesWarning: Situaciones inusualesError: Errores que requieren atenciónFatal: Errores críticos
Ejemplo de log:
[15:30:00 INF] POST /api/payments - Cliente: cfe8b150-..., Monto: 1500
[15:30:00 INF] Pago creado exitosamente - ExternalOperationId: a1b2c3d4-...
[15:30:01 INF] Payment a1b2c3d4-... updated to status: Accepted
Docker: docker-compose logs -f financial-api
Endpoint de health check: http://localhost:5000/health
Verifica:
- ✅ PostgreSQL conectado
- ✅ Kafka disponible
- ✅ API respondiendo
Para producción, considera:
- Variables de Entorno: Usa variables de entorno en vez de appsettings.json
- Secrets: Usa Docker Secrets o Azure Key Vault para passwords
- HTTPS: Configura certificados SSL/TLS válidos
- Escalabilidad: Usa réplicas de la API con load balancer
- Monitoring: Integra con Prometheus + Grafana o Application Insights
- Backups: Configura backups automáticos de PostgreSQL
Ejemplo de pipeline (GitHub Actions):
name: Deploy to Production
on:
push:
branches: [ main ]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build Docker image
run: docker build -t financial-api:latest .
- name: Push to registry
run: docker push financial-api:latest
- name: Deploy
run: kubectl apply -f k8s/Las contribuciones son bienvenidas. Por favor:
- Fork el repositorio
- Crea una rama para tu feature (
git checkout -b feature/AmazingFeature) - Commit tus cambios (
git commit -m 'Add some AmazingFeature') - Push a la rama (
git push origin feature/AmazingFeature) - Abre un Pull Request
- Seguir principios SOLID
- Agregar tests unitarios
- Documentar métodos públicos con XML comments
- Usar logging estructurado
- Mantener Clean Architecture
# Desarrollo
dotnet build # Compilar solución
dotnet run --project src/FinancialWebAPI.Api # Ejecutar API
dotnet test # Ejecutar tests
dotnet watch run --project src/FinancialWebAPI.Api # Hot reload
# Entity Framework
dotnet ef migrations add MigrationName -p src/FinancialWebAPI.Infrastructure -s src/FinancialWebAPI.Api
dotnet ef database update -p src/FinancialWebAPI.Infrastructure -s src/FinancialWebAPI.Api
dotnet ef migrations list -p src/FinancialWebAPI.Infrastructure -s src/FinancialWebAPI.Api
# Docker
docker-compose build # Build imágenes
docker-compose up -d # Iniciar servicios
docker-compose down # Detener servicios
docker-compose down -v # Detener y limpiar volúmenes
docker-compose logs -f financial-api # Ver logs
docker-compose ps # Ver estado
# Limpieza
docker system prune -a # Limpiar todo Docker
dotnet clean # Limpiar build artifacts- Documentación Técnica: Ver
Instructions.md - Docker: Ver
DOCKER_README.md - Pasos de Implementación: Ver archivos
PASO_X_COMPLETADO.md - InMemory Event Bus: Ver
INMEMORY_EVENTBUS_GUIDE.md - Kafka Documentation: https://kafka.apache.org/documentation/
- EF Core Documentation: https://learn.microsoft.com/ef/core/
- .NET 8 Documentation: https://learn.microsoft.com/dotnet/
Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.
- Vladimir Castro - Desarrollo Inicial - hct-vladimir
- Clean Architecture por Robert C. Martin
- Vertical Slice Architecture por Jimmy Bogard
- Patrón Modular Monolith
- Comunidad de .NET
Para soporte y preguntas:
- 📧 Email: support@financialapi.com
- 🐛 Issues: GitHub Issues
- 💭 Discussions: GitHub Discussions
¡Gracias por usar Financial Web API! 🚀
Última actualización: 29 de Diciembre de 2025