michangarrito/backups/docs-backup-2026-01-10/docs/01-epicas/MCH-027-integracion-sat.md

MCH-027: Integracion SAT

Metadata

• Codigo: MCH-027
• Fase: 7 - Expansion (Futuro)
• Prioridad: P3
• Estado: Completado
• 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

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-10