Skip to main content

Diccionario de Datos y Catálogo de Valores por Defecto

Microservicio Generador de Addendas (msa-facturacion-generador-addendas)​

Versión del Documento: 1.0.0
Fecha: 2026-11-10
Estado: Aprobado para Arquitectura y Desarrollo
Ámbito: Motor de Addendas Assembled, Entidades de Persistencia, Conectores y Configuración


Tabla de Contenido​

  1. Introducción y Objetivos
  2. Convenciones Generales y Comportamiento ante Valores Nulos
  3. Módulo 1: Catálogo de Plantillas (cat_addenda_plantillas)
  4. Módulo 2: Catálogo Global de Tokens Canónicos (cat_addenda_tokens)
  5. Módulo 3: Tokens Custom y Reglas de Cálculo (cat_addenda_plantilla_custom_tokens)
  6. Módulo 4: Reglas de Transformación Condicional (cat_addenda_reglas_transformacion)
  7. Módulo 5: Bitácora de Procesamiento y Telemetría (addenda_bitacora)
  8. Módulo 6: Estrategias de Motor y Enums de Servicio
  9. Módulo 7: Modificadores de Formato y Sintaxis en Plantilla
  10. Módulo 8: Catálogo Maestro de Tokens Canónicos Estándar
  11. Matriz Resumen de Valores por Defecto (Default Matrix)
  12. Módulo 9: Orden de Poblado y Dependencias Relacionales para Inserciones

1. Introducción y Objetivos​

El presente Diccionario de Datos tiene como objetivo formalizar y documentar exhaustivamente todos los atributos, campos y parámetros del microservicio generador de addendas que disponen de un valor por defecto, una enumeración acotada de valores permitidos o una regla de fallback funcional.

Este documento sirve como referencia única de la verdad para:

  • Desarrolladores: Implementación de validaciones, DTOs, entidades JPA y mapeos de datos.
  • Administradores de Configuración: Alta y mantenimiento de plantillas XML, reglas de transformación y tokens custom sin necesidad de modificar el código fuente.
  • QA / Pruebas: Definición de casos límite, matrices de equivalencia y validación de comprobantes.

2. Convenciones Generales y Comportamiento ante Valores Nulos​

Cuando el motor orquestador de addendas procesa una factura o nota de crédito, aplica la siguiente jerarquía de resolución ante campos nulos o no provistos:

  1. Prevalencia del Catálogo: Si un token o parámetro no es suministrado por los conectores de origen (SAP, Oracle EBS, AS400, etc.), el motor busca el valor definido en valor_default.
  2. Resiliencia Aritmética: En cálculos matemáticos, cualquier operando nulo o inexistente es sustituido automáticamente por 0.00. Si ocurre una división por cero, el resultado evalúa de forma segura a 0.00 sin abortar el flujo del comprobante.
  3. Escapado XML Seguro: Todo valor de texto resultante es automáticamente saneado contra entidades XML (&, <, >, ", ').

3. Módulo 1: Catálogo de Plantillas (cat_addenda_plantillas)​

Mapeado en la entidad PlantillaAddendaDO y DTO PlantillaAddendaVO.

CampoTipoValor por DefectoValores PermitidosSignificado Funcional
estadoVARCHAR(20)'PUBLICADA'BORRADOR
PUBLICADA
RETIRADA
OBSOLETA
Controla el ciclo de vida de la plantilla y su disponibilidad para el motor de generación.
tipo_comprobanteVARCHAR(5)ObligatorioI
E
T
P
N
Tipo de comprobante fiscal SAT según el Anexo 20 para el cual aplica la estructura XML.
dn_activoBOOLEANTRUETRUE
FALSE
Bandera de borrado lógico estándar del arquetipo Alpura (BaseDO).
dn_usuario_creadorVARCHAR(255)'ADMIN'Texto libreUsuario o proceso de servicio que registró originalmente la plantilla.
dn_usuario_modificadorVARCHAR(255)'ADMIN'Texto libreUsuario o proceso que realizó la última alteración de la configuración.
dd_fecha_creacionTIMESTAMPCURRENT_TIMESTAMPFecha/Hora ISOMarca de tiempo del alta en base de datos.
dd_fecha_modificacionTIMESTAMPCURRENT_TIMESTAMPFecha/Hora ISOMarca de tiempo de la última actualización.

3.1 Detalle de Estados de la Plantilla (estado)​

  • PUBLICADA (Default): La plantilla está activa, aprobada y disponible para ser resuelta por el orquestador en tiempo real según la fecha de vigencia del comprobante.
  • BORRADOR: Plantilla en proceso de diseño o calibración técnica. El motor productivo la ignora; únicamente puede invocarse en endpoints de simulación/testeo.
  • RETIRADA: Plantilla deshabilitada administrativamente por descontinuación del cliente comercial o suspensión de operaciones.
  • OBSOLETA: Versión histórica reemplazada por una versión más moderna de la addenda con fecha de vigencia superior.

3.2 Detalle de Tipos de Comprobante (tipo_comprobante)​

  • I (Ingreso): Facturas comerciales de venta ordinarias de Alpura. Representa el 90% de las addendas de cadenas de retail (Soriana, Fresko, Tiendas 3B, El Duero, Walmart, etc.).
  • E (Egreso): Notas de crédito por concepto de devoluciones de producto caducado, descuentos por pronto pago o bonificaciones comerciales (ej. OXXO Consolidada NC).
  • T (Traslado): Cartas porte o comprobantes de movimiento de mercancía entre Cedis/Plantas.
  • P (Recepción de Pagos): Recibos electrónicos de pago (REP / Complemento de Pago).
  • N (Nómina): Recibos de nómina (no suele requerir addenda comercial).

4. Módulo 2: Catálogo Global de Tokens Canónicos (cat_addenda_tokens)​

Define el catálogo maestro de variables reemplazables en el motor. Permite al generador saber el origen, destino y método de obtención de cualquier token.

CampoTipoValor por DefectoValores PermitidosSignificado Funcional
tipo_origenVARCHAR(40)ObligatorioFACTURA
CLIENTE
PEDIDO
RUBROS_IMPUESTOS
SISTEMA_CFDI
Clasificación del dominio de procedencia de los datos para ruteo del conector Spring.
conector_asociadoVARCHAR(60)ObligatorioFacturaConnectorService
ClienteConnectorService
PedidoConnectorService
RubrosConnectorService
LegacyConnectorServiceImpl
Nombre del bean Spring encargado de extraer el DTO de datos.
sistema_fuenteVARCHAR(50)ObligatorioDB Billing
Cat Generales
Oracle EBS
AS400
CFDI Core
Sistema legado o base de datos externa de donde se extrae la información.
estrategia_extraccionVARCHAR(40)'DIRECT_DTO_FIELD'DIRECT_DTO_FIELD
JSON_PATH
SQL_COLUMN
COMPUTED
HEADER_PARAM
Mecanismo técnico empleado por el motor para leer el valor del contexto.
alcanceVARCHAR(20)'ENCABEZADO'ENCABEZADO
DETALLE
Nivel estructural del token: una sola vez por factura o una vez por cada partida de producto.
tipo_datoVARCHAR(20)'STRING'STRING
NUMERIC
INTEGER
DATE
DATETIME
BOOLEAN
Tipo de dato que determina la coerción, redondeo y formateo del valor.
formato_defaultVARCHAR(50)NULLMáscaras estándar (ver detalle abajo)Formato aplicado si el token no declara modificador explícito en la plantilla XML.
es_obligatorioBOOLEANFALSETRUE
FALSE
Si es TRUE, el motor aborta la generación con error de validación si el valor resulta nulo o vacío.
valor_defaultVARCHAR(255)'' (o '0.00')Texto / Valor fallbackValor de respaldo inyectado si el conector retorna nulo y es_obligatorio = FALSE.

4.1 Detalle de Tipo de Origen (tipo_origen)​

  • FACTURA: Datos extraídos de la cabecera fiscal del comprobante (serie, folio, subtotal, total, moneda, tipo de cambio).
  • CLIENTE: Datos maestros del receptor (RFC, razón social, número de cliente asignado, GLN corporativo, sucursal o tienda).
  • PEDIDO: Datos comerciales o logísticos provenientes de la orden de compra, remisión, entrada de almacén o embarque (Oracle EBS).
  • RUBROS_IMPUESTOS: Impuestos trasladados y retenidos, tasas de IVA/IEPS y bases gravables (AS400 / Core de Facturación).
  • SISTEMA_CFDI: Metadatos internos de timbrado (UUID fiscal, certificado, sello digital, versión Anexo 20).

4.2 Detalle de Estrategias de Extracción (estrategia_extraccion)​

  • DIRECT_DTO_FIELD (Default): Lectura por reflexión o getter directo sobre las propiedades de los objetos de transporte (AddendaHeaderVO, AddendaClientVO, AddendaItemVO, AddendaTaxVO).
  • JSON_PATH: Extracción mediante expresión JsonPath ($.comprobante.complemento...) navegando sobre payloads no estructurados.
  • SQL_COLUMN: Consulta directa contra columna relacional en esquema billing.
  • COMPUTED: Valor calculado dinámicamente mediante código de servicio o función de orquestación.
  • HEADER_PARAM: Lectura desde encabezados HTTP de la petición entrante.

4.3 Detalle de Alcance (alcance)​

  • ENCABEZADO (Default): Variables a nivel comprobante. Tienen un valor único global en toda la addenda (ej. $Encabezadototal$).
  • DETALLE: Variables que iteran por cada partida de mercancía. Su valor varía en cada fila de la lista de partidas (ej. $DetalleSKU$, $Detallecantidad$).

4.4 Detalle de Tipos de Dato (tipo_dato)​

  • STRING (Default): Cadenas alfanuméricas. Se asegura de escapar caracteres reservados XML.
  • NUMERIC: Valores decimales monetarios o cantidades continuas. Soportan precisión BigDecimal.
  • INTEGER: Números enteros sin fracción (ej. número de línea, cantidad de bultos).
  • DATE: Fechas de calendario (año, mes, día).
  • DATETIME: Marcas de tiempo completas con hora, minutos y segundos.
  • BOOLEAN: Valores lógicos representados como true/false o 1/0.

5. Módulo 3: Tokens Custom y Reglas de Cálculo (cat_addenda_plantilla_custom_tokens)​

Mapeado en la entidad PlantillaCustomTokenDO y DTO PlantillaCustomTokenVO.

CampoTipoValor por DefectoValores PermitidosSignificado Funcional
alcanceVARCHAR(20)'ENCABEZADO'ENCABEZADO
DETALLE
Determina si el token custom se calcula a nivel cabecera o de forma repetitiva por partida.
tipo_valorVARCHAR(20)ObligatorioFIJO
CALCULADO
Naturaleza del token: constante inmutable o fórmula matemática resuelta en tiempo de ejecución.
tipo_dato_resultadoVARCHAR(20)'STRING'STRING
NUMERIC
INTEGER
DATE
BOOLEAN
Tipo de dato esperado para el valor final evaluado.
escala_decimalesINTEGER2Entero $\ge 0$ (0, 1, 2, 3, 4, ...)Número de dígitos fraccionarios aplicados en el redondeo BigDecimal.setScale().
tipo_redondeoVARCHAR(20)'HALF_UP'HALF_UP
HALF_EVEN
CEILING
FLOOR
UP
DOWN
Algoritmo de redondeo aritmético para resolver fracciones decimales.
orden_evaluacionINTEGER1Entero $\ge 1$ (1, 2, 3, ...)Secuencia determinista de resolución. Permite cálculos encadenados en cascada.

5.1 Detalle de Tipos de Valor (tipo_valor)​

  • FIJO: Constante literal exigida por el cliente comercial que nunca varía entre facturas (ej. código de proveedor asignado $CustomNumAcreedor$ = 'ATZ 983527' o tipo de documento fijo $CustomClaseDoc$ = '002').
  • CALCULADO: Expresión matemática formulada a partir de otros tokens estándar o custom previos (ej. $Encabezadodescuentos$ / $Encabezadototal$).

5.2 Detalle de Tipos de Redondeo (tipo_redondeo)​

  • HALF_UP (Default SAT): Redondeo estándar comercial. Si el decimal descartado es $\ge 5$, redondea hacia arriba; de lo contrario trunca hacia abajo (ej. 2.555 $\rightarrow$ 2.56).
  • HALF_EVEN (Bancario / Financiero): Redondea hacia el vecino par más cercano. Minimiza el sesgo acumulativo en grandes volúmenes de transacciones (ej. 2.545 $\rightarrow$ 2.54, 2.555 $\rightarrow$ 2.56).
  • CEILING: Redondea siempre hacia infinito positivo (ej. 2.511 $\rightarrow$ 2.52).
  • FLOOR: Redondea siempre hacia infinito negativo (truncamiento directo positivo) (ej. 2.599 $\rightarrow$ 2.59).
  • UP: Redondeo alejándose de cero.
  • DOWN: Truncado puro hacia cero.

5.3 Operadores y Funciones en Fórmulas Aritméticas​

Las expresiones en expresion_calculo soportan:

  • Operadores Básicos: Suma (+), Resta (-), Multiplicación (*), División (/).
  • Agrupación: Paréntesis anidados ( ) para precedencia de operaciones.
  • Funciones Matemáticas: abs(x) (valor absoluto), round(x, d) (redondeo manual), min(a, b), max(a, b), ceil(x), floor(x).
  • Protección ante División por Cero: Si el denominador resuelve a 0 o nulo, la expresión retorna automáticamente 0.00 sin arrojar excepción.

6. Módulo 4: Reglas de Transformación Condicional (cat_addenda_reglas_transformacion)​

Permite la homologación de unidades de medida (UOM), conversión de códigos internos a estándares del cliente y reasignaciones condicionales.

CampoTipoValor por DefectoValores PermitidosSignificado Funcional
operacionVARCHAR(10)'=' (o NULL)= (o NULL)
<> o !=
=r
<>r o !=r
REGEX
Operador lógico que determina la condición de activación de la regla.
token_origenVARCHAR(100)ObligatorioSintaxis $NombreToken$Token cuyo valor extraído se inspecciona en la condición.
valor_actualTEXTObligatorioLiteral o lista separada por comasValor(es) contra los que se compara el contenido de token_origen.
nuevo_valorTEXTObligatorioLiteral o sintaxis $Token$Valor resultante que se inyectará si la condición se cumple.
token_destinoVARCHAR(100)NULLSintaxis $TokenDestino$Token que recibirá el resultado (requerido solo para operaciones =r y <>r).
orden_ejecucionINTEGER1Entero $\ge 1$ (1, 2, 3, ...)Secuencia de ejecución de las reglas antes del renderizado de la plantilla.

6.1 Detalle de Operaciones (operacion)​

  • = o NULL (Igualdad directa / Reemplazo in-situ): Si el valor de token_origen coincide con valor_actual (o con cualquiera de los elementos en una lista separada por comas, ej. 'PIEZA,PZA,PZ'), el contenido del mismo token_origen se reemplaza por nuevo_valor (ej. 'PCE').
  • <> o != (Desigualdad in-situ): Si el valor de token_origen es distinto de valor_actual, su contenido se reemplaza por nuevo_valor.
  • =r (Igualdad con Redirección a Token Destino): Si token_origen coincide con valor_actual, el nuevo_valor (que puede ser otro token o un literal) se almacena en el campo especificado en token_destino. El token origen original no se destruye.
  • <>r o !=r (Desigualdad con Redirección a Token Destino): Si token_origen es distinto de valor_actual, se escribe el nuevo_valor en token_destino.
  • REGEX (Coincidencia por Expresión Regular): Evalúa el patrón de expresión regular definido en valor_actual y sustituye según nuevo_valor.

7. Módulo 5: Bitácora de Procesamiento y Telemetría (addenda_bitacora)​

Registra la auditoría y rendimiento de cada comprobante ensamblado por el motor.

CampoTipoValor por DefectoValores PermitidosSignificado Funcional
estado_procesoVARCHAR(25)'EXITOSO'EXITOSO
ERROR_VALIDACION
ERROR_CALCULO
ERROR_TRANSFORMACION
ERROR_TIMEOUT
Resultado global de la generación de la addenda.
motor_usadoVARCHAR(30)'THYMELEAF_XML'THYMELEAF_XML
LEGACY_REGEX
Motor tecnológico responsable de compilar el XML final.
hash_addendaVARCHAR(64)NULLHexadecimal SHA-256Checksum criptográfico del nodo XML generado para detección de cambios.
tiempo_procesamiento_msBIGINT0Entero $\ge 0$Milisegundos transcurridos desde la recepción del payload hasta el retorno del XML.

7.1 Detalle de Estados de Proceso (estado_proceso)​

  • EXITOSO (Default): El XML de la addenda se construyó correctamente, cumplió las validaciones y se integró al comprobante.
  • ERROR_VALIDACION: Falló la validación sintáctica del XML, el esquema XSD de la cadena o faltó un token obligatorio (es_obligatorio = true).
  • ERROR_CALCULO: Ocurrió un error semántico irrecuperable en una fórmula de token custom.
  • ERROR_TRANSFORMACION: Error durante la ejecución de las reglas de sustitución o redirección de tokens.
  • ERROR_TIMEOUT: Uno de los conectores fuente excedió el tiempo límite de respuesta configurado.

8. Módulo 6: Estrategias de Motor y Enums de Servicio​

8.1 Estrategia de Selección del Motor (AddendaStrategyEnum)​

Controla el flujo de ensamblado dentro del patrón Strategy del microservicio:

Valor EnumModo de OperaciónSignificado y Flujo Funcional
ASSEMBLEDMotor Moderno (Default)Orquestación mediante conectores de Spring, resolución relacional de cat_addenda_* y renderizado XML seguro con Thymeleaf 3.x.
LEGACYMotor HistóricoConsulta a tablas legadas (billing.alp_facturacion_addenda) con payloads JSONB monolíticos y reemplazos de texto antiguos.

8.2 Catálogo de Códigos de Error (ServiceErrorCodeEnum)​

CódigoIdentificadorSignificado FuncionalAcción de Recuperación
0UNKNOWN_ERRORError no categorizado o excepción no controlada en el runtime.Revisar logs del microservicio en OpenSearch.
1REQUIRED_FIELDUn campo obligatorio del comprobante o de la plantilla está vacío.Verificar payload o marcar token con es_obligatorio = false.
2EXCEEDS_MAX_LENGTHUn valor supera la longitud de caracteres permitida por la base de datos o XSD.Aplicar modificador de longitud {Size_N}.
404NO_RESULTSLa consulta a un conector externo no devolvió registros.Revisar folios en Oracle EBS / AS400.
500ADDENDA_PROCESSING_ERRORFallo interno durante la generación del XML de addenda.Validar trazabilidad en addenda_bitacora.
1001ADDENDA_CADENA_REQUIREDLa petición no especificó la cadena comercial destino.Enviar atributo cadena en la petición JSON.
1002ADDENDA_REQUEST_EMPTYEl payload de la petición llegó completamente vacío.Enviar cuerpo JSON válido.
2001PLANTILLA_NOT_FOUNDNo existe plantilla activa y vigente para la cadena y fecha de comprobante.Dar de alta versión en cat_addenda_plantillas.
2002PLANTILLA_DUPLICATE_VERSIONIntento de registrar una versión que colisiona con otra ya existente para la misma fecha.Incrementar versión semántica o ajustar fecha de vigencia.
2003PLANTILLA_INVALID_XMLEl XML configurado en la plantilla está mal formado o no cierra etiquetas.Validar estructura XML con herramienta sintáctica.
2004CUSTOM_TOKEN_NOT_FOUNDUna fórmula matemática hace referencia a un token que no existe en el catálogo.Registrar el token dependiente en cat_addenda_tokens.
2005PLANTILLA_REQUIRED_FIELDFalta un atributo fundamental en el DTO de configuración de plantilla.Revisar anotaciones @NotEmpty en PlantillaAddendaVO.
3001CATALOG_SERVICE_ERROREl microservicio de Catálogos Maestros de Alpura no respondió.Verificar conectividad y circuit breaker Resilience4j.

9. Módulo 7: Modificadores de Formato y Sintaxis en Plantilla​

En las plantillas XML almacenadas en cat_addenda_plantillas, los tokens pueden incluir modificadores de presentación con la sintaxis $Token{modificador}$.

ModificadorTipo AplicableEjemplo de UsoComportamiento Funcional por Defecto
{Size_N}STRING / INTEGER$EncabezadofolioRecepcion{Size_10}$Longitud Fija: Si el valor tiene menos de $N$ caracteres, rellena por defecto con espacios a la derecha si es texto, o con ceros a la izquierda si es numérico. Si supera $N$, trunca a la longitud máxima.
{yyMMdd}DATE / DATETIME$EncabezadoFechaComprobante{yyMMdd}$Formato corto de fecha (ej. 2026-11-10 $\rightarrow$ 261110).
{yyyyMMdd}DATE / DATETIME$EncabezadoFechaComprobante{yyyyMMdd}$Formato estándar de fecha de 8 dígitos (ej. 20261110).
{yyyy-MM-dd}DATE / DATETIME$EncabezadoFechaEntrega{yyyy-MM-dd}$Formato ISO satelital (ej. 2026-11-10).
{0.00}NUMERIC$DetalleprecioUnitario{0.00}$Fuerza 2 decimales fijos con punto flotante (ej. 15 $\rightarrow$ 15.00).
{0.0000}NUMERIC$DetalleprecioUnitario{0.0000}$Fuerza 4 decimales de precisión para precios unitarios de retail.

10. Módulo 8: Catálogo Maestro de Tokens Canónicos Estándar​

A continuación se detallan los tokens globales estándar provistos por la arquitectura, clasificados por su ámbito y con sus valores por defecto en caso de ausencia de información en los sistemas de origen:

10.1 Tokens de Encabezado y Factura Fiscal (tipo_origen = 'FACTURA')​

Token CanónicoConector AsignadoTipo DatoFormato DefaultValor DefaultObligatorioSignificado Funcional
$EncabezadoserieComprobante$FacturaConnectorServiceSTRING—''SíSerie fiscal SAT asignada al comprobante.
$EncabezadofolioComprobante$FacturaConnectorServiceSTRING—''SíFolio fiscal correlativo de facturación.
$Encabezadosubtotal$FacturaConnectorServiceNUMERIC0.00'0.00'SíImporte subtotal antes de descuentos e impuestos.
$Encabezadodescuentos$FacturaConnectorServiceNUMERIC0.00'0.00'NoDescuento total aplicado a nivel comprobante.
$Encabezadototal$FacturaConnectorServiceNUMERIC0.00'0.00'SíImporte total final a pagar.
$Encabezadomoneda$FacturaConnectorServiceSTRING—'MXN'SíClave de moneda según catálogo SAT ISO 4217.
$EncabezadotipoCambio$FacturaConnectorServiceNUMERIC0.00'1.00'NoTipo de cambio fijado para la divisa (1.00 si MXN).
$EncabezadoFechaComprobante$FacturaConnectorServiceDATEyyyy-MM-dd''SíFecha oficial de emisión del comprobante.
$EncabezadonumProveedor$FacturaConnectorServiceSTRING—''NoNúmero de proveedor corporativo asignado por la cadena.
$EncabezadodiasPago$FacturaConnectorServiceINTEGER—'0'NoDías de crédito pactados para liquidación de factura.

10.2 Tokens de Cliente y Receptor (tipo_origen = 'CLIENTE')​

Token CanónicoConector AsignadoTipo DatoFormato DefaultValor DefaultObligatorioSignificado Funcional
$ClienteRFC$ClienteConnectorServiceSTRING—''SíRFC tributario oficial del cliente receptor.
$EncabezadoreceptorNombreReceptor$ClienteConnectorServiceSTRING—''SíDenominación o razón social oficial del receptor.
$EncabezadoreceptorNumeroCliente$ClienteConnectorServiceSTRING—''NoCódigo interno de cliente en el ERP de Alpura.
$EncabezadoreceptorGlnReceptor$ClienteConnectorServiceSTRING—''NoGlobal Location Number (GLN) del corporativo comprador.
$EncabezadoreceptorNumeroSucursal$ClienteConnectorServiceSTRING—''NoNúmero o identificador de la tienda o sucursal destino.
$EncabezadoreceptorGlnSucursal$ClienteConnectorServiceSTRING—''NoGLN asignado al punto físico de entrega de mercancía.

10.3 Tokens de Logística y Orden de Compra (tipo_origen = 'PEDIDO')​

Token CanónicoConector AsignadoTipo DatoFormato DefaultValor DefaultObligatorioSignificado Funcional
$EncabezadonumOrdenCompra$PedidoConnectorServiceSTRING—''NoOrden de Compra (OC / Purchase Order) emitida por el cliente.
$EncabezadofolioRecepcion$PedidoConnectorServiceSTRING—''NoFolio de entrada al almacén / contra-recibo en tienda.
$EncabezadoFechaEntrega$PedidoConnectorServiceDATEyyyy-MM-dd''NoFecha efectiva de recepción física de las mercancías.

10.4 Tokens de Partidas de Detalle (tipo_origen = 'PEDIDO', alcance = 'DETALLE')​

Token CanónicoConector AsignadoTipo DatoFormato DefaultValor DefaultObligatorioSignificado Funcional
$DetalleNumLinea$PedidoConnectorServiceINTEGER—'1'SíSecuencia o número ordinal de la partida en el comprobante.
$DetalleSKU$PedidoConnectorServiceSTRING—''SíCódigo de producto interno Alpura o código de barras EAN/GTIN.
$Detalledescripcion$PedidoConnectorServiceSTRING—''SíNombre comercial y descripción detallada del artículo.
$Detallecantidad$PedidoConnectorServiceNUMERIC0.00'0'SíUnidades o piezas físicas facturadas en la partida.
$DetalleunidadMedida$PedidoConnectorServiceSTRING—'PZA'SíClave de unidad de medida original (ej. PZA, CJA, LT).
$DetalleprecioUnitario$PedidoConnectorServiceNUMERIC0.00'0.00'SíPrecio unitario pactado antes de impuestos.
$Detalleimporte$PedidoConnectorServiceNUMERIC0.00'0.00'SíImporte total bruto de la línea (cantidad * precioUnitario).
$DetalleDescuento$PedidoConnectorServiceNUMERIC0.00'0.00'NoDescuento específico concedido en la partida.

10.5 Tokens de Impuestos (tipo_origen = 'RUBROS_IMPUESTOS')​

Token CanónicoConector AsignadoAlcanceTipo DatoFormato DefaultValor DefaultSignificado Funcional
$Encabezadoimpuestos$RubrosConnectorServiceENCABEZADONUMERIC0.00'0.00'Total consolidado de impuestos trasladados del comprobante.
$DetalleTasaIVA$RubrosConnectorServiceDETALLENUMERIC0.00'16.00'Tasa porcentual de IVA aplicada al producto (ej. 16.00 o 0.00).
$DetallemontoIva$RubrosConnectorServiceDETALLENUMERIC0.00'0.00'Importe monetario de IVA calculado para la partida específica.

11. Matriz Resumen de Valores por Defecto (Default Matrix)​

Esta matriz resume los valores por defecto automáticos aplicados en cada capa del sistema cuando un valor es omitido en las peticiones o configuraciones:

+------------------------------------+-------------------------+---------------------------------+
| Entidad / Tabla | Atributo | Valor por Defecto Aplicado |
+------------------------------------+-------------------------+---------------------------------+
| cat_addenda_plantillas | estado | 'PUBLICADA' |
| cat_addenda_plantillas | dn_activo | true |
| cat_addenda_plantillas | dn_usuario_creador | 'ADMIN' |
| cat_addenda_plantillas | dd_fecha_creacion | CURRENT_TIMESTAMP |
| cat_addenda_tokens | estrategia_extraccion | 'DIRECT_DTO_FIELD' |
| cat_addenda_tokens | alcance | 'ENCABEZADO' |
| cat_addenda_tokens | tipo_dato | 'STRING' |
| cat_addenda_tokens | es_obligatorio | false |
| cat_addenda_tokens | valor_default (String) | '' (cadena vacía) |
| cat_addenda_tokens | valor_default (Numeric) | '0.00' |
| cat_addenda_tokens | valor_default (Integer) | '0' |
| cat_addenda_tokens | dn_activo | true |
| cat_addenda_plantilla_custom_tokens| alcance | 'ENCABEZADO' |
| cat_addenda_plantilla_custom_tokens| tipo_dato_resultado | 'STRING' (o 'NUMERIC' si fórmula)|
| cat_addenda_plantilla_custom_tokens| escala_decimales | 2 |
| cat_addenda_plantilla_custom_tokens| tipo_redondeo | 'HALF_UP' |
| cat_addenda_plantilla_custom_tokens| orden_evaluacion | 1 |
| cat_addenda_plantilla_custom_tokens| dn_activo | true |
| cat_addenda_reglas_transformacion | operacion | '=' |
| cat_addenda_reglas_transformacion | orden_ejecucion | 1 |
| cat_addenda_reglas_transformacion | dn_activo | true |
| addenda_bitacora | estado_proceso | 'EXITOSO' |
| addenda_bitacora | motor_usado | 'THYMELEAF_XML' |
| Petición API (AddendaRequestVO) | legacy | false (estrategia ASSEMBLED) |
| Petición API (AddendaRequestVO) | tipoComprobante | 'I' (Ingreso) |
| Evaluación Fórmulas Aritméticas | Denominador cero | 0.00 (protección automática) |
| Evaluación Fórmulas Aritméticas | Operando nulo | 0.00 (coerción automática) |
| Formateo de Texto {Size_N} | Relleno Alfanumérico | Espacios a la derecha |
| Formateo de Texto {Size_N} | Relleno Numérico | Ceros a la izquierda |
+------------------------------------+-------------------------+---------------------------------+

12. Módulo 9: Orden de Poblado y Dependencias Relacionales para Inserciones​

Para poblar las tablas del nuevo modelo de addendas sin violar restricciones de integridad referencial (FOREIGN KEY) ni dependencias funcionales lógicas, se debe seguir un orden topológico estricto.

12.1 Diagrama de Dependencias e Inserción​


12.2 Clasificación de Dependencias por Nivel de Inserción​

A continuación se detalla qué tablas deben estar pobladas obligatoriamente antes de intentar insertar en cada tabla nueva:

Tabla a Poblar (Hija / Destino)Tablas que Deben Estar Pobladas Antes (Padres)Tipo de DependenciaColumnas InvolucradasConsecuencia si No Está Poblada
cat_addenda_plantillasNinguna (Tabla Maestra Raíz)Independienteid_plantilla (PK)N/A. Puede insertarse en cualquier momento sin dependencias previas.
cat_addenda_tokensNinguna (Catálogo Global)Independienteid_token (PK), clave_token (UK)N/A. Puede insertarse en cualquier momento.
cat_addenda_plantilla_custom_tokens1. cat_addenda_plantillas
2. cat_addenda_tokens
Física (FK)
Lógica (Fórmula)
id_plantilla $\rightarrow$ cat_addenda_plantillas.id_plantilla
tokens_dependientes $\rightarrow$ clave_token
Error SQLState 23503: Violación de clave foránea fk_custom_tokens_plantilla. En ejecución, error CUSTOM_TOKEN_NOT_FOUND (2004).
cat_addenda_reglas_transformacion1. cat_addenda_plantillas
2. cat_addenda_tokens
Física (FK)
Lógica (Regla)
id_plantilla $\rightarrow$ cat_addenda_plantillas.id_plantilla
token_origen / token_destino $\rightarrow$ clave_token
Error SQLState 23503: Violación de clave foránea fk_reglas_transformacion_plantilla. En ejecución, la regla no encontrará el token origen.
user_tblNinguna (Catálogo de Seguridad)Independienteuser_id (PK), email (UK)N/A. Debe poblarse para vincular usuarios de auditoría (dn_usuario_creador).
addenda_bitacora1. cat_addenda_plantillas
2. alp_facturacion_comprobante
3. user_tbl
Lógica / Telemetríaid_plantilla, id_facturacion_comprobante, usuario_ejecutorLos registros de auditoría quedarán huérfanos si los identificadores de comprobante o plantilla no existen.
alp_facturacion_comprobante
(Pruebas E2E operativas)
1. alp_facturacion_emisor
2. alp_facturacion_receptor
3. alp_facturacion_impuestos
Física (FK) de db.sqlid_emisor $\rightarrow$ alp_facturacion_emisor.id
id_receptor $\rightarrow$ alp_facturacion_receptor.id
id_impuestos $\rightarrow$ alp_facturacion_impuestos.id
Error SQLState 23503: Violación de FKs fiscales (fk_alp_facturacion_comprobante_emisor, etc.).
alp_facturacion_factura
(Pruebas E2E operativas)
1. alp_facturacion_comprobante
2. alp_facturacion_remision
Física (FK) de db.sqlid_comprobante $\rightarrow$ alp_facturacion_comprobante.id
id_remision $\rightarrow$ alp_facturacion_remision.id
Error SQLState 23503: Violación de fk_alp_facturacion_factura_comprobante o fk_alp_facturacion_factura_remision.

12.3 Detalle de Restricciones Físicas de Integridad (Foreign Keys)​

Las restricciones de clave foránea implementadas en la base de datos que dictan este comportamiento son:

  1. fk_custom_tokens_plantilla:

    ALTER TABLE billing.cat_addenda_plantilla_custom_tokens
    ADD CONSTRAINT fk_custom_tokens_plantilla
    FOREIGN KEY (id_plantilla)
    REFERENCES billing.cat_addenda_plantillas (id_plantilla)
    ON DELETE CASCADE;
    • Comportamiento: No es posible registrar un token custom (fijo o fórmula) si su id_plantilla no existe previamente en cat_addenda_plantillas. Si se elimina la plantilla, se eliminan en cascada sus tokens custom asociados.
  2. fk_reglas_transformacion_plantilla:

    ALTER TABLE billing.cat_addenda_reglas_transformacion
    ADD CONSTRAINT fk_reglas_transformacion_plantilla
    FOREIGN KEY (id_plantilla)
    REFERENCES billing.cat_addenda_plantillas (id_plantilla)
    ON DELETE CASCADE;
    • Comportamiento: Las reglas de transformación condicional están sujetas a la existencia previa de la plantilla asociada.
  3. Restricciones de Facturación Operativa (desde docs/db.sql):

    • alp_facturacion_comprobante exige que existan previamente registros en alp_facturacion_emisor, alp_facturacion_receptor y alp_facturacion_impuestos.
    • alp_facturacion_factura exige la existencia simultánea de alp_facturacion_comprobante y alp_facturacion_remision.

12.4 Dependencias Lógicas y Semánticas del Motor​

Más allá de las restricciones forzadas por el motor de PostgreSQL, existen dependencias semánticas críticas para el correcto funcionamiento del generador:

  1. Tokens Canónicos vs Fórmulas Custom:

    • Al registrar un token calculado en cat_addenda_plantilla_custom_tokens con una expresión aritmética (ej. $Encabezadodescuentos$ / $Encabezadototal$), ambos tokens deben existir previamente registrados en cat_addenda_tokens.
    • Si la fórmula utiliza otro token custom (cálculo en cascada, como $DetalleTotalLinea$ = $DetalleSubtotalNeto$ + $DetalleIvaCalculado$), los tokens previos deben tener un orden_evaluacion estrictamente menor (orden_evaluacion = 1 y 2 resueltos antes de 3).
  2. Reglas de Transformación Condicional:

    • En cat_addenda_reglas_transformacion, token_origen debe corresponder a un token extraído por los conectores (ej. $DetalleunidadMedida$).
    • Si la operación es =r o <>r, el campo token_destino debe existir en el contexto de tokens para que el valor resultante pueda ser inyectado y leído posteriormente en la plantilla XML.
  3. Resolución de Plantilla por Comprobante:

    • Para que el orquestador genere la addenda de un comprobante en runtime, en cat_addenda_plantillas debe existir un registro donde cadena_codigo coincida con el cliente/cadena, tipo_comprobante coincida con el CFDI (I o E), estado = 'PUBLICADA', y fecha_inicio_vigencia <= fecha_emision_cfdi <= COALESCE(fecha_fin_vigencia, CURRENT_TIMESTAMP).

12.5 Secuencia Recomendada de Ejecución de Scripts (Paso a Paso)​

Para poblar una base de datos limpia de pruebas o un ambiente nuevo, se debe ejecutar la carga de datos en el siguiente orden secuencial exacto (como está estructurado en examples.sql):

  1. Paso 1: Insertar catálogo global de tokens en cat_addenda_tokens.
  2. Paso 2: Insertar plantillas maestras en cat_addenda_plantillas (obteniendo sus id_plantilla).
  3. Paso 3: Insertar tokens custom fijos y calculados en cat_addenda_plantilla_custom_tokens (asociados a sus id_plantilla).
  4. Paso 4: Insertar reglas de transformación en cat_addenda_reglas_transformacion (asociadas a sus id_plantilla).
  5. Paso 5: Insertar usuarios base en user_tbl.
  6. Paso 6 (Opcional - Pruebas Operativas): Insertar en alp_facturacion_emisor, alp_facturacion_receptor, alp_facturacion_impuestos y alp_facturacion_remision.
  7. Paso 7 (Opcional - Pruebas Operativas): Insertar comprobantes en alp_facturacion_comprobante enlazando los IDs del Paso 6.
  8. Paso 8 (Opcional - Pruebas Operativas): Insertar factura en alp_facturacion_factura enlazando comprobante y remisión.
  9. Paso 9: Registrar eventos o pruebas en addenda_bitacora.

12.6 Secuencia Inversa de Limpieza / Despoblado (TRUNCATE / ROLLBACK)​

Si se requiere reiniciar o limpiar los datos de prueba, la secuencia de borrado debe ser la inversa para evitar errores de clave foránea:

-- Opción A: Vaciado seguro de tablas de configuración en cascada
TRUNCATE TABLE
billing.addenda_bitacora,
billing.cat_addenda_reglas_transformacion,
billing.cat_addenda_plantilla_custom_tokens,
billing.cat_addenda_plantillas,
billing.cat_addenda_tokens,
billing.user_tbl
CASCADE;

-- Opción B: Si también se incluyen datos operativos de prueba
TRUNCATE TABLE
billing.alp_facturacion_factura,
billing.alp_facturacion_comprobante,
billing.alp_facturacion_remision,
billing.alp_facturacion_impuestos,
billing.alp_facturacion_receptor,
billing.alp_facturacion_emisor
CASCADE;


[!NOTE] Para cualquier adición de nuevos tokens custom o plantillas, consulte este diccionario para asegurar la compatibilidad con los tipos de redondeo, escalas decimales y reglas de precedencia soportadas por el motor Thymeleaf XML.