201 lines
6.6 KiB
Markdown
201 lines
6.6 KiB
Markdown
# EPICA: EPIC-MGN-017 - Payments POS
|
|
|
|
## Metadata
|
|
|
|
| Campo | Valor |
|
|
|-------|-------|
|
|
| **ID** | EPIC-MGN-017 |
|
|
| **Nombre** | Payments POS (MercadoPago, Clip) |
|
|
| **Modulo** | payments |
|
|
| **Fase** | Fase 4 - SaaS Platform |
|
|
| **Prioridad** | P3 |
|
|
| **Estado** | Backlog |
|
|
| **Story Points** | 34 |
|
|
| **Sprint(s)** | Sprint 21-23 |
|
|
|
|
---
|
|
|
|
## Descripcion
|
|
|
|
Sistema de integracion con terminales de pago (MercadoPago y Clip) para procesar transacciones en punto de venta. Incluye registro de terminales por ubicacion, procesamiento de transacciones con tarjeta, reembolsos parciales/totales, webhooks para notificaciones y conciliacion automatica con generacion de asientos contables.
|
|
|
|
---
|
|
|
|
## Objetivo de Negocio
|
|
|
|
Proveer integracion de pagos que:
|
|
- Procese pagos fisicos y digitales en punto de venta
|
|
- Soporte multiples proveedores (MercadoPago, Clip)
|
|
- Automatice conciliacion con contabilidad
|
|
- Reduzca errores de captura manual
|
|
- Genere asientos contables automaticos
|
|
- Maneje comisiones de cada proveedor
|
|
|
|
---
|
|
|
|
## Stakeholders
|
|
|
|
| Rol | Nombre/Equipo | Responsabilidad |
|
|
|-----|---------------|-----------------|
|
|
| Product Owner | Equipo Producto | Definicion de proveedores y flujos |
|
|
| Tech Lead | Equipo Backend | Arquitectura de integraciones |
|
|
| Contador | Finanzas | Definicion de asientos contables |
|
|
| Cajeros | Operaciones | Uso diario, feedback UX |
|
|
|
|
---
|
|
|
|
## Historias de Usuario
|
|
|
|
| ID | Historia | Prioridad | SP | Estado |
|
|
|----|----------|-----------|-----|--------|
|
|
| US-MGN017-001 | Como admin, quiero registrar terminales de pago para identificar dispositivos | P0 | 3 | Backlog |
|
|
| US-MGN017-002 | Como admin, quiero configurar credenciales de MercadoPago (OAuth) | P0 | 5 | Backlog |
|
|
| US-MGN017-003 | Como admin, quiero configurar credenciales de Clip (API Keys) | P0 | 3 | Backlog |
|
|
| US-MGN017-004 | Como cajero, quiero procesar un pago con tarjeta para cobrar a cliente | P0 | 8 | Backlog |
|
|
| US-MGN017-005 | Como cajero, quiero procesar un reembolso para devolver a cliente | P0 | 5 | Backlog |
|
|
| US-MGN017-006 | Como sistema, quiero recibir webhooks de pagos para actualizar estados | P0 | 5 | Backlog |
|
|
| US-MGN017-007 | Como contador, quiero conciliar transacciones con extractos bancarios | P1 | 5 | Backlog |
|
|
|
|
**Total Story Points:** 34 SP
|
|
|
|
---
|
|
|
|
## Criterios de Aceptacion de la Epica
|
|
|
|
**Funcionales:**
|
|
- [ ] Multi-provider: MercadoPago (OAuth) y Clip (API Keys)
|
|
- [ ] Registro de terminales por ubicacion/almacen
|
|
- [ ] Procesamiento de pagos con tarjeta (credito, debito)
|
|
- [ ] Reembolsos parciales y totales
|
|
- [ ] Webhooks para notificaciones de estado de pago
|
|
- [ ] Conciliacion de transacciones con extractos bancarios
|
|
- [ ] Asientos contables automaticos (Bancos, Comisiones, Ventas)
|
|
- [ ] Manejo de comisiones por provider
|
|
|
|
**No Funcionales:**
|
|
- [ ] Timeout de transacciones < 30s
|
|
- [ ] Retry automatico (3 intentos) en fallos de red
|
|
- [ ] Logs detallados para debugging y auditoria
|
|
- [ ] PCI DSS compliance (no almacenar datos de tarjeta)
|
|
|
|
**Tecnicos:**
|
|
- [ ] Cobertura de tests > 80%
|
|
- [ ] Documentacion de APIs de proveedores
|
|
- [ ] Manejo de errores estandarizado
|
|
|
|
---
|
|
|
|
## Integraciones
|
|
|
|
### MercadoPago
|
|
- **Autenticacion:** OAuth 2.0
|
|
- **Webhooks:** Para notificaciones de estado
|
|
- **APIs:** Payments, Refunds, Terminals, Device Management
|
|
- **Comision:** ~3.49% + IVA
|
|
|
|
### Clip
|
|
- **Autenticacion:** API Keys
|
|
- **Estado:** Polling (no tiene webhooks nativos)
|
|
- **APIs:** Transactions, Refunds, Terminals
|
|
- **Comision:** ~3.6% + IVA
|
|
|
|
---
|
|
|
|
## Dependencias
|
|
|
|
**Esta epica depende de:**
|
|
| Epica/Modulo | Estado | Bloqueante |
|
|
|--------------|--------|------------|
|
|
| EPIC-MGN-004 Tenants | Ready | Si |
|
|
| EPIC-MGN-010 Financial | Backlog | Si (asientos contables) |
|
|
| EPIC-MGN-016 Billing | Backlog | No |
|
|
|
|
**Esta epica bloquea:**
|
|
| Epica/Modulo | Razon |
|
|
|--------------|-------|
|
|
| Verticales con POS | Necesitan procesamiento de pagos |
|
|
|
|
---
|
|
|
|
## Desglose Tecnico
|
|
|
|
**Database:**
|
|
- [ ] Schema: `integrations`
|
|
- [ ] Tablas: 7 (payment_providers, payment_credentials, terminals, transactions, refunds, webhook_logs, reconciliation_batches)
|
|
- [ ] Indices: Por terminal_id, status, created_at
|
|
- [ ] RLS Policies: Si (por tenant)
|
|
|
|
**Backend:**
|
|
- [ ] Modulo: `payments`
|
|
- [ ] Services: MercadoPagoService, ClipService, PaymentProcessor, ReconciliationService
|
|
- [ ] Controllers: PaymentsController, TerminalsController, WebhooksController
|
|
- [ ] Endpoints: 20+ (CRUD terminales, procesar pago, reembolso, webhooks)
|
|
- [ ] Jobs: ReconciliationJob (diario)
|
|
- [ ] Tests: 35+
|
|
|
|
**Frontend:**
|
|
- [ ] Paginas: 5 (Terminals, Transactions, Reconciliation, ProviderConfig, TransactionDetail)
|
|
- [ ] Componentes: TerminalCard, TransactionTable, RefundForm, PaymentForm, ReconciliationWizard
|
|
- [ ] Stores: 1 (paymentsStore)
|
|
|
|
---
|
|
|
|
## Riesgos
|
|
|
|
| Riesgo | Probabilidad | Impacto | Mitigacion |
|
|
|--------|--------------|---------|------------|
|
|
| Cambios en APIs de proveedores | Media | Alto | Versionado, abstraccion, monitoreo |
|
|
| Timeout en transacciones | Media | Alto | Retry, timeout configurable, fallback |
|
|
| Conciliacion incorrecta | Baja | Alto | Validaciones, alertas, revision manual |
|
|
| PCI DSS incumplimiento | Baja | Critico | No almacenar datos sensibles, usar tokens |
|
|
|
|
---
|
|
|
|
## Definition of Ready (DoR)
|
|
|
|
- [x] Historias de usuario definidas
|
|
- [x] Criterios de aceptacion claros
|
|
- [x] Dependencias identificadas
|
|
- [x] Estimacion completada
|
|
- [ ] Cuentas de sandbox de MercadoPago y Clip
|
|
- [ ] Catalogo de asientos contables definido
|
|
- [x] Sin bloqueadores activos
|
|
|
|
## Definition of Done (DoD)
|
|
|
|
- [ ] Codigo implementado y revisado
|
|
- [ ] Tests pasando (unit, integration)
|
|
- [ ] Integracion MercadoPago funcional
|
|
- [ ] Integracion Clip funcional
|
|
- [ ] Webhooks procesando correctamente
|
|
- [ ] Asientos contables generandose
|
|
- [ ] Documentacion actualizada
|
|
- [ ] Inventarios actualizados
|
|
- [ ] Demo realizada
|
|
- [ ] Product Owner aprobo
|
|
|
|
---
|
|
|
|
## Documentacion Relacionada
|
|
|
|
- Requerimientos: `docs/03-requerimientos/RF-payments/`
|
|
- User Stories: `docs/05-user-stories/mgn-017/`
|
|
- DDL Spec: `docs/04-modelado/database-design/DDL-SPEC-integrations_payments.md`
|
|
- API MercadoPago: https://www.mercadopago.com.mx/developers/es/docs
|
|
- API Clip: https://developer.clip.mx/
|
|
|
|
---
|
|
|
|
## Historial
|
|
|
|
| Fecha | Cambio | Autor |
|
|
|-------|--------|-------|
|
|
| 2025-12-05 | Creacion de epica | Requirements-Analyst |
|
|
| 2025-12-05 | Completado con Stakeholders, Riesgos, DoR/DoD | Requirements-Analyst |
|
|
|
|
---
|
|
|
|
**Creada por:** Requirements-Analyst
|
|
**Fecha:** 2025-12-05
|
|
**Ultima actualizacion:** 2025-12-05
|