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)
```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

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