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
- Introducción y Objetivos
- Convenciones Generales y Comportamiento ante Valores Nulos
- Módulo 1: Catálogo de Plantillas (
cat_addenda_plantillas) - Módulo 2: Catálogo Global de Tokens Canónicos (
cat_addenda_tokens) - Módulo 3: Tokens Custom y Reglas de Cálculo (
cat_addenda_plantilla_custom_tokens) - Módulo 4: Reglas de Transformación Condicional (
cat_addenda_reglas_transformacion) - Módulo 5: Bitácora de Procesamiento y Telemetría (
addenda_bitacora) - Módulo 6: Estrategias de Motor y Enums de Servicio
- Módulo 7: Modificadores de Formato y Sintaxis en Plantilla
- Módulo 8: Catálogo Maestro de Tokens Canónicos Estándar
- Matriz Resumen de Valores por Defecto (Default Matrix)
- 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:
- 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. - 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 a0.00sin abortar el flujo del comprobante. - 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.
| Campo | Tipo | Valor por Defecto | Valores Permitidos | Significado Funcional |
|---|---|---|---|---|
estado | VARCHAR(20) | 'PUBLICADA' | BORRADORPUBLICADARETIRADAOBSOLETA | Controla el ciclo de vida de la plantilla y su disponibilidad para el motor de generación. |
tipo_comprobante | VARCHAR(5) | Obligatorio | IETPN | Tipo de comprobante fiscal SAT según el Anexo 20 para el cual aplica la estructura XML. |
dn_activo | BOOLEAN | TRUE | TRUEFALSE | Bandera de borrado lógico estándar del arquetipo Alpura (BaseDO). |
dn_usuario_creador | VARCHAR(255) | 'ADMIN' | Texto libre | Usuario o proceso de servicio que registró originalmente la plantilla. |
dn_usuario_modificador | VARCHAR(255) | 'ADMIN' | Texto libre | Usuario o proceso que realizó la última alteración de la configuración. |
dd_fecha_creacion | TIMESTAMP | CURRENT_TIMESTAMP | Fecha/Hora ISO | Marca de tiempo del alta en base de datos. |
dd_fecha_modificacion | TIMESTAMP | CURRENT_TIMESTAMP | Fecha/Hora ISO | Marca 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.
| Campo | Tipo | Valor por Defecto | Valores Permitidos | Significado Funcional |
|---|---|---|---|---|
tipo_origen | VARCHAR(40) | Obligatorio | FACTURACLIENTEPEDIDORUBROS_IMPUESTOSSISTEMA_CFDI | Clasificación del dominio de procedencia de los datos para ruteo del conector Spring. |
conector_asociado | VARCHAR(60) | Obligatorio | FacturaConnectorServiceClienteConnectorServicePedidoConnectorServiceRubrosConnectorServiceLegacyConnectorServiceImpl | Nombre del bean Spring encargado de extraer el DTO de datos. |
sistema_fuente | VARCHAR(50) | Obligatorio | DB BillingCat GeneralesOracle EBSAS400CFDI Core | Sistema legado o base de datos externa de donde se extrae la información. |
estrategia_extraccion | VARCHAR(40) | 'DIRECT_DTO_FIELD' | DIRECT_DTO_FIELDJSON_PATHSQL_COLUMNCOMPUTEDHEADER_PARAM | Mecanismo técnico empleado por el motor para leer el valor del contexto. |
alcance | VARCHAR(20) | 'ENCABEZADO' | ENCABEZADODETALLE | Nivel estructural del token: una sola vez por factura o una vez por cada partida de producto. |
tipo_dato | VARCHAR(20) | 'STRING' | STRINGNUMERICINTEGERDATEDATETIMEBOOLEAN | Tipo de dato que determina la coerción, redondeo y formateo del valor. |
formato_default | VARCHAR(50) | NULL | Máscaras estándar (ver detalle abajo) | Formato aplicado si el token no declara modificador explícito en la plantilla XML. |
es_obligatorio | BOOLEAN | FALSE | TRUEFALSE | Si es TRUE, el motor aborta la generación con error de validación si el valor resulta nulo o vacío. |
valor_default | VARCHAR(255) | '' (o '0.00') | Texto / Valor fallback | Valor 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 esquemabilling.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ónBigDecimal.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 comotrue/falseo1/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.
| Campo | Tipo | Valor por Defecto | Valores Permitidos | Significado Funcional |
|---|---|---|---|---|
alcance | VARCHAR(20) | 'ENCABEZADO' | ENCABEZADODETALLE | Determina si el token custom se calcula a nivel cabecera o de forma repetitiva por partida. |
tipo_valor | VARCHAR(20) | Obligatorio | FIJOCALCULADO | Naturaleza del token: constante inmutable o fórmula matemática resuelta en tiempo de ejecución. |
tipo_dato_resultado | VARCHAR(20) | 'STRING' | STRINGNUMERICINTEGERDATEBOOLEAN | Tipo de dato esperado para el valor final evaluado. |
escala_decimales | INTEGER | 2 | Entero $\ge 0$ (0, 1, 2, 3, 4, ...) | Número de dígitos fraccionarios aplicados en el redondeo BigDecimal.setScale(). |
tipo_redondeo | VARCHAR(20) | 'HALF_UP' | HALF_UPHALF_EVENCEILINGFLOORUPDOWN | Algoritmo de redondeo aritmético para resolver fracciones decimales. |
orden_evaluacion | INTEGER | 1 | Entero $\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
0o nulo, la expresión retorna automáticamente0.00sin 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.
| Campo | Tipo | Valor por Defecto | Valores Permitidos | Significado Funcional |
|---|---|---|---|---|
operacion | VARCHAR(10) | '=' (o NULL) | = (o NULL)<> o !==r<>r o !=rREGEX | Operador lógico que determina la condición de activación de la regla. |
token_origen | VARCHAR(100) | Obligatorio | Sintaxis $NombreToken$ | Token cuyo valor extraído se inspecciona en la condición. |
valor_actual | TEXT | Obligatorio | Literal o lista separada por comas | Valor(es) contra los que se compara el contenido de token_origen. |
nuevo_valor | TEXT | Obligatorio | Literal o sintaxis $Token$ | Valor resultante que se inyectará si la condición se cumple. |
token_destino | VARCHAR(100) | NULL | Sintaxis $TokenDestino$ | Token que recibirá el resultado (requerido solo para operaciones =r y <>r). |
orden_ejecucion | INTEGER | 1 | Entero $\ge 1$ (1, 2, 3, ...) | Secuencia de ejecución de las reglas antes del renderizado de la plantilla. |
6.1 Detalle de Operaciones (operacion)
=oNULL(Igualdad directa / Reemplazo in-situ): Si el valor detoken_origencoincide convalor_actual(o con cualquiera de los elementos en una lista separada por comas, ej.'PIEZA,PZA,PZ'), el contenido del mismotoken_origense reemplaza pornuevo_valor(ej.'PCE').<>o!=(Desigualdad in-situ): Si el valor detoken_origenes distinto devalor_actual, su contenido se reemplaza pornuevo_valor.=r(Igualdad con Redirección a Token Destino): Sitoken_origencoincide convalor_actual, elnuevo_valor(que puede ser otro token o un literal) se almacena en el campo especificado entoken_destino. El token origen original no se destruye.<>ro!=r(Desigualdad con Redirección a Token Destino): Sitoken_origenes distinto devalor_actual, se escribe elnuevo_valorentoken_destino.REGEX(Coincidencia por Expresión Regular): Evalúa el patrón de expresión regular definido envalor_actualy sustituye segúnnuevo_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.
| Campo | Tipo | Valor por Defecto | Valores Permitidos | Significado Funcional |
|---|---|---|---|---|
estado_proceso | VARCHAR(25) | 'EXITOSO' | EXITOSOERROR_VALIDACIONERROR_CALCULOERROR_TRANSFORMACIONERROR_TIMEOUT | Resultado global de la generación de la addenda. |
motor_usado | VARCHAR(30) | 'THYMELEAF_XML' | THYMELEAF_XMLLEGACY_REGEX | Motor tecnológico responsable de compilar el XML final. |
hash_addenda | VARCHAR(64) | NULL | Hexadecimal SHA-256 | Checksum criptográfico del nodo XML generado para detección de cambios. |
tiempo_procesamiento_ms | BIGINT | 0 | Entero $\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 Enum | Modo de Operación | Significado y Flujo Funcional |
|---|---|---|
ASSEMBLED | Motor Moderno (Default) | Orquestación mediante conectores de Spring, resolución relacional de cat_addenda_* y renderizado XML seguro con Thymeleaf 3.x. |
LEGACY | Motor Histórico | Consulta 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ódigo | Identificador | Significado Funcional | Acción de Recuperación |
|---|---|---|---|
0 | UNKNOWN_ERROR | Error no categorizado o excepción no controlada en el runtime. | Revisar logs del microservicio en OpenSearch. |
1 | REQUIRED_FIELD | Un campo obligatorio del comprobante o de la plantilla está vacío. | Verificar payload o marcar token con es_obligatorio = false. |
2 | EXCEEDS_MAX_LENGTH | Un valor supera la longitud de caracteres permitida por la base de datos o XSD. | Aplicar modificador de longitud {Size_N}. |
404 | NO_RESULTS | La consulta a un conector externo no devolvió registros. | Revisar folios en Oracle EBS / AS400. |
500 | ADDENDA_PROCESSING_ERROR | Fallo interno durante la generación del XML de addenda. | Validar trazabilidad en addenda_bitacora. |
1001 | ADDENDA_CADENA_REQUIRED | La petición no especificó la cadena comercial destino. | Enviar atributo cadena en la petición JSON. |
1002 | ADDENDA_REQUEST_EMPTY | El payload de la petición llegó completamente vacío. | Enviar cuerpo JSON válido. |
2001 | PLANTILLA_NOT_FOUND | No existe plantilla activa y vigente para la cadena y fecha de comprobante. | Dar de alta versión en cat_addenda_plantillas. |
2002 | PLANTILLA_DUPLICATE_VERSION | Intento 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. |
2003 | PLANTILLA_INVALID_XML | El XML configurado en la plantilla está mal formado o no cierra etiquetas. | Validar estructura XML con herramienta sintáctica. |
2004 | CUSTOM_TOKEN_NOT_FOUND | Una fórmula matemática hace referencia a un token que no existe en el catálogo. | Registrar el token dependiente en cat_addenda_tokens. |
2005 | PLANTILLA_REQUIRED_FIELD | Falta un atributo fundamental en el DTO de configuración de plantilla. | Revisar anotaciones @NotEmpty en PlantillaAddendaVO. |
3001 | CATALOG_SERVICE_ERROR | El 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}$.
| Modificador | Tipo Aplicable | Ejemplo de Uso | Comportamiento 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ónico | Conector Asignado | Tipo Dato | Formato Default | Valor Default | Obligatorio | Significado Funcional |
|---|---|---|---|---|---|---|
$EncabezadoserieComprobante$ | FacturaConnectorService | STRING | — | '' | Sí | Serie fiscal SAT asignada al comprobante. |
$EncabezadofolioComprobante$ | FacturaConnectorService | STRING | — | '' | Sí | Folio fiscal correlativo de facturación. |
$Encabezadosubtotal$ | FacturaConnectorService | NUMERIC | 0.00 | '0.00' | Sí | Importe subtotal antes de descuentos e impuestos. |
$Encabezadodescuentos$ | FacturaConnectorService | NUMERIC | 0.00 | '0.00' | No | Descuento total aplicado a nivel comprobante. |
$Encabezadototal$ | FacturaConnectorService | NUMERIC | 0.00 | '0.00' | Sí | Importe total final a pagar. |
$Encabezadomoneda$ | FacturaConnectorService | STRING | — | 'MXN' | Sí | Clave de moneda según catálogo SAT ISO 4217. |
$EncabezadotipoCambio$ | FacturaConnectorService | NUMERIC | 0.00 | '1.00' | No | Tipo de cambio fijado para la divisa (1.00 si MXN). |
$EncabezadoFechaComprobante$ | FacturaConnectorService | DATE | yyyy-MM-dd | '' | Sí | Fecha oficial de emisión del comprobante. |
$EncabezadonumProveedor$ | FacturaConnectorService | STRING | — | '' | No | Número de proveedor corporativo asignado por la cadena. |
$EncabezadodiasPago$ | FacturaConnectorService | INTEGER | — | '0' | No | Días de crédito pactados para liquidación de factura. |
10.2 Tokens de Cliente y Receptor (tipo_origen = 'CLIENTE')
| Token Canónico | Conector Asignado | Tipo Dato | Formato Default | Valor Default | Obligatorio | Significado Funcional |
|---|---|---|---|---|---|---|
$ClienteRFC$ | ClienteConnectorService | STRING | — | '' | Sí | RFC tributario oficial del cliente receptor. |
$EncabezadoreceptorNombreReceptor$ | ClienteConnectorService | STRING | — | '' | Sí | Denominación o razón social oficial del receptor. |
$EncabezadoreceptorNumeroCliente$ | ClienteConnectorService | STRING | — | '' | No | Código interno de cliente en el ERP de Alpura. |
$EncabezadoreceptorGlnReceptor$ | ClienteConnectorService | STRING | — | '' | No | Global Location Number (GLN) del corporativo comprador. |
$EncabezadoreceptorNumeroSucursal$ | ClienteConnectorService | STRING | — | '' | No | Número o identificador de la tienda o sucursal destino. |
$EncabezadoreceptorGlnSucursal$ | ClienteConnectorService | STRING | — | '' | No | GLN 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ónico | Conector Asignado | Tipo Dato | Formato Default | Valor Default | Obligatorio | Significado Funcional |
|---|---|---|---|---|---|---|
$EncabezadonumOrdenCompra$ | PedidoConnectorService | STRING | — | '' | No | Orden de Compra (OC / Purchase Order) emitida por el cliente. |
$EncabezadofolioRecepcion$ | PedidoConnectorService | STRING | — | '' | No | Folio de entrada al almacén / contra-recibo en tienda. |
$EncabezadoFechaEntrega$ | PedidoConnectorService | DATE | yyyy-MM-dd | '' | No | Fecha efectiva de recepción física de las mercancías. |
10.4 Tokens de Partidas de Detalle (tipo_origen = 'PEDIDO', alcance = 'DETALLE')
| Token Canónico | Conector Asignado | Tipo Dato | Formato Default | Valor Default | Obligatorio | Significado Funcional |
|---|---|---|---|---|---|---|
$DetalleNumLinea$ | PedidoConnectorService | INTEGER | — | '1' | Sí | Secuencia o número ordinal de la partida en el comprobante. |
$DetalleSKU$ | PedidoConnectorService | STRING | — | '' | Sí | Código de producto interno Alpura o código de barras EAN/GTIN. |
$Detalledescripcion$ | PedidoConnectorService | STRING | — | '' | Sí | Nombre comercial y descripción detallada del artículo. |
$Detallecantidad$ | PedidoConnectorService | NUMERIC | 0.00 | '0' | Sí | Unidades o piezas físicas facturadas en la partida. |
$DetalleunidadMedida$ | PedidoConnectorService | STRING | — | 'PZA' | Sí | Clave de unidad de medida original (ej. PZA, CJA, LT). |
$DetalleprecioUnitario$ | PedidoConnectorService | NUMERIC | 0.00 | '0.00' | Sí | Precio unitario pactado antes de impuestos. |
$Detalleimporte$ | PedidoConnectorService | NUMERIC | 0.00 | '0.00' | Sí | Importe total bruto de la línea (cantidad * precioUnitario). |
$DetalleDescuento$ | PedidoConnectorService | NUMERIC | 0.00 | '0.00' | No | Descuento específico concedido en la partida. |
10.5 Tokens de Impuestos (tipo_origen = 'RUBROS_IMPUESTOS')
| Token Canónico | Conector Asignado | Alcance | Tipo Dato | Formato Default | Valor Default | Significado Funcional |
|---|---|---|---|---|---|---|
$Encabezadoimpuestos$ | RubrosConnectorService | ENCABEZADO | NUMERIC | 0.00 | '0.00' | Total consolidado de impuestos trasladados del comprobante. |
$DetalleTasaIVA$ | RubrosConnectorService | DETALLE | NUMERIC | 0.00 | '16.00' | Tasa porcentual de IVA aplicada al producto (ej. 16.00 o 0.00). |
$DetallemontoIva$ | RubrosConnectorService | DETALLE | NUMERIC | 0.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 Dependencia | Columnas Involucradas | Consecuencia si No Está Poblada |
|---|---|---|---|---|
cat_addenda_plantillas | Ninguna (Tabla Maestra Raíz) | Independiente | id_plantilla (PK) | N/A. Puede insertarse en cualquier momento sin dependencias previas. |
cat_addenda_tokens | Ninguna (Catálogo Global) | Independiente | id_token (PK), clave_token (UK) | N/A. Puede insertarse en cualquier momento. |
cat_addenda_plantilla_custom_tokens | 1. cat_addenda_plantillas2. cat_addenda_tokens | Física (FK) Lógica (Fórmula) | id_plantilla $\rightarrow$ cat_addenda_plantillas.id_plantillatokens_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_transformacion | 1. cat_addenda_plantillas2. cat_addenda_tokens | Física (FK) Lógica (Regla) | id_plantilla $\rightarrow$ cat_addenda_plantillas.id_plantillatoken_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_tbl | Ninguna (Catálogo de Seguridad) | Independiente | user_id (PK), email (UK) | N/A. Debe poblarse para vincular usuarios de auditoría (dn_usuario_creador). |
addenda_bitacora | 1. cat_addenda_plantillas2. alp_facturacion_comprobante3. user_tbl | Lógica / Telemetría | id_plantilla, id_facturacion_comprobante, usuario_ejecutor | Los 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_emisor2. alp_facturacion_receptor3. alp_facturacion_impuestos | Física (FK) de db.sql | id_emisor $\rightarrow$ alp_facturacion_emisor.idid_receptor $\rightarrow$ alp_facturacion_receptor.idid_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_comprobante2. alp_facturacion_remision | Física (FK) de db.sql | id_comprobante $\rightarrow$ alp_facturacion_comprobante.idid_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:
-
fk_custom_tokens_plantilla:ALTER TABLE billing.cat_addenda_plantilla_custom_tokensADD CONSTRAINT fk_custom_tokens_plantillaFOREIGN 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_plantillano existe previamente encat_addenda_plantillas. Si se elimina la plantilla, se eliminan en cascada sus tokens custom asociados.
- Comportamiento: No es posible registrar un token custom (fijo o fórmula) si su
-
fk_reglas_transformacion_plantilla:ALTER TABLE billing.cat_addenda_reglas_transformacionADD CONSTRAINT fk_reglas_transformacion_plantillaFOREIGN 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.
-
Restricciones de Facturación Operativa (desde
docs/db.sql):alp_facturacion_comprobanteexige que existan previamente registros enalp_facturacion_emisor,alp_facturacion_receptoryalp_facturacion_impuestos.alp_facturacion_facturaexige la existencia simultánea dealp_facturacion_comprobanteyalp_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:
-
Tokens Canónicos vs Fórmulas Custom:
- Al registrar un token calculado en
cat_addenda_plantilla_custom_tokenscon una expresión aritmética (ej.$Encabezadodescuentos$ / $Encabezadototal$), ambos tokens deben existir previamente registrados encat_addenda_tokens. - Si la fórmula utiliza otro token custom (cálculo en cascada, como
$DetalleTotalLinea$ = $DetalleSubtotalNeto$ + $DetalleIvaCalculado$), los tokens previos deben tener unorden_evaluacionestrictamente menor (orden_evaluacion = 1y2resueltos antes de3).
- Al registrar un token calculado en
-
Reglas de Transformación Condicional:
- En
cat_addenda_reglas_transformacion,token_origendebe corresponder a un token extraído por los conectores (ej.$DetalleunidadMedida$). - Si la operación es
=ro<>r, el campotoken_destinodebe existir en el contexto de tokens para que el valor resultante pueda ser inyectado y leído posteriormente en la plantilla XML.
- En
-
Resolución de Plantilla por Comprobante:
- Para que el orquestador genere la addenda de un comprobante en runtime, en
cat_addenda_plantillasdebe existir un registro dondecadena_codigocoincida con el cliente/cadena,tipo_comprobantecoincida con el CFDI (IoE),estado = 'PUBLICADA', yfecha_inicio_vigencia <= fecha_emision_cfdi <= COALESCE(fecha_fin_vigencia, CURRENT_TIMESTAMP).
- Para que el orquestador genere la addenda de un comprobante en runtime, en
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):
- Paso 1: Insertar catálogo global de tokens en
cat_addenda_tokens. - Paso 2: Insertar plantillas maestras en
cat_addenda_plantillas(obteniendo susid_plantilla). - Paso 3: Insertar tokens custom fijos y calculados en
cat_addenda_plantilla_custom_tokens(asociados a susid_plantilla). - Paso 4: Insertar reglas de transformación en
cat_addenda_reglas_transformacion(asociadas a susid_plantilla). - Paso 5: Insertar usuarios base en
user_tbl. - Paso 6 (Opcional - Pruebas Operativas): Insertar en
alp_facturacion_emisor,alp_facturacion_receptor,alp_facturacion_impuestosyalp_facturacion_remision. - Paso 7 (Opcional - Pruebas Operativas): Insertar comprobantes en
alp_facturacion_comprobanteenlazando los IDs del Paso 6. - Paso 8 (Opcional - Pruebas Operativas): Insertar factura en
alp_facturacion_facturaenlazando comprobante y remisión. - 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.