Integraciones - Portal de Clientes

Integraciones con sistemas externos y servicios existentes de Sistema Bautista.

Estado: Planificado

Payment Gateways

Arquitectura multi-gateway basada en el patron Adapter que soporta multiples proveedores de pago online. Cada tenant tiene un gateway configurado en deploy time. La seleccion se realiza via PaymentGatewayFactory.

Gateways soportados:

Gateway	Estado	Documentacion
Pago TIC (PayPerTIC)	Primer adapter	paypertic.md
MercadoPago	Planificado	mercadopago.md

Interfaz estandar: Todos los gateways implementan PaymentGatewayAdapter con 6 metodos: createPayment, processWebhook, validateWebhook, getPaymentStatus, cancelPayment, refundPayment. Ver arquitectura completa.

Caracteristicas:

• Patron Adapter para abstraer diferencias entre gateways
• Factory pattern para seleccion per-tenant
• DTOs estandar (PaymentRequest, PaymentResponse, WebhookResult, etc.)
• Estados normalizados: PENDING, ISSUED, APPROVED, REJECTED, REFUNDED, CANCELLED
• Webhook validation (HMAC-SHA256 o Bearer token segun gateway)
• Idempotencia con external_id
• Pago automatico: webhook con estado APPROVED crea recibo en CtaCte sin intervencion manual

Flujo de Pago Estandar

El pago es completamente automatico. No requiere intervencion manual para acreditar.

sequenceDiagram
    participant C as Cliente
    participant FE as Frontend (Docker)
    participant BE as Backend (compartido)
    participant GW as Gateway (Pago TIC / MercadoPago)
    participant CC as CtaCte

    C->>FE: Selecciona facturas, click "Pagar"
    FE->>BE: POST /portal/pagos/iniciar
    BE->>BE: PaymentGatewayFactory.create(tenant_gateway)
    BE->>GW: adapter.createPayment(PaymentRequest)
    GW-->>BE: PaymentResponse {checkoutUrl}
    BE-->>FE: redirect_url
    FE->>C: Redirige al checkout del gateway

    C->>GW: Completa el pago
    GW-->>C: Redirige a returnUrl

    GW->>BE: POST /portal/pagos/webhook
    BE->>BE: adapter.validateWebhook()
    BE->>BE: adapter.processWebhook() -> WebhookResult

    alt status == APPROVED
        BE->>CC: Crear recibo automaticamente
        BE->>BE: Actualizar portal_payments
    end

El recibo se crea automaticamente cuando el webhook confirma el pago aprobado. El cliente no necesita hacer nada mas despues de pagar en el gateway.

Cupones de Pago

La generacion de cupones de pago reutiliza el servicio existente CuponPagoService del sistema. No se implementa logica nueva de cupones para el portal.

Endpoints expuestos al portal:

• GET /portal/cupones/cliente/{id} - Listar cupones del cliente
• POST /portal/cupones/generar - Generar nuevo cupon (delega a CuponPagoService existente)

Funcionalidad reutilizada:

• Generacion de codigo de barras ITF-14
• Validacion de cupones
• Listado con paginacion
• Generacion de PDF

Seguridad

Webhook Validation

• Cada gateway implementa su propia validacion: HMAC-SHA256 (MercadoPago), Bearer token (Pago TIC)
• Verificacion de idempotencia con external_id
• Rate limiting en endpoints de webhook

Configuracion por Tenant

Cada tenant tiene su propia configuracion de gateway (credenciales) en la tabla ini.sistemas. La URL del webhook es unica por despliegue de backend, no por tenant. El backend identifica el tenant a partir del external_id del pago via portal_payments.

Ver ADR-011 - Resolucion de tenant en webhooks.

Ver tambien

• Arquitectura de Medios de Pago -- Interfaz estandar, DTOs, Factory
• Pago TIC (PayPerTIC) -- Primer adapter
• MercadoPago -- Adapter planificado
• Deployment