rckrdmrd/workspace-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d6c684611f
workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAE-009-facturacion/implementacion/TRACEABILITY.yml
rckrdmrd 66161b1566 feat: Workspace-v1 complete migration with NEXUS v3.4 
Sistema NEXUS v3.4 migrado con:

Estructura principal:
- core/orchestration: Sistema SIMCO + CAPVED (27 directivas, 28 perfiles)
- core/catalog: Catalogo de funcionalidades reutilizables
- shared/knowledge-base: Base de conocimiento compartida
- devtools/scripts: Herramientas de desarrollo
- control-plane/registries: Control de servicios y CI/CD
- orchestration/: Configuracion de orquestacion de agentes

Proyectos incluidos (11):
- gamilit (submodule -> GitHub)
- trading-platform (OrbiquanTIA)
- erp-suite con 5 verticales:
  - erp-core, construccion, vidrio-templado
  - mecanicas-diesel, retail, clinicas
- betting-analytics
- inmobiliaria-analytics
- platform_marketing_content
- pos-micro, erp-basico

Configuracion:
- .gitignore completo para Node.js/Python/Docker
- gamilit como submodule (git@github.com:rckrdmrd/gamilit-workspace.git)
- Sistema de puertos estandarizado (3005-3199)

Generated with NEXUS v3.4 Migration System
EPIC-010: Configuracion Git y Repositorios
2026-01-04 03:37:42 -06:00

1421 lines
48 KiB
YAML
Raw Blame History

# ============================================================================
# MATRIZ DE TRAZABILIDAD - MÓDULO MAE-009: FACTURACIÓN
# ============================================================================
# Proyecto: ERP Suite - Vertical Construcción
# Módulo: MAE-009 - Facturación Electrónica
# Versión: 1.0.0
# Fecha: 2025-12-06
# ============================================================================
metadata:
module_id: MAE-009
module_name: Facturación
vertical: construccion
version: 1.0.0
status: planned
owner: Equipo Construcción
created_date: 2025-12-06
last_updated: 2025-12-06
description: |
Módulo de facturación electrónica para el sector construcción.
Gestiona la emisión, cancelación y recepción de CFDI, así como
complementos de pago según la normativa del SAT mexicano.
# ============================================================================
# REQUERIMIENTOS FUNCIONALES
# ============================================================================
functional_requirements:
# --------------------------------------------------------------------------
# RF-001: EMISIÓN DE CFDI
# --------------------------------------------------------------------------
- id: RF-MAE-009-001
name: Emisión de CFDI
description: |
Emisión de Comprobantes Fiscales Digitales por Internet (CFDI) según
la normativa del SAT mexicano. Incluye validación de datos fiscales,
timbrado mediante PAC y almacenamiento de XML y PDF.
priority: critical
status: pending
business_rules:
- id: BR-MAE-009-001-01
description: El RFC del emisor debe estar registrado y activo en el SAT
- id: BR-MAE-009-001-02
description: Todos los CFDI deben timbarse con un PAC autorizado antes de ser válidos
- id: BR-MAE-009-001-03
description: Los datos fiscales del receptor deben validarse contra el SAT
- id: BR-MAE-009-001-04
description: El CFDI debe cumplir con el esquema XML vigente del SAT (versión 4.0)
- id: BR-MAE-009-001-05
description: Cada CFDI debe incluir UUID único proporcionado por el PAC
- id: BR-MAE-009-001-06
description: Se debe generar representación impresa (PDF) del CFDI
- id: BR-MAE-009-001-07
description: Los CFDI de obra deben incluir información de la obra/proyecto
- id: BR-MAE-009-001-08
description: Validar que la forma de pago coincida con el método de pago
user_stories:
- id: US-MAE-009-001-01
title: Crear CFDI de ingreso desde contrato
description: Como contador, quiero generar un CFDI de ingreso a partir de un contrato de obra para facturar estimaciones
acceptance_criteria:
- El sistema carga automáticamente los datos del contrato
- Se pre-llena la información fiscal del cliente
- Se permite seleccionar conceptos de la estimación
- Se calcula automáticamente IVA y retenciones
- Se valida el RFC del receptor contra el SAT
priority: high
story_points: 8
- id: US-MAE-009-001-02
title: Timbrar CFDI con PAC
description: Como contador, quiero timbrar el CFDI generado mediante el PAC autorizado para obtener el sello digital
acceptance_criteria:
- El sistema envía el XML pre-validado al PAC
- Se recibe y almacena el UUID del comprobante
- Se guarda el XML timbrado con cadena original
- Se genera PDF con código QR y sello digital
- Se notifica al usuario del éxito o error del timbrado
priority: critical
story_points: 13
- id: US-MAE-009-001-03
title: Enviar CFDI por correo electrónico
description: Como contador, quiero enviar el CFDI timbrado al cliente por correo electrónico con XML y PDF adjuntos
acceptance_criteria:
- Se adjuntan XML y PDF del CFDI
- El correo incluye resumen de la factura
- Se registra el envío en el historial
- Se permite reenvío de CFDI
- Se valida el formato del correo electrónico
priority: medium
story_points: 5
- id: US-MAE-009-001-04
title: Gestionar addendas de clientes
description: Como contador, quiero agregar addendas específicas de clientes corporativos al CFDI para cumplir sus requerimientos
acceptance_criteria:
- Se pueden configurar addendas por cliente
- Las addendas se incluyen en el XML del CFDI
- Se valida la estructura XML de la addenda
- Se mantiene compatibilidad con esquema SAT
priority: low
story_points: 8
technical_requirements:
- id: TR-MAE-009-001-01
description: Implementar servicio de validación de RFC contra API del SAT
component: backend/services/sat-validation
technology: Node.js, Axios
- id: TR-MAE-009-001-02
description: Integrar con PAC autorizado (ej. Finkok, PAC SAT)
component: backend/integrations/pac
technology: SOAP/REST, XML
- id: TR-MAE-009-001-03
description: Generar XML según esquema CFDI 4.0
component: backend/services/cfdi-generator
technology: Node.js, xml2js
- id: TR-MAE-009-001-04
description: Generar PDF con representación impresa del CFDI
component: backend/services/pdf-generator
technology: PDFKit, QRCode
- id: TR-MAE-009-001-05
description: Implementar interfaz de captura de CFDI
component: frontend/modules/facturacion
technology: React, TypeScript
dependencies:
internal:
- module: MGN-001
requirement: Gestión de usuarios y autenticación
- module: MGN-002
requirement: Control de permisos para emisión de CFDI
- module: MGN-003
requirement: Aislamiento de datos por tenant/empresa
- module: MAE-001
requirement: Datos de contratos y clientes
external:
- service: PAC
description: Proveedor Autorizado de Certificación para timbrado
type: SOAP/REST API
- service: SAT
description: Servicio de Administración Tributaria - Validación de RFC
type: Web Service
test_cases:
- id: TC-MAE-009-001-01
description: Validar generación correcta de XML CFDI 4.0
type: unit
status: pending
- id: TC-MAE-009-001-02
description: Probar timbrado exitoso con PAC en ambiente de pruebas
type: integration
status: pending
- id: TC-MAE-009-001-03
description: Verificar generación de PDF con todos los elementos legales
type: functional
status: pending
- id: TC-MAE-009-001-04
description: Validar flujo completo de emisión de CFDI
type: e2e
status: pending
implementation:
files:
- path: backend/src/modules/facturacion/services/cfdi-emision.service.ts
status: pending
- path: backend/src/modules/facturacion/controllers/cfdi.controller.ts
status: pending
- path: backend/src/integrations/pac/pac-client.ts
status: pending
- path: frontend/src/modules/facturacion/components/CFDIForm.tsx
status: pending
database_changes:
- table: cfdi
type: create
description: Almacena los CFDI emitidos
- table: cfdi_conceptos
type: create
description: Detalle de conceptos del CFDI
- table: cfdi_impuestos
type: create
description: Desglose de impuestos
api_endpoints:
- method: POST
path: /api/v1/facturacion/cfdi
description: Crear y timbrar nuevo CFDI
- method: GET
path: /api/v1/facturacion/cfdi/:id
description: Obtener detalles de un CFDI
- method: GET
path: /api/v1/facturacion/cfdi/:id/xml
description: Descargar XML del CFDI
- method: GET
path: /api/v1/facturacion/cfdi/:id/pdf
description: Descargar PDF del CFDI
# --------------------------------------------------------------------------
# RF-002: CANCELACIÓN DE CFDI
# --------------------------------------------------------------------------
- id: RF-MAE-009-002
name: Cancelación de CFDI
description: |
Proceso de cancelación de CFDI previamente timbrados mediante el PAC,
incluyendo solicitud de cancelación, gestión de aceptación por parte
del receptor y actualización de estatus en el SAT.
priority: critical
status: pending
business_rules:
- id: BR-MAE-009-002-01
description: Solo se pueden cancelar CFDI previamente timbrados
- id: BR-MAE-009-002-02
description: La cancelación debe registrarse ante el SAT a través del PAC
- id: BR-MAE-009-002-03
description: Para CFDI mayores a $5,000 se requiere aceptación del receptor
- id: BR-MAE-009-002-04
description: Se debe especificar el motivo de cancelación según catálogo SAT
- id: BR-MAE-009-002-05
description: Si se especifica UUID de sustitución, este debe ser válido
- id: BR-MAE-009-002-06
description: No se pueden cancelar CFDI ya cancelados
- id: BR-MAE-009-002-07
description: Validar período permitido para cancelación según reglas SAT
user_stories:
- id: US-MAE-009-002-01
title: Solicitar cancelación de CFDI
description: Como contador, quiero solicitar la cancelación de un CFDI emitido especificando el motivo para corregir errores
acceptance_criteria:
- Se muestra lista de motivos de cancelación del catálogo SAT
- Se permite indicar UUID de sustitución si aplica
- El sistema valida que el CFDI no esté ya cancelado
- Se envía solicitud al PAC
- Se registra el intento de cancelación
priority: high
story_points: 8
- id: US-MAE-009-002-02
title: Gestionar aceptación de cancelación
description: Como receptor, quiero recibir notificación de solicitud de cancelación y poder aceptarla o rechazarla
acceptance_criteria:
- Se notifica por correo la solicitud de cancelación
- Se proporciona enlace para aceptar/rechazar
- Se registra la respuesta del receptor
- Se actualiza el estatus del CFDI
- Se notifica al emisor de la decisión
priority: high
story_points: 8
- id: US-MAE-009-002-03
title: Consultar estatus de cancelación
description: Como contador, quiero consultar el estatus de una solicitud de cancelación para dar seguimiento
acceptance_criteria:
- Se muestra el estatus actual (pendiente, aceptada, rechazada)
- Se muestra la fecha de solicitud
- Se indica si requiere aceptación del receptor
- Se muestra historial de la solicitud
priority: medium
story_points: 5
technical_requirements:
- id: TR-MAE-009-002-01
description: Implementar servicio de cancelación vía PAC
component: backend/services/cfdi-cancelacion
technology: Node.js, SOAP/REST
- id: TR-MAE-009-002-02
description: Crear flujo de aceptación/rechazo de cancelación
component: backend/services/cancelacion-workflow
technology: Node.js, Estado de máquina
- id: TR-MAE-009-002-03
description: Implementar notificaciones de cancelación
component: backend/services/notifications
technology: Email, Push notifications
- id: TR-MAE-009-002-04
description: Interfaz de gestión de cancelaciones
component: frontend/modules/facturacion/cancelacion
technology: React, TypeScript
dependencies:
internal:
- module: RF-MAE-009-001
requirement: CFDI debe estar previamente emitido
- module: MGN-008
requirement: Sistema de notificaciones
external:
- service: PAC
description: Cancelación de CFDI ante el SAT
type: SOAP/REST API
- service: SAT
description: Consulta de estatus de cancelación
type: Web Service
test_cases:
- id: TC-MAE-009-002-01
description: Validar cancelación exitosa de CFDI menor a $5,000
type: integration
status: pending
- id: TC-MAE-009-002-02
description: Probar flujo de aceptación de cancelación por receptor
type: functional
status: pending
- id: TC-MAE-009-002-03
description: Verificar rechazo de cancelación de CFDI ya cancelado
type: unit
status: pending
implementation:
files:
- path: backend/src/modules/facturacion/services/cfdi-cancelacion.service.ts
status: pending
- path: backend/src/modules/facturacion/controllers/cancelacion.controller.ts
status: pending
- path: frontend/src/modules/facturacion/components/CancelacionForm.tsx
status: pending
database_changes:
- table: cfdi_cancelaciones
type: create
description: Registro de solicitudes de cancelación
- table: cfdi
type: alter
description: Agregar campos de estatus de cancelación
api_endpoints:
- method: POST
path: /api/v1/facturacion/cfdi/:id/cancelar
description: Solicitar cancelación de CFDI
- method: GET
path: /api/v1/facturacion/cfdi/:id/cancelacion/status
description: Consultar estatus de cancelación
- method: POST
path: /api/v1/facturacion/cancelacion/:id/aceptar
description: Aceptar cancelación como receptor
- method: POST
path: /api/v1/facturacion/cancelacion/:id/rechazar
description: Rechazar cancelación como receptor
# --------------------------------------------------------------------------
# RF-003: RECEPCIÓN DE CFDI
# --------------------------------------------------------------------------
- id: RF-MAE-009-003
name: Recepción de CFDI
description: |
Gestión de CFDI recibidos de proveedores, incluyendo carga de XML,
validación de timbrado, verificación ante el SAT y registro contable
de documentos por pagar.
priority: high
status: pending
business_rules:
- id: BR-MAE-009-003-01
description: El XML debe contener un UUID válido y verificable ante el SAT
- id: BR-MAE-009-003-02
description: El RFC receptor debe corresponder a la empresa activa
- id: BR-MAE-009-003-03
description: Se debe validar el sello digital del PAC
- id: BR-MAE-009-003-04
description: Verificar que el CFDI no esté cancelado en el SAT
- id: BR-MAE-009-003-05
description: Los CFDI recibidos deben asociarse a órdenes de compra o contratos
- id: BR-MAE-009-003-06
description: Detectar y alertar sobre CFDI duplicados (mismo UUID)
- id: BR-MAE-009-003-07
description: Validar que los montos coincidan con la orden de compra asociada
user_stories:
- id: US-MAE-009-003-01
title: Cargar CFDI recibido
description: Como auxiliar contable, quiero cargar el XML de un CFDI recibido para registrarlo en el sistema
acceptance_criteria:
- Se permite carga individual o masiva de archivos XML
- El sistema extrae automáticamente datos del XML
- Se valida la estructura y sello del XML
- Se detectan XML duplicados
- Se almacena el XML original
priority: high
story_points: 8
- id: US-MAE-009-003-02
title: Validar CFDI ante el SAT
description: Como contador, quiero validar automáticamente el CFDI ante el SAT para verificar su autenticidad y vigencia
acceptance_criteria:
- Se consulta el estatus del UUID ante el SAT
- Se verifica que el CFDI no esté cancelado
- Se valida la cadena original y sello digital
- Se muestra resultado de la validación
- Se registra fecha de validación
priority: high
story_points: 8
- id: US-MAE-009-003-03
title: Asociar CFDI a orden de compra
description: Como auxiliar contable, quiero asociar un CFDI recibido a su orden de compra correspondiente para conciliar
acceptance_criteria:
- Se sugieren órdenes de compra pendientes del proveedor
- Se comparan montos entre CFDI y orden de compra
- Se permite asociación manual o automática
- Se actualiza estatus de la orden de compra
- Se alerta si hay discrepancias en montos
priority: medium
story_points: 5
- id: US-MAE-009-003-04
title: Consultar CFDI recibidos
description: Como contador, quiero consultar y filtrar los CFDI recibidos para revisión y auditoría
acceptance_criteria:
- Filtros por proveedor, fecha, monto, estatus
- Visualización de datos fiscales principales
- Descarga de XML y PDF
- Exportación a Excel
- Indicadores visuales de estatus
priority: medium
story_points: 5
technical_requirements:
- id: TR-MAE-009-003-01
description: Implementar parser de XML CFDI 4.0 y versiones anteriores
component: backend/services/cfdi-parser
technology: Node.js, xml2js
- id: TR-MAE-009-003-02
description: Servicio de validación de CFDI ante SAT
component: backend/services/sat-validator
technology: Node.js, SOAP
- id: TR-MAE-009-003-03
description: Almacenamiento y gestión de archivos XML
component: backend/services/file-storage
technology: S3, MinIO
- id: TR-MAE-009-003-04
description: Interfaz de carga y gestión de CFDI recibidos
component: frontend/modules/facturacion/recepcion
technology: React, TypeScript
dependencies:
internal:
- module: MGN-003
requirement: Validación de RFC de empresa
- module: MAE-002
requirement: Órdenes de compra para asociación
external:
- service: SAT
description: Validación de vigencia de CFDI
type: Web Service
test_cases:
- id: TC-MAE-009-003-01
description: Validar parsing correcto de XML CFDI 4.0
type: unit
status: pending
- id: TC-MAE-009-003-02
description: Probar validación de CFDI vigente ante SAT
type: integration
status: pending
- id: TC-MAE-009-003-03
description: Verificar detección de CFDI duplicados
type: functional
status: pending
- id: TC-MAE-009-003-04
description: Validar asociación correcta con orden de compra
type: functional
status: pending
implementation:
files:
- path: backend/src/modules/facturacion/services/cfdi-recepcion.service.ts
status: pending
- path: backend/src/modules/facturacion/parsers/cfdi-parser.ts
status: pending
- path: frontend/src/modules/facturacion/components/RecepcionCFDI.tsx
status: pending
database_changes:
- table: cfdi_recibidos
type: create
description: Almacena CFDI recibidos de proveedores
- table: cfdi_recibidos_conceptos
type: create
description: Detalle de conceptos de CFDI recibidos
- table: cfdi_validaciones
type: create
description: Historial de validaciones ante SAT
api_endpoints:
- method: POST
path: /api/v1/facturacion/cfdi/recibidos
description: Cargar CFDI recibido
- method: POST
path: /api/v1/facturacion/cfdi/recibidos/validar
description: Validar CFDI ante SAT
- method: GET
path: /api/v1/facturacion/cfdi/recibidos
description: Listar CFDI recibidos
- method: POST
path: /api/v1/facturacion/cfdi/recibidos/:id/asociar
description: Asociar CFDI a orden de compra
# --------------------------------------------------------------------------
# RF-004: COMPLEMENTOS DE PAGO
# --------------------------------------------------------------------------
- id: RF-MAE-009-004
name: Complementos de Pago
description: |
Emisión de CFDI con complemento de pago para relacionar pagos
recibidos con facturas previamente emitidas, cumpliendo con
la normativa del SAT para documentar la forma de pago.
priority: high
status: pending
business_rules:
- id: BR-MAE-009-004-01
description: El complemento de pago debe relacionarse con uno o más CFDI de ingreso previos
- id: BR-MAE-009-004-02
description: La suma de pagos no debe exceder el total del CFDI relacionado
- id: BR-MAE-009-004-03
description: Se debe especificar la forma de pago (transferencia, cheque, etc.)
- id: BR-MAE-009-004-04
description: Incluir datos bancarios si el pago es por transferencia
- id: BR-MAE-009-004-05
description: El tipo de cambio es obligatorio para pagos en moneda extranjera
- id: BR-MAE-009-004-06
description: Validar que los CFDI relacionados no estén cancelados
- id: BR-MAE-009-004-07
description: El monto del pago debe ser mayor a cero
user_stories:
- id: US-MAE-009-004-01
title: Generar complemento de pago
description: Como contador, quiero generar un complemento de pago para documentar un pago recibido de un cliente
acceptance_criteria:
- Se seleccionan los CFDI pendientes de pago del cliente
- Se captura monto, fecha y forma de pago
- Se calculan parcialidades automáticamente
- Se valida que no se exceda el saldo pendiente
- Se genera y timbra el complemento
priority: high
story_points: 13
- id: US-MAE-009-004-02
title: Aplicar pago parcial a múltiples facturas
description: Como contador, quiero aplicar un pago que cubre parcialmente varias facturas para documentar correctamente
acceptance_criteria:
- Se distribuye automáticamente el pago entre facturas
- Se permite ajuste manual de distribución
- Se muestra saldo pendiente de cada factura
- Se valida que la suma sea correcta
- Se generan parcialidades correctas en el XML
priority: high
story_points: 8
- id: US-MAE-009-004-03
title: Consultar complementos de pago emitidos
description: Como contador, quiero consultar los complementos de pago emitidos para verificar aplicación de pagos
acceptance_criteria:
- Lista de complementos con filtros
- Visualización de facturas relacionadas
- Descarga de XML y PDF
- Indicador de estatus (vigente/cancelado)
- Integración con estado de cuenta del cliente
priority: medium
story_points: 5
- id: US-MAE-009-004-04
title: Cancelar complemento de pago
description: Como contador, quiero cancelar un complemento de pago en caso de error para corregir la aplicación
acceptance_criteria:
- Se restaura el saldo de las facturas relacionadas
- Se solicita cancelación al PAC
- Se actualiza estado de cuenta del cliente
- Se registra motivo de cancelación
- Se notifica al cliente
priority: medium
story_points: 5
technical_requirements:
- id: TR-MAE-009-004-01
description: Implementar generación de complemento de pago según anexo 20
component: backend/services/complemento-pago
technology: Node.js, xml2js
- id: TR-MAE-009-004-02
description: Servicio de cálculo de parcialidades
component: backend/services/parcialidades-calculator
technology: Node.js
- id: TR-MAE-009-004-03
description: Interfaz de aplicación de pagos
component: frontend/modules/facturacion/pagos
technology: React, TypeScript
- id: TR-MAE-009-004-04
description: Actualización de saldos de clientes
component: backend/services/cuentas-corrientes
technology: Node.js, PostgreSQL
dependencies:
internal:
- module: RF-MAE-009-001
requirement: CFDI de ingreso previamente emitidos
- module: MAE-003
requirement: Gestión de cuentas por cobrar
external:
- service: PAC
description: Timbrado de complementos de pago
type: SOAP/REST API
- service: Banxico
description: Tipo de cambio para pagos en moneda extranjera
type: REST API
test_cases:
- id: TC-MAE-009-004-01
description: Validar generación correcta de XML complemento de pago
type: unit
status: pending
- id: TC-MAE-009-004-02
description: Probar cálculo de parcialidades para pago múltiple
type: unit
status: pending
- id: TC-MAE-009-004-03
description: Verificar actualización de saldos tras aplicar pago
type: integration
status: pending
- id: TC-MAE-009-004-04
description: Validar flujo completo de complemento de pago
type: e2e
status: pending
implementation:
files:
- path: backend/src/modules/facturacion/services/complemento-pago.service.ts
status: pending
- path: backend/src/modules/facturacion/controllers/pagos.controller.ts
status: pending
- path: frontend/src/modules/facturacion/components/ComplementoPagoForm.tsx
status: pending
database_changes:
- table: complementos_pago
type: create
description: Registro de complementos de pago emitidos
- table: complementos_pago_documentos
type: create
description: Relación con documentos relacionados
- table: cfdi
type: alter
description: Agregar campos de control de saldo y parcialidades
api_endpoints:
- method: POST
path: /api/v1/facturacion/complementos-pago
description: Generar complemento de pago
- method: GET
path: /api/v1/facturacion/complementos-pago
description: Listar complementos de pago
- method: GET
path: /api/v1/facturacion/cfdi/:id/saldo
description: Consultar saldo pendiente de un CFDI
- method: POST
path: /api/v1/facturacion/complementos-pago/:id/cancelar
description: Cancelar complemento de pago
# ============================================================================
# INTEGRACIONES EXTERNAS
# ============================================================================
external_integrations:
- id: INT-MAE-009-001
name: Integración con PAC
description: |
Integración con Proveedor Autorizado de Certificación para timbrado
y cancelación de CFDI ante el SAT.
provider: PAC Autorizado (Finkok, PAC SAT, etc.)
type: SOAP/REST API
authentication: API Key + Certificado Digital
endpoints:
- name: Timbrado de CFDI
method: POST
description: Envío de XML para timbrado
- name: Cancelación de CFDI
method: POST
description: Solicitud de cancelación
- name: Consulta de estatus
method: GET
description: Verificación de estatus de CFDI
requirements:
- Certificado de sello digital vigente (CSD)
- Cuenta activa con el PAC
- Configuración de credenciales de API
error_handling:
- Timeout: Reintentar hasta 3 veces
- Error de validación: Mostrar mensaje específico
- Servicio no disponible: Encolar para reintento
- id: INT-MAE-009-002
name: Validación ante SAT
description: |
Servicios web del SAT para validación de RFC, estatus de CFDI
y consulta de datos fiscales.
provider: Servicio de Administración Tributaria
type: Web Service (SOAP)
authentication: Pública (sin autenticación para consultas)
endpoints:
- name: Validación de RFC
method: GET
description: Verificar existencia y estatus de RFC
- name: Validación de CFDI
method: GET
description: Consultar vigencia de UUID
- name: Consulta de estatus tributario
method: GET
description: Verificar situación fiscal del contribuyente
requirements:
- Conexión a internet estable
- Manejo de certificados SSL
error_handling:
- Cache de RFC validados (24 horas)
- Modo offline para consultas no críticas
- id: INT-MAE-009-003
name: Consulta de tipo de cambio
description: |
Obtención de tipo de cambio oficial para CFDI en moneda extranjera
y complementos de pago.
provider: Banco de México (Banxico)
type: REST API
authentication: API Token
endpoints:
- name: Tipo de cambio USD
method: GET
description: Obtener tipo de cambio USD/MXN
requirements:
- Token de API de Banxico
- Actualización diaria de tipos de cambio
error_handling:
- Cache del último tipo de cambio conocido
- Alerta si no se puede actualizar por 3 días
# ============================================================================
# MODELO DE DATOS
# ============================================================================
data_model:
tables:
- name: cfdi
description: Catálogo principal de CFDI emitidos
columns:
- name: id
type: UUID
primary_key: true
- name: tenant_id
type: UUID
nullable: false
foreign_key: tenants.id
- name: uuid
type: VARCHAR(36)
nullable: false
unique: true
description: UUID del CFDI asignado por el PAC
- name: folio
type: VARCHAR(20)
nullable: false
- name: serie
type: VARCHAR(10)
nullable: true
- name: tipo_comprobante
type: VARCHAR(1)
nullable: false
description: I=Ingreso, E=Egreso, T=Traslado, N=Nómina, P=Pago
- name: fecha_emision
type: TIMESTAMP
nullable: false
- name: fecha_timbrado
type: TIMESTAMP
nullable: true
- name: emisor_rfc
type: VARCHAR(13)
nullable: false
- name: emisor_nombre
type: VARCHAR(300)
nullable: false
- name: receptor_rfc
type: VARCHAR(13)
nullable: false
- name: receptor_nombre
type: VARCHAR(300)
nullable: false
- name: receptor_email
type: VARCHAR(100)
nullable: true
- name: subtotal
type: DECIMAL(18,2)
nullable: false
- name: total
type: DECIMAL(18,2)
nullable: false
- name: moneda
type: VARCHAR(3)
nullable: false
default: MXN
- name: tipo_cambio
type: DECIMAL(10,6)
nullable: true
- name: forma_pago
type: VARCHAR(2)
nullable: true
- name: metodo_pago
type: VARCHAR(3)
nullable: false
- name: uso_cfdi
type: VARCHAR(3)
nullable: false
- name: estatus
type: VARCHAR(20)
nullable: false
description: borrador, timbrado, cancelado, cancelacion_pendiente
- name: xml_path
type: VARCHAR(500)
nullable: true
- name: pdf_path
type: VARCHAR(500)
nullable: true
- name: saldo_pendiente
type: DECIMAL(18,2)
nullable: true
description: Para control de complementos de pago
- name: contrato_id
type: UUID
nullable: true
foreign_key: contratos.id
- name: created_at
type: TIMESTAMP
default: NOW()
- name: updated_at
type: TIMESTAMP
default: NOW()
indexes:
- columns: [uuid]
unique: true
- columns: [tenant_id, folio, serie]
- columns: [receptor_rfc]
- columns: [estatus]
- columns: [fecha_emision]
- name: cfdi_conceptos
description: Conceptos/partidas de los CFDI
columns:
- name: id
type: UUID
primary_key: true
- name: cfdi_id
type: UUID
nullable: false
foreign_key: cfdi.id
- name: numero
type: INTEGER
nullable: false
- name: clave_prod_serv
type: VARCHAR(8)
nullable: false
- name: clave_unidad
type: VARCHAR(3)
nullable: false
- name: unidad
type: VARCHAR(20)
nullable: true
- name: descripcion
type: TEXT
nullable: false
- name: cantidad
type: DECIMAL(18,6)
nullable: false
- name: valor_unitario
type: DECIMAL(18,6)
nullable: false
- name: importe
type: DECIMAL(18,2)
nullable: false
- name: descuento
type: DECIMAL(18,2)
nullable: true
- name: objeto_imp
type: VARCHAR(2)
nullable: false
indexes:
- columns: [cfdi_id]
- name: cfdi_impuestos
description: Desglose de impuestos por concepto
columns:
- name: id
type: UUID
primary_key: true
- name: concepto_id
type: UUID
nullable: false
foreign_key: cfdi_conceptos.id
- name: tipo
type: VARCHAR(10)
nullable: false
description: traslado o retencion
- name: impuesto
type: VARCHAR(3)
nullable: false
description: 001=ISR, 002=IVA, 003=IEPS
- name: tipo_factor
type: VARCHAR(10)
nullable: false
- name: tasa_o_cuota
type: DECIMAL(6,6)
nullable: true
- name: base
type: DECIMAL(18,2)
nullable: false
- name: importe
type: DECIMAL(18,2)
nullable: false
indexes:
- columns: [concepto_id]
- name: cfdi_cancelaciones
description: Registro de solicitudes de cancelación
columns:
- name: id
type: UUID
primary_key: true
- name: cfdi_id
type: UUID
nullable: false
foreign_key: cfdi.id
- name: fecha_solicitud
type: TIMESTAMP
nullable: false
default: NOW()
- name: motivo
type: VARCHAR(2)
nullable: false
description: Catálogo de motivos SAT
- name: uuid_sustitucion
type: VARCHAR(36)
nullable: true
- name: estatus
type: VARCHAR(20)
nullable: false
description: pendiente, aceptada, rechazada
- name: fecha_respuesta
type: TIMESTAMP
nullable: true
- name: respuesta_receptor
type: VARCHAR(20)
nullable: true
- name: pac_acuse
type: TEXT
nullable: true
- name: created_by
type: UUID
nullable: false
foreign_key: users.id
indexes:
- columns: [cfdi_id]
- columns: [estatus]
- name: cfdi_recibidos
description: CFDI recibidos de proveedores
columns:
- name: id
type: UUID
primary_key: true
- name: tenant_id
type: UUID
nullable: false
foreign_key: tenants.id
- name: uuid
type: VARCHAR(36)
nullable: false
unique: true
- name: folio
type: VARCHAR(20)
nullable: true
- name: serie
type: VARCHAR(10)
nullable: true
- name: fecha_emision
type: TIMESTAMP
nullable: false
- name: emisor_rfc
type: VARCHAR(13)
nullable: false
- name: emisor_nombre
type: VARCHAR(300)
nullable: false
- name: subtotal
type: DECIMAL(18,2)
nullable: false
- name: total
type: DECIMAL(18,2)
nullable: false
- name: moneda
type: VARCHAR(3)
nullable: false
- name: estatus
type: VARCHAR(20)
nullable: false
description: pendiente_validar, vigente, cancelado
- name: xml_path
type: VARCHAR(500)
nullable: false
- name: pdf_path
type: VARCHAR(500)
nullable: true
- name: validado_sat
type: BOOLEAN
default: false
- name: fecha_validacion
type: TIMESTAMP
nullable: true
- name: orden_compra_id
type: UUID
nullable: true
foreign_key: ordenes_compra.id
- name: created_at
type: TIMESTAMP
default: NOW()
indexes:
- columns: [uuid]
unique: true
- columns: [tenant_id, emisor_rfc]
- columns: [estatus]
- name: complementos_pago
description: Complementos de pago emitidos
columns:
- name: id
type: UUID
primary_key: true
- name: cfdi_id
type: UUID
nullable: false
foreign_key: cfdi.id
description: CFDI tipo P que contiene el complemento
- name: fecha_pago
type: DATE
nullable: false
- name: forma_pago
type: VARCHAR(2)
nullable: false
- name: moneda
type: VARCHAR(3)
nullable: false
- name: tipo_cambio
type: DECIMAL(10,6)
nullable: true
- name: monto
type: DECIMAL(18,2)
nullable: false
- name: num_operacion
type: VARCHAR(100)
nullable: true
- name: rfc_banco_ordenante
type: VARCHAR(13)
nullable: true
- name: cuenta_ordenante
type: VARCHAR(50)
nullable: true
- name: rfc_banco_beneficiario
type: VARCHAR(13)
nullable: true
- name: cuenta_beneficiario
type: VARCHAR(50)
nullable: true
- name: created_at
type: TIMESTAMP
default: NOW()
indexes:
- columns: [cfdi_id]
- name: complementos_pago_documentos
description: Documentos relacionados en complemento de pago
columns:
- name: id
type: UUID
primary_key: true
- name: complemento_pago_id
type: UUID
nullable: false
foreign_key: complementos_pago.id
- name: cfdi_relacionado_id
type: UUID
nullable: false
foreign_key: cfdi.id
- name: uuid_documento
type: VARCHAR(36)
nullable: false
- name: serie
type: VARCHAR(10)
nullable: true
- name: folio
type: VARCHAR(20)
nullable: false
- name: moneda
type: VARCHAR(3)
nullable: false
- name: equivalencia_dr
type: DECIMAL(10,6)
nullable: true
- name: num_parcialidad
type: INTEGER
nullable: false
- name: imp_saldo_anterior
type: DECIMAL(18,2)
nullable: false
- name: imp_pagado
type: DECIMAL(18,2)
nullable: false
- name: imp_saldo_insoluto
type: DECIMAL(18,2)
nullable: false
- name: objeto_imp_dr
type: VARCHAR(2)
nullable: false
indexes:
- columns: [complemento_pago_id]
- columns: [cfdi_relacionado_id]
# ============================================================================
# PLAN DE IMPLEMENTACIÓN
# ============================================================================
implementation_plan:
phases:
- phase: 1
name: Configuración y infraestructura
duration: 2 semanas
tasks:
- Configurar integración con PAC de pruebas
- Implementar servicio de validación SAT
- Configurar almacenamiento de archivos XML/PDF
- Crear estructura de base de datos
- Configurar certificados de sello digital
deliverables:
- Integración con PAC funcional en ambiente de pruebas
- Base de datos creada y migrada
- Servicio de almacenamiento configurado
- phase: 2
name: Emisión de CFDI (RF-001)
duration: 3 semanas
tasks:
- Implementar generador de XML CFDI 4.0
- Desarrollar servicio de timbrado con PAC
- Crear generador de PDF con representación impresa
- Desarrollar interfaz de captura de CFDI
- Implementar envío por correo electrónico
- Pruebas de timbrado en ambiente de pruebas
deliverables:
- Módulo de emisión de CFDI completo
- Casos de prueba ejecutados
- Documentación de usuario
- phase: 3
name: Cancelación de CFDI (RF-002)
duration: 2 semanas
tasks:
- Implementar servicio de cancelación vía PAC
- Desarrollar flujo de aceptación/rechazo
- Crear interfaz de gestión de cancelaciones
- Implementar notificaciones de cancelación
- Pruebas de cancelación
deliverables:
- Módulo de cancelación funcional
- Sistema de notificaciones integrado
- Casos de prueba ejecutados
- phase: 4
name: Recepción de CFDI (RF-003)
duration: 2 semanas
tasks:
- Implementar parser de XML CFDI
- Desarrollar validador ante SAT
- Crear interfaz de carga de XML
- Implementar asociación con órdenes de compra
- Desarrollar consultas y reportes
deliverables:
- Módulo de recepción completo
- Validación automática ante SAT
- Reportes de CFDI recibidos
- phase: 5
name: Complementos de Pago (RF-004)
duration: 2 semanas
tasks:
- Implementar generador de complemento de pago
- Desarrollar calculadora de parcialidades
- Crear interfaz de aplicación de pagos
- Implementar actualización de saldos
- Integrar con cuentas por cobrar
- Pruebas de complementos
deliverables:
- Módulo de complementos de pago funcional
- Integración con cuentas por cobrar
- Actualización automática de saldos
- phase: 6
name: Pruebas integrales y despliegue
duration: 1 semana
tasks:
- Pruebas de integración end-to-end
- Pruebas de rendimiento
- Migración a ambiente de producción
- Configuración de PAC en producción
- Capacitación a usuarios
- Documentación final
deliverables:
- Sistema probado y validado
- Ambiente de producción configurado
- Usuarios capacitados
- Documentación completa
total_duration: 12 semanas
resources:
- role: Tech Lead
allocation: 100%
- role: Backend Developer
allocation: 100%
count: 2
- role: Frontend Developer
allocation: 100%
- role: QA Engineer
allocation: 50%
- role: DevOps Engineer
allocation: 25%
# ============================================================================
# MÉTRICAS Y KPIs
# ============================================================================
metrics:
business_metrics:
- name: CFDI emitidos por mes
description: Número total de CFDI timbrados exitosamente
target: "> 1000"
measurement: Conteo mensual
- name: Tasa de éxito de timbrado
description: Porcentaje de CFDI timbrados exitosamente vs. intentos
target: "> 98%"
measurement: (Timbrados exitosos / Total intentos) * 100
- name: Tiempo promedio de emisión
description: Tiempo desde captura hasta timbrado exitoso
target: "< 30 segundos"
measurement: Promedio de tiempo por CFDI
- name: Tasa de cancelación
description: Porcentaje de CFDI cancelados vs. emitidos
target: "< 5%"
measurement: (Cancelados / Emitidos) * 100
- name: CFDI recibidos validados
description: Porcentaje de CFDI recibidos validados ante SAT
target: "100%"
measurement: (Validados / Total recibidos) * 100
technical_metrics:
- name: Disponibilidad del servicio
description: Uptime del módulo de facturación
target: "> 99.5%"
measurement: Monitoreo continuo
- name: Tiempo de respuesta API
description: Tiempo promedio de respuesta de endpoints
target: "< 500ms"
measurement: Promedio de p95
- name: Tasa de errores
description: Porcentaje de requests con error
target: "< 1%"
measurement: (Errores / Total requests) * 100
- name: Cobertura de pruebas
description: Porcentaje de código cubierto por pruebas
target: "> 80%"
measurement: Análisis de cobertura
# ============================================================================
# RIESGOS Y MITIGACIONES
# ============================================================================
risks:
- id: RISK-MAE-009-001
description: Indisponibilidad del servicio del PAC
probability: medium
impact: high
mitigation: |
- Implementar sistema de cola para reintentos automáticos
- Configurar PAC de respaldo
- Alertas automáticas al equipo técnico
- SLA con proveedor PAC
- id: RISK-MAE-009-002
description: Cambios en normativa SAT
probability: high
impact: high
mitigation: |
- Monitoreo continuo de publicaciones del SAT
- Arquitectura flexible para adaptación rápida
- Mantener compatibilidad con versiones anteriores
- Equipo de compliance fiscal
- id: RISK-MAE-009-003
description: Problemas con certificados de sello digital
probability: low
impact: critical
mitigation: |
- Alertas de vencimiento 60 días antes
- Proceso documentado de renovación
- Respaldo de certificados en vault seguro
- Procedimiento de emergencia
- id: RISK-MAE-009-004
description: Volumen alto de facturación (cierre de mes)
probability: high
impact: medium
mitigation: |
- Arquitectura escalable horizontalmente
- Auto-scaling en cloud
- Cache de validaciones frecuentes
- Pruebas de carga periódicas
- id: RISK-MAE-009-005
description: Pérdida de archivos XML/PDF
probability: low
impact: high
mitigation: |
- Almacenamiento redundante (S3 con replicación)
- Backups diarios automáticos
- Registro en blockchain (opcional)
- Posibilidad de re-descarga desde PAC
# ============================================================================
# NOTAS Y CONSIDERACIONES
# ============================================================================
notes: |
1. CUMPLIMIENTO NORMATIVO:
- Todas las funcionalidades deben cumplir con el Anexo 20 del SAT
- Mantener actualización con versión vigente de CFDI (actualmente 4.0)
- Consultar regularmente el Diario Oficial de la Federación
2. SEGURIDAD:
- Los certificados de sello digital (CSD) deben almacenarse encriptados
- Implementar logs de auditoría para todas las operaciones
- Control de acceso basado en roles para emisión de CFDI
- Encriptación en tránsito y en reposo para archivos XML
3. INTEGRACIONES:
- Priorizar PAC con mejor uptime y soporte
- Considerar integración con múltiples PAC para redundancia
- Mantener ambiente de pruebas separado (sandbox PAC)
4. EXPERIENCIA DE USUARIO:
- Formularios con autocompletado de catálogos SAT
- Validaciones en tiempo real antes de timbrar
- Mensajes de error claros y accionables
- Descarga masiva de XML y PDF
5. RENDIMIENTO:
- Optimizar para alta concurrencia en cierre de mes
- Implementar procesamiento asíncrono para timbrado
- Cache de catálogos SAT (actualización semanal)
6. REPORTES Y ANALYTICS:
- Dashboard de facturación con métricas clave
- Reportes de CFDI para contabilidad
- Integración con sistema contable
- Exportación a formatos estándar (Excel, PDF, XML)
# ============================================================================
# HISTORIAL DE CAMBIOS
# ============================================================================
change_log:
- version: 1.0.0
date: 2025-12-06
author: Sistema
changes:
- Creación inicial del archivo de trazabilidad
- Definición de 4 requerimientos funcionales principales
- Especificación de integraciones con PAC y SAT
- Definición de modelo de datos
- Plan de implementación en 6 fases
Reference in New Issue View Git Blame Copy Permalink