# Arquitectura de la facturación centralizada UTILIA OS está diseñado para actuar como **centro fiscal** y **centro de cobro** de un ecosistema multi-aplicación. Esta página describe cómo encajan las piezas para que el equipo técnico pueda operar el sistema con conocimiento completo del modelo. Esta página es técnica y está pensada para personas del equipo de desarrollo o de operaciones que necesiten comprender los flujos en profundidad. ## Visión general Tres actores trabajan juntos: - **UTILIA OS**: numera las facturas (correlativo AEAT), firma VeriFactu, mantiene el estado fiscal, guarda el metadato de cada cobro y expone la API externa. - **Stripe**: gestiona los datos de tarjeta (PCI DSS), ejecuta los cobros, enruta el dinero a la cuenta bancaria de la organización y notifica por webhooks. - **Apps externas** (Línea, Azer y otras): crean facturas vía SDK, presentan la UI de pago al usuario final y reciben webhooks con eventos de facturación. ``` +-----------------------------+ | UTILIA OS | | (centro fiscal + cobro) | | - Numeración AEAT | | - Firma VeriFactu | | - PDF, portal, dashboard | | - StripeModule | +---+-----------------+-------+ | | +-------------+ +-------------+ | | v v +------------------+ +------------------------+ | Stripe | | Apps externas | | (Connect) | | (Línea, Azer, ...) | | - tarjetas | | - SDK JS / Python | | - PaymentIntent | | - UI propia de pago | | - webhooks | | - Webhooks INVOICE_* | +--------+---------+ +-----------+------------+ | | | webhook | webhook +-----------------> UTILIA <------------------+ (evento bus) ``` ## Stripe Connect Standard Cada organización de UTILIA conecta una cuenta Stripe propia mediante **Connect Standard**. UTILIA actúa como **plataforma**, pero los cobros se enrutan a la cuenta de la organización usando el header `Stripe-Account` en cada llamada a Stripe. Ventajas de este modelo: - El dinero llega directamente al banco de la organización, no al de UTILIA. - Cada organización mantiene independencia total sobre su cuenta de Stripe (panel, devoluciones, disputas). - Se soporta la visión SaaS multi-tenant: en el futuro cada organización cliente de UTILIA puede tener su propia cuenta Stripe. - UTILIA no asume riesgo financiero ni entra en cumplimiento PCI más allá del mínimo necesario (toda información sensible de tarjeta vive en Stripe). ### Variables de entorno Las secretas viven exclusivamente en el backend. El frontend recibe únicamente la `publishableKey` de la cuenta conectada a través del endpoint autenticado `GET /finance/stripe/publishable-key`. ## Modelo de datos UTILIA introduce nuevos modelos Prisma para representar el mundo Stripe y su vinculación con las entidades existentes: ### StripeAccount Una cuenta Stripe Connect por organización. ### StripeCustomer Un customer Stripe por `Client` del CRM **o** por `ExternalUser` de una app externa, exclusivamente. ### StripePaymentMethod Tarjetas (u otros métodos) guardadas. ### StripePaymentIntent Cada intento de cobro asociado a una factura. ### StripeWebhookEvent Auditoría y garantía de idempotencia de webhooks recibidos desde Stripe. ### Modificaciones en modelos existentes ## Aislamiento por tabla puente Para preservar el aislamiento entre el CRM del equipo y los usuarios finales de apps externas, UTILIA nunca mezcla `ExternalUser` con `Contact` o `Client`. En cambio, se usa una tabla puente `InvoiceExternalUserAccess` para los pocos casos donde una factura puede ser accesible por varios usuarios externos. La regla es simple: el CRM **no ve** los `ExternalUser` de ninguna app. Solo ve sus propios `Client`. Esto evita mezclar bases de datos de clientes distintas y mantiene la privacidad entre apps. ## Flujo: cobro desde el portal del cliente ``` [Cliente en portal] | | 1. Pulsa "Pagar ahora" v [Frontend portal] | | 2. POST /portal-invoices/:id/pay v [Backend UTILIA] | | 3. Valida permisos + estado factura | 4. Crea PaymentIntent on_session en Stripe | 5. Devuelve clientSecret v [Stripe Elements en portal] | | 6. Usa clientSecret | 7. stripe.confirmCardPayment() con PaymentElement v [Stripe] | | 8. Procesa cobro v [Stripe -> UTILIA webhook] | | 9. payment_intent.succeeded v [Backend UTILIA] | | 10. Verifica firma HMAC | 11. Registra en StripeWebhookEvent (idempotencia) | 12. Transacción: actualiza Invoice.paidAmount, estado -> PAID | 13. Emite evento invoice.paid.via_stripe v [Consumidores del evento] | | 14. Notificar cliente por correo | 15. Notificar por SSE al portal (UI en tiempo real) | 16. Si factura es de app externa -> webhook INVOICE_PAID v [Actualización visible en < 1 segundo] ``` ## Flujo: cobro automático de factura recurrente ``` [Cron diario 03:00] | | 1. RecurringInvoice vencen hoy v [RecurringInvoiceGenerator] | | 2. Crea Invoice con numeración AEAT | 3. Firma VeriFactu | 4. Revisa: ¿cliente tiene PaymentMethod predeterminado? v [Sí] --+ +-- [No: termina, ISSUED] | v 5. PaymentIntent off_session 6. idempotency_key = recurring: 7. confirm=true, off_session=true v [Stripe responde] | +-- succeeded --> webhook -> PAID +-- requires_action --> correo cliente -> portal completa 3DS +-- failed --> cola reintentos BullMQ (3/7/14 días) | +-- 3 fallos -> RecurringInvoice PAYMENT_FAILED + notificación al equipo ``` ## Flujo: factura creada por app externa, pagada desde la propia app ``` [Backend de la app externa Línea] | | 1. sdk.invoices.create(...) [SDK JS] v [UTILIA POST /external/v1/invoices] | | 2. Valida billingEnabled + tope amount | 3. Upsert ExternalUser (appId, externalId) | 4. Numera AEAT + firma VeriFactu | 5. Registra source=EXTERNAL_APP, externalAppId, externalUserId | 6. Emite invoice.created.external v [Línea: UI de "Mis facturas"] | | 7. sdk.invoices.list(userId) v [Línea: botón Pagar] | | 8. sdk.payments.payInvoice(invoiceId, userId) v [UTILIA POST /external/v1/invoices/:id/pay] | | 9. PaymentIntent on_session | 10. Devuelve clientSecret + publishableKey + stripeAccountId v [Frontend de Línea - React] | | 11. | | | | 12. stripe.confirmCardPayment() v [Stripe] | | 13. webhook payment_intent.succeeded v [Backend UTILIA] | | 14. Invoice -> PAID | 15. Emite webhook INVOICE_PAID firmado HMAC a Línea v [Línea recibe webhook] | | 16. Actualiza su base de datos local | 17. Notifica al usuario dentro de Línea ``` ## Webhooks entrantes desde Stripe UTILIA expone dos endpoints de webhook: - `POST /webhooks/stripe/platform` (eventos a nivel de plataforma: conexiones Connect nuevas, actualizaciones de cuenta). - `POST /webhooks/stripe/connect` (eventos por cuenta conectada: cobros, reembolsos, disputas). Cada webhook: 1. Lee el header `Stripe-Signature`. 2. Verifica la firma contra `STRIPE_CONNECT_WEBHOOK_SECRET` (o el de plataforma) usando el **raw body** (nunca el body ya parseado). 3. Guarda el evento en `StripeWebhookEvent` con `processed=false` (si ya existe `stripeEventId`, termina con `processed=true`). 4. Pasa al handler específico por tipo de evento. 5. Marca `processed=true` y `processedAt` al terminar. Esto hace el procesamiento **idempotente**: Stripe puede reintentar el mismo evento múltiples veces sin riesgo de duplicar efectos. ## Webhooks salientes hacia apps externas Para cada cambio relevante en una factura, UTILIA dispara webhooks firmados HMAC a las apps externas suscritas. Los eventos soportados son: - `INVOICE_CREATED`, `INVOICE_SENT`, `INVOICE_PAID`, `INVOICE_PARTIALLY_PAID`. - `INVOICE_PAYMENT_FAILED`, `INVOICE_OVERDUE`, `INVOICE_CANCELLED`, `INVOICE_REFUNDED`. - `PAYMENT_METHOD_ADDED`, `PAYMENT_METHOD_REMOVED`. Regla de enrutamiento: - Si la factura tiene `source = EXTERNAL_APP`, el webhook se envía **exclusivamente** a la app propietaria. - Si es nativa (`source = UTILIA_NATIVE`), se emite en broadcast a todas las apps suscritas. Consulte [Webhooks y payloads](/dashboard/docs/integraciones-api/webhooks-payloads-eventos) para el formato exacto. ## Dónde está el código relevante ## Permisos técnicos nuevos Los enums de Prisma añaden estos permisos al sistema RBAC existente: - `STRIPE_CONFIGURE`, `STRIPE_PAYMENTS_VIEW`, `STRIPE_PAYMENTS_REFUND`, `STRIPE_WEBHOOKS_MANAGE`. - `PAYMENT_METHODS_VIEW`, `PAYMENT_METHODS_MANAGE`. - `INVOICES_CHARGE`. - `PORTAL_PAY_INVOICES`, `PORTAL_MANAGE_PAYMENT_METHODS`. Se asignan a roles desde **Configuración → Usuarios y roles**. ## Siguiente paso Para entender cómo extender el sistema con eventos personalizados, revise el módulo `StripeWebhookHandlerService` y añada su handler al router de eventos. Para añadir soporte a otros métodos de pago (SEPA, Link), extienda `StripePaymentMethodType` en el enum y actualice el frontend de Stripe Elements.