michangarrito/docs/01-epicas/MCH-027-integracion-sat.md

---
id: EPIC-MCH-027
type: Epic
title: "MCH-027: Integracion SAT"
code: MCH-027
status: Completado
status_real: "Mock"
status_nota: "Implementacion mock - Sin integracion real con PAC"
phase: 7
priority: P3
story_points: 55
created_at: 2026-01-10
updated_at: 2026-01-17
simco_version: "4.0.1"
dependencies:
  blocks: []
  depends_on: []
---

# MCH-027: Integracion SAT

## Metadata
- **Codigo:** MCH-027
- **Fase:** 7 - Expansion (Futuro)
- **Prioridad:** P3
- **Estado:** Parcial (Mock)
- **Estado Real:** Implementacion mock - UUID generado localmente, sin timbrado SAT
- **Story Points:** 55
- **Sprint Asignado:** Sprint 5 (Integraciones Reales)
- **Requiere:** Contrato con PAC (Facturapi recomendado)
- **Fecha estimada:** Sprint 19+

## Descripcion

Integracion con el SAT (Servicio de Administracion Tributaria) de Mexico para facturacion electronica simplificada (CFDI): emision de facturas a clientes, cancelacion, y reportes fiscales.

## Objetivos

1. Emision de CFDI (facturas)
2. Cancelacion de facturas
3. Envio automatico al cliente
4. Reportes para contabilidad
5. Cumplimiento normativo

## Alcance

### Incluido
- CFDI de Ingreso (factura de venta)
- CFDI de Egreso (nota de credito)
- Envio por email al cliente
- Descarga de XML y PDF
- Reporte mensual

### Excluido
- CFDI de Nomina
- CFDI de Pagos complejos
- Declaraciones automaticas
- Contabilidad electronica

## Tipos de Comprobante

| Tipo | Uso | Cuando |
|------|-----|--------|
| Ingreso | Factura de venta | Cliente solicita factura |
| Egreso | Nota de credito | Devolucion o descuento |

## Flujo de Facturacion

### Solicitud de Factura (Post-venta)
```
1. Cliente solicita factura via WhatsApp
   "Necesito factura del ticket #123"

2. Bot responde:
   "Para tu factura necesito:
   - RFC
   - Razon social
   - Codigo postal
   - Uso CFDI (ej: Gastos en general)"

3. Cliente proporciona datos

4. Sistema genera CFDI:
   - Timbra con PAC
   - Genera PDF
   - Envia por email
   - Guarda en historial

5. Bot confirma:
   "Tu factura ha sido enviada a tu email"
```

### Factura desde POS
```
1. Al finalizar venta
2. Empleado pregunta: "¿Requiere factura?"
3. Si: captura datos fiscales
4. Se genera CFDI
5. Se entrega ticket + factura
```

## Modelo de Datos

### Tablas (schema: billing)

**invoices** (CFDI)
- id, tenant_id, sale_id, type (ingreso/egreso)
- uuid (folio fiscal), serie, folio
- customer_rfc, customer_name, customer_zip
- uso_cfdi, payment_method, payment_form
- subtotal, iva, total
- xml_url, pdf_url, status
- stamped_at, cancelled_at

**invoice_items**
- id, invoice_id, product_id
- clave_prod_serv, clave_unidad
- description, quantity, unit_price
- discount, iva, total

**tax_configs** (por tenant)
- id, tenant_id, rfc, razon_social
- regimen_fiscal, codigo_postal
- pac_provider, pac_credentials

## Claves SAT Requeridas

### Uso CFDI Comunes
| Clave | Descripcion |
|-------|-------------|
| G01 | Adquisicion de mercancias |
| G03 | Gastos en general |
| P01 | Por definir |

### Forma de Pago
| Clave | Descripcion |
|-------|-------------|
| 01 | Efectivo |
| 04 | Tarjeta de credito |
| 28 | Tarjeta de debito |
| 99 | Por definir |

### Metodo de Pago
| Clave | Descripcion |
|-------|-------------|
| PUE | Pago en una sola exhibicion |
| PPD | Pago en parcialidades |

## Integracion con PAC

### Proveedores PAC Recomendados
- Facturapi (simple, buena API)
- SW Sapien
- Finkok

### API Facturapi (Ejemplo)
```typescript
const facturapi = require('facturapi');

const invoice = await facturapi.invoices.create({
  customer: {
    legal_name: 'Juan Perez',
    tax_id: 'XAXX010101000',
    tax_system: '601',
    address: { zip: '06600' }
  },
  items: [{
    product: {
      description: 'Coca-Cola 600ml',
      product_key: '50202301', // Bebidas
      price: 18,
      tax_included: true
    }
  }],
  payment_form: '01', // Efectivo
  use: 'G03' // Gastos generales
});
```

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /invoices | Crear factura |
| GET | /invoices/:id | Obtener factura |
| GET | /invoices/:id/pdf | Descargar PDF |
| GET | /invoices/:id/xml | Descargar XML |
| POST | /invoices/:id/cancel | Cancelar factura |
| POST | /invoices/:id/send | Reenviar por email |
| GET | /invoices/report | Reporte mensual |

## UI Components

### InvoiceRequestForm
- RFC con validacion
- Razon social
- Codigo postal
- Uso CFDI (dropdown)
- Email para envio

### InvoiceHistory
- Lista de facturas emitidas
- Filtros por periodo
- Acciones: ver, descargar, cancelar

### InvoicePreview
- Vista previa del PDF
- Datos fiscales
- Botones: descargar, enviar

## Historias de Usuario

### MCH-US-260: Emision de CFDI de Ingreso
**Story Points:** 8

**Como** dueno de negocio
**Quiero** emitir facturas electronicas (CFDI de Ingreso) cuando un cliente lo solicite
**Para** cumplir con las obligaciones fiscales y dar al cliente su comprobante oficial

#### Criterios de Aceptacion
- [CA-260-1] El sistema genera un CFDI valido con estructura XML conforme al esquema SAT vigente
- [CA-260-2] El CFDI incluye todos los datos fiscales requeridos: RFC, razon social, regimen fiscal, uso CFDI
- [CA-260-3] Los productos facturados incluyen clave de producto/servicio SAT y clave de unidad
- [CA-260-4] El timbrado se realiza exitosamente con el PAC configurado
- [CA-260-5] El UUID (folio fiscal) se almacena correctamente en la base de datos
- [CA-260-6] El estatus de la factura se actualiza a "Timbrada" tras el proceso exitoso

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-260-01 | Implementar entity Invoice con todos los campos SAT | 3h |
| MCH-TT-260-02 | Crear servicio de construccion de XML CFDI | 4h |
| MCH-TT-260-03 | Implementar validaciones de datos fiscales | 2h |
| MCH-TT-260-04 | Integrar con servicio de timbrado PAC | 4h |
| MCH-TT-260-05 | Crear endpoint POST /invoices | 2h |
| MCH-TT-260-06 | Implementar tests unitarios y de integracion | 3h |

---

### MCH-US-261: Emision de CFDI de Egreso
**Story Points:** 5

**Como** dueno de negocio
**Quiero** emitir notas de credito (CFDI de Egreso) cuando haya devoluciones o descuentos
**Para** reflejar correctamente las operaciones fiscales y mantener la contabilidad al dia

#### Criterios de Aceptacion
- [CA-261-1] El CFDI de Egreso referencia correctamente al CFDI de Ingreso original (UUID)
- [CA-261-2] El tipo de relacion SAT se especifica correctamente (01-Nota de credito)
- [CA-261-3] Los montos del egreso corresponden a la devolucion o descuento aplicado
- [CA-261-4] El sistema valida que el CFDI original exista y este vigente
- [CA-261-5] El egreso se timbra correctamente con el PAC

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-261-01 | Extender modelo Invoice para tipo Egreso | 2h |
| MCH-TT-261-02 | Implementar logica de relacion entre CFDIs | 3h |
| MCH-TT-261-03 | Crear validaciones especificas para egresos | 2h |
| MCH-TT-261-04 | Ajustar servicio de timbrado para egresos | 2h |
| MCH-TT-261-05 | Implementar tests para flujo de egreso | 2h |

---

### MCH-US-262: Integracion con PAC
**Story Points:** 8

**Como** sistema
**Quiero** conectarme con un Proveedor Autorizado de Certificacion (PAC)
**Para** timbrar los CFDIs y obtener el sello digital del SAT

#### Criterios de Aceptacion
- [CA-262-1] El sistema soporta al menos un PAC (Facturapi como principal)
- [CA-262-2] Las credenciales del PAC se almacenan encriptadas por tenant
- [CA-262-3] El sistema maneja errores de timbrado con mensajes claros
- [CA-262-4] Se implementa retry automatico ante fallas temporales del PAC
- [CA-262-5] Los tiempos de respuesta del PAC se registran para monitoreo
- [CA-262-6] El sistema puede funcionar en modo sandbox para pruebas

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-262-01 | Crear interfaz abstracta PacProvider | 2h |
| MCH-TT-262-02 | Implementar FacturapiProvider | 4h |
| MCH-TT-262-03 | Configurar manejo de credenciales encriptadas | 3h |
| MCH-TT-262-04 | Implementar circuit breaker y retry logic | 3h |
| MCH-TT-262-05 | Crear modo sandbox/pruebas | 2h |
| MCH-TT-262-06 | Implementar logging y metricas de PAC | 2h |

---

### MCH-US-263: Generacion de PDF de Factura
**Story Points:** 5

**Como** cliente
**Quiero** recibir mi factura en formato PDF legible
**Para** tener un comprobante imprimible y facil de leer

#### Criterios de Aceptacion
- [CA-263-1] El PDF incluye todos los datos fiscales del emisor y receptor
- [CA-263-2] Se muestra el desglose de productos con claves SAT
- [CA-263-3] El PDF incluye codigo QR con URL de verificacion SAT
- [CA-263-4] Se muestra la cadena original y sello digital
- [CA-263-5] El diseno es profesional y cumple con requisitos SAT
- [CA-263-6] El PDF se genera en menos de 3 segundos

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-263-01 | Disenar template de factura PDF | 3h |
| MCH-TT-263-02 | Implementar servicio de generacion PDF | 4h |
| MCH-TT-263-03 | Integrar generacion de codigo QR | 2h |
| MCH-TT-263-04 | Crear endpoint GET /invoices/:id/pdf | 1h |
| MCH-TT-263-05 | Optimizar rendimiento de generacion | 2h |

---

### MCH-US-264: Envio Automatico por Email
**Story Points:** 5

**Como** cliente
**Quiero** recibir mi factura automaticamente por email
**Para** tenerla disponible sin tener que solicitarla nuevamente

#### Criterios de Aceptacion
- [CA-264-1] El email incluye el XML como adjunto
- [CA-264-2] El email incluye el PDF como adjunto
- [CA-264-3] El asunto del email identifica claramente la factura (serie, folio)
- [CA-264-4] El cuerpo del email incluye resumen de la factura
- [CA-264-5] Se registra el envio exitoso en la base de datos
- [CA-264-6] El sistema permite reenviar la factura bajo demanda

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-264-01 | Disenar template de email para factura | 2h |
| MCH-TT-264-02 | Implementar servicio de envio con adjuntos | 3h |
| MCH-TT-264-03 | Crear endpoint POST /invoices/:id/send | 1h |
| MCH-TT-264-04 | Implementar cola de envios para alto volumen | 3h |
| MCH-TT-264-05 | Registrar tracking de envios | 2h |

---

### MCH-US-265: Cancelacion de Facturas
**Story Points:** 8

**Como** dueno de negocio
**Quiero** cancelar facturas emitidas por error o devolucion
**Para** mantener mi contabilidad correcta ante el SAT

#### Criterios de Aceptacion
- [CA-265-1] La cancelacion se envia al SAT a traves del PAC
- [CA-265-2] Se requiere motivo de cancelacion segun catalogo SAT
- [CA-265-3] Para facturas >$1000, se gestiona el proceso de aceptacion del receptor
- [CA-265-4] El estatus de cancelacion se actualiza correctamente (En proceso, Cancelada)
- [CA-265-5] Se genera acuse de cancelacion cuando aplica
- [CA-265-6] El sistema consulta periodicamente el estatus de cancelaciones pendientes

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-265-01 | Implementar endpoint POST /invoices/:id/cancel | 2h |
| MCH-TT-265-02 | Integrar API de cancelacion del PAC | 4h |
| MCH-TT-265-03 | Implementar flujo de aceptacion de receptor | 4h |
| MCH-TT-265-04 | Crear job de consulta de estatus de cancelaciones | 3h |
| MCH-TT-265-05 | Implementar notificaciones de cambio de estatus | 2h |
| MCH-TT-265-06 | Crear tests para flujos de cancelacion | 3h |

---

### MCH-US-266: Solicitud de Factura via WhatsApp
**Story Points:** 8

**Como** cliente
**Quiero** solicitar mi factura a traves de WhatsApp
**Para** obtenerla de forma rapida y conversacional sin llamar al negocio

#### Criterios de Aceptacion
- [CA-266-1] El bot reconoce la intencion de solicitar factura
- [CA-266-2] El bot solicita los datos fiscales requeridos de forma conversacional
- [CA-266-3] El sistema valida el RFC en formato y estructura
- [CA-266-4] El bot confirma los datos antes de generar la factura
- [CA-266-5] La factura se genera y se notifica al cliente el envio por email
- [CA-266-6] El bot maneja errores de forma amigable (RFC invalido, ticket no encontrado)

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-266-01 | Disenar flujo conversacional de facturacion | 3h |
| MCH-TT-266-02 | Implementar intent de solicitud de factura | 2h |
| MCH-TT-266-03 | Crear colectores de datos fiscales | 4h |
| MCH-TT-266-04 | Integrar validacion de RFC | 2h |
| MCH-TT-266-05 | Conectar con servicio de facturacion | 3h |
| MCH-TT-266-06 | Implementar manejo de errores conversacional | 2h |

---

### MCH-US-267: Reportes Fiscales Mensuales
**Story Points:** 8

**Como** contador del negocio
**Quiero** generar reportes mensuales de facturas emitidas
**Para** facilitar la declaracion de impuestos y conciliacion fiscal

#### Criterios de Aceptacion
- [CA-267-1] El reporte incluye todas las facturas del periodo (ingresos y egresos)
- [CA-267-2] Se muestra desglose de IVA trasladado y retenido
- [CA-267-3] El reporte se puede exportar en formato Excel y PDF
- [CA-267-4] Se incluye totales por tipo de comprobante
- [CA-267-5] El reporte incluye facturas canceladas marcadas como tal
- [CA-267-6] Se puede filtrar por serie, estatus y tipo de CFDI

#### Tareas
| ID | Tarea | Estimacion |
|----|-------|------------|
| MCH-TT-267-01 | Disenar estructura del reporte fiscal | 2h |
| MCH-TT-267-02 | Implementar consultas agregadas de facturas | 4h |
| MCH-TT-267-03 | Crear endpoint GET /invoices/report | 2h |
| MCH-TT-267-04 | Implementar exportacion a Excel | 3h |
| MCH-TT-267-05 | Implementar exportacion a PDF | 2h |
| MCH-TT-267-06 | Crear UI de reportes fiscales | 4h |
| MCH-TT-267-07 | Implementar filtros y parametros del reporte | 2h |

---

### Resumen de Historias de Usuario

| ID | Historia | Story Points | Prioridad |
|----|----------|--------------|-----------|
| MCH-US-260 | Emision de CFDI de Ingreso | 8 | Alta |
| MCH-US-261 | Emision de CFDI de Egreso | 5 | Alta |
| MCH-US-262 | Integracion con PAC | 8 | Alta |
| MCH-US-263 | Generacion de PDF de Factura | 5 | Alta |
| MCH-US-264 | Envio Automatico por Email | 5 | Media |
| MCH-US-265 | Cancelacion de Facturas | 8 | Alta |
| MCH-US-266 | Solicitud de Factura via WhatsApp | 8 | Media |
| MCH-US-267 | Reportes Fiscales Mensuales | 8 | Media |
| **Total** | | **55** | |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| DB Schema | Completado | `database/schemas/15-invoices.sql` |
| invoices.module | Completado | `modules/invoices/` |
| Entities | Completado | `modules/invoices/entities/` |
| Service | Completado | `modules/invoices/invoices.service.ts` |
| Controller | Completado | `modules/invoices/invoices.controller.ts` |
| PAC integration | Mock | Integrado en servicio |
| Invoice PDF generator | Pendiente | `services/invoice-pdf.service.ts` |
| WhatsApp invoice flow | Pendiente | `whatsapp-service/flows/` |
| Invoice UI | Completado | `pages/Invoices.tsx` |

## Dependencias

### Depende de
- MCH-004 (Sales - datos de venta)
- MCH-014 (Customers - datos fiscales)
- Cuenta SAT del negocio (e.firma)
- Contrato con PAC

### Bloquea a
- Ninguno

## Criterios de Aceptacion

- [ ] CFDI se genera correctamente
- [ ] XML cumple con esquema SAT
- [ ] PDF se genera legible
- [ ] Email se envia al cliente
- [ ] Cancelacion funciona
- [ ] Reporte mensual se genera

## Configuracion por Tenant

```typescript
{
  billing: {
    enabled: true,
    pac_provider: 'facturapi',
    pac_api_key: 'encrypted...',
    rfc: 'XAXX010101000',
    razon_social: 'Mi Tiendita SA de CV',
    regimen_fiscal: '601',
    codigo_postal: '06600',
    serie: 'A',
    auto_send_email: true
  }
}
```

## Costos

| Concepto | Costo Estimado |
|----------|----------------|
| PAC por timbrado | ~$2-4 MXN/factura |
| Certificado e.firma | Gratis (SAT) |

---

**Ultima actualizacion:** 2026-01-17