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

id	type	title	code	status	status_real	status_nota	phase	priority	story_points	created_at	updated_at	simco_version	dependencies
EPIC-MCH-027	Epic	MCH-027: Integracion SAT	MCH-027	Completado	Mock	Implementacion mock - Sin integracion real con PAC	7	P3	55	2026-01-10	2026-01-17	4.0.1	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)

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

{
  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