clinica-dental/docs/04-fase-saas/MGN-016-billing/README.md

---
id: MGN-016-billing
title: Modulo Billing - Suscripciones para Clinica Dental
type: ModuleOverview
status: Draft
version: 1.0.0
created_date: 2026-01-13
updated_date: 2026-01-13
module: billing
priority: P0
normativas: [NOM-013-SSA2-2015, CFDI-4.0]
---

# MGN-016: Billing - Sistema de Facturacion y Suscripciones Dentales

## Resumen Ejecutivo

El modulo Billing implementa el sistema de facturacion y suscripciones para consultorios y clinicas dentales, integrando Stripe Billing como proveedor de pagos. Permite gestionar suscripciones por tipo de consultorio (individual, grupal, centro dental), periodos de prueba, upgrades/downgrades y facturacion automatica con soporte para CFDI 4.0.

---

## Objetivos

### Objetivo Principal

Implementar un sistema de billing completo para clinicas dentales que permita:
- Suscripciones mensuales y anuales por tipo de consultorio
- Planes diferenciados por numero de sillones dentales
- Facturacion automatica recurrente con CFDI 4.0
- Portal de cliente self-service via Stripe

### Objetivos Secundarios

- Sincronizacion bidireccional con Stripe via webhooks
- Soporte para periodos de prueba (14 dias)
- Manejo de pagos fallidos y dunning
- Historial de facturas accesible para clinicas
- Facturacion adicional por servicios especiales

---

## Planes para Clinica Dental

| Plan | Precio/mes | Sillones | Usuarios | Storage | Features |
|------|------------|----------|----------|---------|----------|
| **Consultorio** | $499 MXN | 1 | 3 | 5 GB | Odontograma, Citas, Expedientes |
| **Clinica** | $1,499 MXN | 5 | 15 | 25 GB | + Ortodoncia, Radiografias, Reportes |
| **Centro Dental** | $3,999 MXN | Ilimitado | Ilimitado | 100 GB | + IA, WhatsApp, Multi-sucursal |

---

## Alcance

### Incluido (In Scope)

| Caracteristica | Descripcion | Prioridad |
|----------------|-------------|-----------|
| Stripe Billing | Integracion completa con Stripe | P0 |
| Planes dentales | Consultorio, Clinica, Centro | P0 |
| Suscripciones | Crear, actualizar, cancelar | P0 |
| Webhooks Stripe | Recibir y procesar eventos | P0 |
| Portal cliente | Redirect a Stripe Customer Portal | P0 |
| CFDI 4.0 | Generacion de facturas fiscales | P0 |
| Pagos OXXO | Soporte para pago en efectivo | P1 |
| Invoices | Historial con PDF | P1 |

### Excluido (Out of Scope)

| Caracteristica | Razon | Fase Futura |
|----------------|-------|-------------|
| Multi-currency | Solo MXN por ahora | Fase 2 |
| Servicios adicionales | Pagos one-time | Fase 2 |
| Facturacion por tratamiento | Complejidad | Fase 3 |

---

## Arquitectura

### Diagrama de Integracion

```
+-------------------+     +-------------------+     +-------------------+
|   Frontend        |---->| Billing API       |---->| Stripe API        |
|   (Checkout)      |     | (NestJS)          |     |                   |
+-------------------+     +-------------------+     +-------------------+
                                  |                         |
                          +-------+---------+               |
                          |                 |               v
                    +----------+      +-----------+  +-------------+
                    | Plans DB |      | Invoices  |  | Webhooks    |
                    | (Dental) |      | + CFDI    |  | (events)    |
                    +----------+      +-----------+  +-------------+
                                            |
                                            v
                                      +-----------+
                                      | SAT/CFDI  |
                                      | Timbrado  |
                                      +-----------+
```

### Flujo de Suscripcion Dental

```
1. Dentista selecciona plan en frontend
   |
2. Frontend llama POST /billing/checkout
   |
3. Backend crea Checkout Session en Stripe
   |
4. Backend retorna URL de Stripe Checkout
   |
5. Frontend redirige a Stripe Checkout
   |
6. Dentista paga (tarjeta o OXXO)
   |
7. Stripe envia webhook: checkout.session.completed
   |
8. Backend crea/actualiza subscription en DB
   |
9. Backend activa features del plan (sillones, odontograma, etc.)
   |
10. Clinica operativa con funcionalidades activas
```

---

## Facturacion CFDI 4.0

### Datos Requeridos

- RFC de la clinica
- Razon social
- Regimen fiscal
- Uso CFDI (G03 - Gastos en general)
- Codigo postal fiscal

### Flujo de Facturacion

```
1. Stripe cobra suscripcion
   |
2. Webhook notifica pago exitoso
   |
3. Backend genera pre-CFDI
   |
4. Envia a PAC para timbrado
   |
5. Almacena XML y PDF
   |
6. Notifica a clinica via email
```

---

## Dependencias

### Modulos Prerequisito

| Modulo | Tipo | Descripcion |
|--------|------|-------------|
| MGN-001-auth | Requerido | Autenticacion JWT |
| MGN-002-users | Requerido | Usuario owner clinica |
| MGN-004-tenants | Requerido | Contexto multi-tenant |
| MGN-007-audit | Requerido | Logs de cambios |

### Servicios Externos

| Servicio | Proposito | Requerido |
|----------|-----------|-----------|
| Stripe | Billing y pagos | Si |
| PAC CFDI | Timbrado facturas | Si |
| Redis | Cache de planes | Opcional |

---

## Seguridad y Normativas

| Medida | Implementacion |
|--------|----------------|
| PCI Compliance | No almacenar datos de tarjeta |
| Webhook Signature | Verificar Stripe-Signature |
| CFDI Seguro | Almacenar XMLs firmados |
| Access Control | Solo owner gestiona billing |
| NOM-013-SSA2-2015 | Registro de servicios |
| LFPDPPP | Proteccion datos clinica |

---

## Configuracion

### Variables de Entorno

```bash
# Stripe
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_PUBLISHABLE_KEY=pk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

# Billing Config Dental
BILLING_TRIAL_DAYS=14
BILLING_DEFAULT_PLAN=consultorio
BILLING_SUCCESS_URL=https://clinica.ejemplo.com/billing/success
BILLING_CANCEL_URL=https://clinica.ejemplo.com/billing/cancel

# CFDI
CFDI_PAC_URL=https://pac.ejemplo.com
CFDI_PAC_USER=xxx
CFDI_PAC_PASSWORD=xxx
```

---

## Indices

- [Requerimientos Funcionales](requerimientos/INDICE-RF-BILLING.md)
- [Especificaciones Tecnicas](especificaciones/INDICE-ET-BILLING.md)
- [Historias de Usuario](historias-usuario/INDICE-US-BILLING.md)
- [Trazabilidad](implementacion/TRACEABILITY.yml)

---

## Referencias

- [erp-core/MGN-016-billing](../../../../../erp-core/docs/04-fase-saas/MGN-016-billing/) - Origen
- [Stripe Billing Docs](https://stripe.com/docs/billing) - Documentacion oficial
- [SAT CFDI 4.0](https://www.sat.gob.mx/consultas/42214/cfdi-version-4.0) - Especificacion

---

*Modulo: MGN-016-billing | Clinica Dental | Version: 1.0.0*
*Propagado desde erp-core via erp-clinicas*
*Actualizado: 2026-01-13*