rckrdmrd a6186c4022 Migración desde erp-retail/backend - Estándar multi-repo v2

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-16 08:11:34 -06:00

8.1 KiB

Raw Blame History

Sprint 5: CFDI/Facturación - Resumen

Objetivo

Implementar el sistema completo de facturación electrónica CFDI 4.0 para el vertical de Retail, con integración a PACs y soporte para autofactura.

Componentes Implementados

1. Servicios

XMLService (`src/modules/invoicing/services/xml.service.ts`)

Servicio para construcción y manipulación de XML CFDI 4.0:

buildCFDIXML(): Construye XML completo según especificación SAT
addSealToXML(): Agrega sello del contribuyente
addCertificateToXML(): Agrega certificado CSD
addTimbreToXML(): Agrega complemento TimbreFiscalDigital
buildCadenaOriginal(): Genera cadena original para firma
parseStampedXML(): Parsea respuesta de PAC
generateQRData(): Genera URL de verificación SAT para QR
validateXMLStructure(): Validación básica de estructura

Características:

Namespaces CFDI 4.0 y TFD 1.1
Soporte para CFDIs relacionados
Formateo de montos y tasas según SAT
Generación de cadena original del SAT

PACService (`src/modules/invoicing/services/pac.service.ts`)

Servicio de integración con Proveedores Autorizados de Certificación:

stampCFDI(): Timbrado de CFDI
cancelCFDI(): Cancelación con motivo
verifyCFDIStatus(): Consulta estado en SAT
encrypt()/decrypt(): Cifrado de credenciales
loadCertificate(): Carga de CSD
signData(): Firma con llave privada

PACs Soportados:

PAC	Timbrado	Cancelación	Verificación
Finkok	✓	✓	✓
Facturapi	✓	✓	-
SW Sapien	✓	-	-
Soluciones Fiscales	Config	Config	Config
Digisat	Config	Config	Config

Motivos de Cancelación (SAT):

01: Comprobante emitido con errores con relación
02: Comprobante emitido con errores sin relación
03: No se llevó a cabo la operación
04: Operación nominativa relacionada en factura global

CFDIBuilderService (`src/modules/invoicing/services/cfdi-builder.service.ts`)

Constructor de estructuras CFDI desde datos de orden:

buildFromOrder(): Construye CFDI desde líneas de pedido
buildCreditNote(): Genera nota de crédito
buildPaymentComplement(): Genera complemento de pago
validateReceptor(): Valida datos del receptor (CFDI 4.0)
getUsoCFDIOptions(): Opciones de uso CFDI por tipo de persona
getCommonClavesProdServ(): Claves SAT comunes para retail

Cálculos Automáticos:

Desglose de impuestos (IVA, ISR, IEPS)
Agregación por tipo de impuesto
Manejo de precios con/sin impuesto
Retenciones IVA e ISR

CFDIService (`src/modules/invoicing/services/cfdi.service.ts`)

Servicio principal de facturación:

createCFDI(): Crear factura (draft o timbrada)
stampCFDI(): Timbrar factura en borrador
cancelCFDI(): Cancelar factura timbrada
verifyCFDIStatus(): Verificar estado en SAT
listCFDIs(): Listado con filtros paginados
getCFDIById(): Obtener por ID
getCFDIByUUID(): Obtener por UUID
downloadXML(): Descargar XML
resendEmail(): Reenviar por correo
createCreditNote(): Crear nota de crédito
getStats(): Estadísticas de facturación
getActiveConfig(): Obtener configuración activa

2. Validación Zod (`src/modules/invoicing/validation/cfdi.schema.ts`)

Schemas de CFDI:

receptorSchema: Datos del receptor con validación RFC
orderLineSchema: Líneas con claves SAT
createCFDISchema: Creación completa
cancelCFDISchema: Cancelación con motivo
listCFDIsQuerySchema: Filtros de búsqueda
createCreditNoteSchema: Nota de crédito

Schemas de Configuración:

createCFDIConfigSchema: Configuración PAC y CSD
updateCFDIConfigSchema: Actualización parcial
validateCFDIConfigSchema: Validación de config

Schemas de Autofactura:

autofacturaRequestSchema: Solicitud de autofactura
lookupOrderSchema: Búsqueda de ticket

3. Controladores (`src/modules/invoicing/controllers/cfdi.controller.ts`)

Endpoints de CFDI (14):

Método	Ruta	Descripción
GET	`/cfdis`	Listar CFDIs
GET	`/cfdis/:id`	Obtener por ID
GET	`/cfdis/uuid/:uuid`	Obtener por UUID
POST	`/cfdis`	Crear CFDI
POST	`/cfdis/:id/stamp`	Timbrar
POST	`/cfdis/:id/cancel`	Cancelar
GET	`/cfdis/:id/verify`	Verificar en SAT
GET	`/cfdis/:id/xml`	Descargar XML
POST	`/cfdis/:id/resend-email`	Reenviar email
POST	`/cfdis/:id/credit-note`	Crear nota crédito
GET	`/stats`	Estadísticas
GET	`/cancellation-reasons`	Motivos cancelación
GET	`/uso-cfdi-options`	Opciones UsoCFDI
GET	`/claves-prod-serv`	Claves SAT

Endpoints de Configuración (5):

Método	Ruta	Descripción
GET	`/config`	Obtener config
POST	`/config`	Crear/actualizar config
PUT	`/config`	Actualizar config
POST	`/config/certificate`	Subir CSD
POST	`/config/validate`	Validar config

Endpoints de Autofactura (2):

Método	Ruta	Descripción
POST	`/autofactura/lookup`	Buscar ticket
POST	`/autofactura/create`	Generar factura

Total: 21 endpoints

4. Rutas (`src/modules/invoicing/routes/cfdi.routes.ts`)

Rutas Públicas:

Autofactura (lookup, create)
Catálogos SAT (uso CFDI, claves prod/serv, motivos cancelación)

Rutas Autenticadas:

CFDI CRUD y operaciones
Configuración (requiere cfdi:config:*)

Permisos Requeridos:

cfdi:view, cfdi:create, cfdi:stamp, cfdi:cancel, cfdi:send
cfdi:config:view, cfdi:config:manage

Estructura de Archivos

src/modules/invoicing/
├── controllers/
│   ├── index.ts
│   └── cfdi.controller.ts
├── entities/
│   ├── index.ts
│   ├── cfdi.entity.ts
│   └── cfdi-config.entity.ts
├── routes/
│   ├── index.ts
│   └── cfdi.routes.ts
├── services/
│   ├── index.ts
│   ├── cfdi.service.ts
│   ├── cfdi-builder.service.ts
│   ├── xml.service.ts
│   └── pac.service.ts
├── validation/
│   ├── index.ts
│   └── cfdi.schema.ts
└── index.ts

Flujo de Facturación

┌────────────┐     ┌──────────────┐     ┌─────────────┐
│   Order    │────▶│ CFDIBuilder  │────▶│    CFDI     │
│   Data     │     │   Service    │     │   (draft)   │
└────────────┘     └──────────────┘     └──────┬──────┘
                                               │
                                               ▼
┌────────────┐     ┌──────────────┐     ┌─────────────┐
│  Stamped   │◀────│     PAC      │◀────│     XML     │
│   CFDI     │     │   Service    │     │   Service   │
└────────────┘     └──────────────┘     └─────────────┘

Estados del CFDI

draft ──────▶ pending ──────▶ stamped ──────▶ cancelled
                │                │
                ▼                ▼
              error    cancellation_pending

Características CFDI 4.0

Validación de RFC y régimen fiscal del receptor
Código postal del domicilio fiscal requerido
Objeto de impuesto por concepto
Relacionados con tipo de relación
Exportación (01 = No exportación)

Dependencias

xmlbuilder2: Construcción de XML
crypto (Node.js): Cifrado y firma
TypeORM 0.3.x
Zod para validación

Variables de Entorno Requeridas

PAC_ENCRYPTION_KEY=your-32-byte-encryption-key

Próximos Pasos

El Sprint 6 según el roadmap cubrirá POS Backend:

Sesiones de POS
Órdenes y líneas
Pagos múltiples
Integración con motor de precios

8.1 KiB Raw Blame History