Skip to main content

Manual de Integración y Consumo de Endpoints

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

Proyecto: Nueva Facturación Electrónica Alpura
Versión de la API: v1.0.0
Fecha: Noviembre 2026
Tecnología: Spring Boot 3.4.4 / Java 21 / PostgreSQL / OAuth2 Keycloak


1. Introducción y Arquitectura​

El microservicio msa-facturacion-generador-addendas es el componente de Alpura responsable de transformar dinámicamente los datos de facturación (encabezado y detalle) en el fragmento XML correspondiente al nodo <cfdi:Addenda>, cumpliendo con los estándares y particularidades exigidas por cada cadena comercial (Soriana, Tiendas 3B, OXXO, Chedraui, Comercial City Fresko, Walmart, etc.) para comprobantes de Ingreso (I) y Egreso (E).

1.1 Modos de Orquestación​

El servicio desacopla la fuente de datos mediante el patrón Strategy:

  1. Modo ASSEMBLED (Por defecto / Recomendado):
    Ejecuta un patrón Scatter-Gather concurrente con hilos virtuales/estructurados (Structured Concurrency) y política estricta Fail-Fast. Consulta en paralelo los conectores de facturación (FacturaConnectorService, ClienteConnectorService, PedidoConnectorService, RubrosConnectorService) contra la base de datos de facturación (billing.*).
  2. Modo LEGACY (Contingencia / Oracle):
    Se activa enviando "legacy": true en el payload JSON. Rutea la consulta hacia el servicio heredado de Oracle/OBI.

1.2 Ambientes y URLs Base​

AmbienteHost / Base URLPuertoContext Path
Localhttp://localhost:90909090/
Developmenthttps://apw-dev.alpura.com:8243/addendas8243/
UAT / Staginghttps://apw-uat.alpura.com:8243/addendas8243/
Producciónhttps://api.alpura.com/addendas443/

1.3 Documentación Interactiva y OpenAPI​

  • Swagger UI: http://localhost:9090/swagger-ui.html
  • OpenAPI v3 Spec: http://localhost:9090/v3/api-docs

2. Autenticación y Encabezados (Headers)​

El servicio está protegido mediante OAuth2 / OIDC a través de Keycloak de Alpura (realm: Alpura).

2.1 Encabezados HTTP Obligatorios​

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json
Accept: application/json

2.2 Roles de Seguridad​

Rol de KeycloakEndpoints PermitidosDescripción
ADDENDA_GENERARPOST /api/v1/addendas/generarPermite timbrar y generar el XML oficial de la addenda.
ADDENDA_ADMINPOST /api/v1/addendas/previsualizar
* /api/v1/configuraciones/plantillas/**
Gestión administrativa de plantillas, tokens custom y pruebas en borrador.

[!NOTE] En ambiente local con alpuraSecurity.disableSecurity: true o pruebas unitarias, la validación estricta de roles puede omitirse; en ambientes development, staging y production el token JWT es mandatorio.


3. Estructura Estándar de Respuesta y Errores​

Todos los endpoints del microservicio retornan una envoltura estándar de arquitectura Alpura (SingleResponseVO<T> o ResponseVO<List<T>>).

3.1 Respuesta Exitosa (SingleResponseVO<T>)​

{
"header": {
"code": 200,
"message": "Operación exitosa",
"detail": "OK"
},
"success": true,
"data": { ... },
"errors": [],
"newToken": null,
"hash": null
}

3.2 Respuesta Paginada (ResponseVO<List<T>>)​

{
"header": {
"code": 200,
"message": "Operación exitosa",
"detail": "OK"
},
"success": true,
"data": [ ... ],
"errors": [],
"totalRows": 25,
"page": 0,
"newToken": null,
"hash": null
}

3.3 Catálogo de Códigos de Error de Negocio​

Cuando ocurre un fallo, success es false y el arreglo errors contiene objetos con el código y detalle:

CódigoClave / ConstanteMensaje
404NO_RESULTSLa búsqueda de los recursos solicitados no arrojó ningún resultado.
500ADDENDA_PROCESSING_ERRORError en el procesamiento de generación de addenda.
1001ADDENDA_CADENA_REQUIREDEl campo 'cadena' es requerido para la generación de addenda.
1002ADDENDA_REQUEST_EMPTYLa petición de generación de addenda es requerida.
2001PLANTILLA_NOT_FOUNDLa plantilla solicitada no fue encontrada o se encuentra inactiva.
2002PLANTILLA_DUPLICATE_VERSIONYa existe una plantilla registrada con la misma versión para esta cadena y tipo.
2003PLANTILLA_INVALID_XMLEl contenido XML de la plantilla es inválido o malformado.
2004CUSTOM_TOKEN_NOT_FOUNDEl token custom solicitado no fue encontrado en la plantilla.
2005PLANTILLA_REQUIRED_FIELDLos campos obligatorios de la plantilla no fueron provistos.
3001CATALOG_SERVICE_ERRORError al consumir el servicio de catálogos maestros.

4. Módulo 1: Generación y Previsualización de Addendas​

Ruta base: /api/v1/addendas

4.1 Generar XML de Addenda Oficial​

Genera el XML de la addenda utilizando la plantilla vigente publicada (estado: PUBLICADA) correspondiente a la cadena, tipo de comprobante y fecha de emisión.

  • Método: POST
  • Path: /api/v1/addendas/generar
  • Rol requerido: ADDENDA_GENERAR
  • Consumes / Produces: application/json

Parámetros del Body (AddendaGenerationRequestVO)​

CampoTipoObligatorioDescripción
cadenaStringSíCódigo identificador de la cadena comercial (ej. TIENDAS_SORIANA, TIENDAS_TRES_B, COMERCIAL_CITY_FRESKO, OXXO).
tipoComprobanteStringNoTipo de CFDI: I (Ingreso) o E (Egreso). Por defecto I.
fechaEmisionStringNoFecha/hora ISO (yyyy-MM-dd'T'HH:mm:ss) para resolver la versión vigente.
invoiceIdStringNoID de transacción de facturación (ej. FA-987654) para que el flujo ASSEMBLED extraiga automáticamente los datos de la base de datos billing.*.
legacyBooleanNofalse (por defecto) para orquestación moderna Assembled; true para invocar Oracle/OBI heredado.
encabezadoObject (AddendaHeaderVO)NoDatos de cabecera suministrados directamente (opcional si se usa invoiceId).
detalleArray (List<AddendaItemVO>)NoPartidas o ítems de la factura (opcional si se usa invoiceId).

Ejemplo de Petición (Modo Assembled por invoiceId):​

curl -X POST http://localhost:9090/api/v1/addendas/generar \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"cadena": "TIENDAS_SORIANA",
"tipoComprobante": "I",
"invoiceId": "FA-987654",
"legacy": false
}'

Ejemplo de Petición con Payload Completo en Memoria:​

curl -X POST http://localhost:9090/api/v1/addendas/generar \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"cadena": "TIENDAS_SORIANA",
"tipoComprobante": "I",
"fechaEmision": "2026-11-06T08:00:00",
"legacy": false,
"encabezado": {
"serieComprobante": "FA",
"folioComprobante": "987654",
"numProveedor": "12345",
"numOrdenCompra": "4500098765",
"subtotal": "25000.00",
"total": "29000.00",
"moneda": "MXN",
"rfcEmisor": "GPL720519G60",
"nombreEmisor": "GANADEROS PRODUCTORES DE LECHE PURA SAPI DE CV"
},
"detalle": [
{
"numLinea": 1,
"sku": "7501020512345",
"descripcion": "LECHE ALPURA CLASICA 1L",
"cantidad": "100",
"unidadMedida": "LITRO",
"precioUnitario": "25.00",
"importe": "2500.00"
}
]
}'

Ejemplo de Respuesta Exitosa (200 OK):​

{
"header": {
"code": 200,
"message": "OK",
"detail": "Operación ejecutada exitosamente"
},
"success": true,
"errors": [],
"data": {
"xmlAddenda": "<cfdi:Addenda xmlns:cfdi=\"http://www.sat.gob.mx/cfd/4\">\n <alpura:AddendaComercial cadena=\"TIENDAS_SORIANA\" tipoComprobante=\"I\" invoiceId=\"FA-987654\" estrategia=\"ASSEMBLED\"/>\n</cfdi:Addenda>",
"cadena": "TIENDAS_SORIANA",
"tipoComprobante": "I",
"folio": "FA-987654",
"hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"duracionMs": 42,
"strategyUsed": "ASSEMBLED"
}
}

4.2 Previsualizar Addenda con Plantilla en Borrador​

Permite a los analistas y desarrolladores renderizar la addenda utilizando plantillas en estado BORRADOR antes de su publicación formal a producción.

  • Método: POST
  • Path: /api/v1/addendas/previsualizar
  • Rol requerido: ADDENDA_ADMIN
  • Consumes / Produces: application/json

Ejemplo cURL:​

curl -X POST http://localhost:9090/api/v1/addendas/previsualizar \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"cadena": "TIENDAS_SORIANA",
"tipoComprobante": "I",
"invoiceId": "FA-987654"
}'

4.3 Healthcheck del Módulo de Addendas​

Verifica la disponibilidad y el correcto enlace del controlador de generación de addendas.

  • Método: GET
  • Path: /api/v1/addendas/healthcheck
  • Rol requerido: Público / Ninguno

Ejemplo cURL:​

curl -X GET http://localhost:9090/api/v1/addendas/healthcheck

Respuesta: "OK" (Status 200).


5. Módulo 2: Configuración y Administración de Plantillas​

Ruta base: /api/v1/configuraciones/plantillas

Este módulo permite dar de alta, versionar, actualizar y publicar plantillas XML sin recompilar ni desplegar código.

5.1 Listar Plantillas (Paginado y Filtrado)​

  • Método: GET
  • Path: /api/v1/configuraciones/plantillas
  • Rol requerido: ADDENDA_ADMIN

Query Parameters​

ParámetroTipoDefaultDescripción
sizeInteger50Cantidad de elementos por página.
offsetInteger0Desplazamiento inicial (índice en filas).
cadenaString(Opcional)Filtrar por código de cadena (ej. TIENDAS_SORIANA).
tipoComprobanteString(Opcional)Filtrar por tipo: I o E.
estadoString(Opcional)Filtrar por estado: BORRADOR, PUBLICADA, RETIRADA.

Ejemplo cURL:​

curl -X GET "http://localhost:9090/api/v1/configuraciones/plantillas?cadena=TIENDAS_SORIANA&estado=PUBLICADA&size=10&offset=0" \
-H "Accept: application/json" \
-H "Authorization: Bearer <TOKEN>"

Ejemplo de Respuesta (200 OK):​

{
"header": { "code": 200, "message": "OK", "detail": "OK" },
"success": true,
"errors": [],
"data": [
{
"idPlantilla": 1,
"cadenaCodigo": "TIENDAS_SORIANA",
"numeroCliente": "100234,100235",
"rfcReceptor": "TSO991022PB6",
"glnReceptor": "7504000107903",
"tipoComprobante": "I",
"version": "2026-11-01",
"fechaInicioVigencia": "2026-01-01T00:00:00",
"fechaFinVigencia": null,
"estado": "PUBLICADA",
"xmlPlantillaEncabezado": "<cfdi:Addenda xmlns:cfdi=\"http://www.sat.gob.mx/cfd/4\"><DSCargaRemisionProv><Remision Id=\"Remision1\"><Proveedor>$EncabezadonumProveedor$</Proveedor><Total>$Encabezadototal$</Total></Remision><cfdi:DetalleAddenda/></DSCargaRemisionProv></cfdi:Addenda>",
"xmlPlantillaDetalle": "<Articulos Id=\"Articulos$DetalleNumLinea$\"><Codigo>$DetalleSKU$</Codigo><Cantidad>$Detallecantidad$</Cantidad></Articulos>",
"descripcion": "Plantilla oficial Soriana",
"customTokens": []
}
],
"totalRows": 1,
"page": 0
}

5.2 Obtener Detalle de Plantilla por ID​

  • Método: GET
  • Path: /api/v1/configuraciones/plantillas/{id}
  • Rol requerido: ADDENDA_ADMIN

Ejemplo cURL:​

curl -X GET http://localhost:9090/api/v1/configuraciones/plantillas/1 \
-H "Authorization: Bearer <TOKEN>"

5.3 Crear Nueva Plantilla de Addenda​

Da de alta una nueva versión de plantilla. El servicio valida automáticamente que la estructura XML de encabezado y detalle esté bien formada y que no exista una versión idéntica activa para la misma cadena y tipo de comprobante.

  • Método: POST
  • Path: /api/v1/configuraciones/plantillas
  • Rol requerido: ADDENDA_ADMIN
  • Consumes / Produces: application/json

Estructura del Body (PlantillaAddendaVO)​

CampoTipoRequeridoDescripción
cadenaCodigoStringSíIdentificador de cadena comercial (ej. CHEDRAUI).
tipoComprobanteStringSíI (Ingreso) o E (Egreso).
versionStringSíIdentificador de versión (ej. v1.0.0, 2026-12).
fechaInicioVigenciaString (ISO)SíFecha en que entra en vigor (2026-12-01T00:00:00).
fechaFinVigenciaString (ISO)NoFecha límite de vigencia. null para indefinida.
estadoStringNoBORRADOR (por defecto recomendado) o PUBLICADA.
xmlPlantillaEncabezadoStringSíXML del nodo encabezado. Debe contener el marcador <cfdi:DetalleAddenda/>.
xmlPlantillaDetalleStringSíXML de la partida que se repite por cada ítem.
numeroClienteStringNoNúmeros de cliente Alpura asociados separados por coma.
rfcReceptorStringNoRFC del receptor asociado.
glnReceptorStringNoCódigo GLN del cliente.
descripcionStringNoComentarios o descripción funcional.
customTokensArrayNoLista opcional de tokens custom iniciales.

Ejemplo cURL:​

curl -X POST http://localhost:9090/api/v1/configuraciones/plantillas \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"cadenaCodigo": "CHEDRAUI",
"tipoComprobante": "I",
"version": "2026-12-01",
"fechaInicioVigencia": "2026-12-01T00:00:00",
"estado": "BORRADOR",
"descripcion": "Plantilla Chedraui para pruebas de homologación",
"xmlPlantillaEncabezado": "<cfdi:Addenda xmlns:cfdi=\"http://www.sat.gob.mx/cfd/4\"><Chedraui><Encabezado Proveedor=\"$EncabezadonumProveedor$\" Total=\"$Encabezadototal$\"/><cfdi:DetalleAddenda/></Chedraui></cfdi:Addenda>",
"xmlPlantillaDetalle": "<Detalle Linea=\"$DetalleNumLinea$\" Codigo=\"$DetalleSKU$\" Cantidad=\"$Detallecantidad$\" Importe=\"$Detalleimporte$\"/>"
}'

5.4 Actualizar Plantilla Existente​

  • Método: PUT
  • Path: /api/v1/configuraciones/plantillas/{id}
  • Rol requerido: ADDENDA_ADMIN

Ejemplo cURL:​

curl -X PUT http://localhost:9090/api/v1/configuraciones/plantillas/1 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"descripcion": "Plantilla oficial Soriana actualizada con nuevos requerimientos",
"xmlPlantillaEncabezado": "<cfdi:Addenda xmlns:cfdi=\"http://www.sat.gob.mx/cfd/4\"><DSCargaRemisionProv><Remision Id=\"Remision1\"><Proveedor>$EncabezadonumProveedor$</Proveedor><Subtotal>$Encabezadosubtotal$</Subtotal><Total>$Encabezadototal$</Total></Remision><cfdi:DetalleAddenda/></DSCargaRemisionProv></cfdi:Addenda>"
}'

5.5 Eliminar / Desactivar Plantilla (Soft-Delete)​

Desactiva lógicamente (dn_activo = false) la plantilla y todos sus tokens personalizados asociados.

  • Método: DELETE
  • Path: /api/v1/configuraciones/plantillas/{id}
  • Rol requerido: ADDENDA_ADMIN

Ejemplo cURL:​

curl -X DELETE http://localhost:9090/api/v1/configuraciones/plantillas/1 \
-H "Authorization: Bearer <TOKEN>"

Respuesta:​

{
"header": { "code": 200, "message": "OK", "detail": "OK" },
"success": true,
"data": true
}

5.6 Publicar Versión de Plantilla​

Cambia formalmente el estado de una plantilla de BORRADOR a PUBLICADA. A partir de este momento, el endpoint /generar empezará a utilizar esta versión para los comprobantes que correspondan a su vigencia.

  • Método: POST
  • Path: /api/v1/configuraciones/plantillas/{id}/publicar
  • Rol requerido: ADDENDA_ADMIN

Ejemplo cURL:​

curl -X POST http://localhost:9090/api/v1/configuraciones/plantillas/1/publicar \
-H "Authorization: Bearer <TOKEN>"

6. Módulo 3: Tokens Custom por Plantilla​

Ruta base: /api/v1/configuraciones/plantillas/{id}/custom-tokens

Permite inyectar tokens específicos de una plantilla, ya sean:

  • FIJO: Un literal estático que exige la cadena comercial (ej. un número de acreedor fijo).
  • CALCULADO: Una fórmula aritmética evaluada dinámicamente entre tokens del catálogo canónico (ej. $Encabezadodescuentos$ / $Encabezadototal$).

6.1 Listar Tokens Custom de una Plantilla​

  • Método: GET
  • Path: /api/v1/configuraciones/plantillas/{id}/custom-tokens
  • Rol requerido: ADDENDA_ADMIN

Ejemplo cURL:​

curl -X GET http://localhost:9090/api/v1/configuraciones/plantillas/1/custom-tokens \
-H "Authorization: Bearer <TOKEN>"

6.2 Registrar Token Custom en una Plantilla​

  • Método: POST
  • Path: /api/v1/configuraciones/plantillas/{id}/custom-tokens
  • Rol requerido: ADDENDA_ADMIN
  • Consumes / Produces: application/json

Parámetros del Body (PlantillaCustomTokenVO)​

CampoTipoObligatorioDescripción
claveTokenCustomStringSíSintaxis del token entre signos de peso (ej. $CustomTipoBulto$, $ResultadosDescuentos$).
alcanceStringNoNivel de aplicación: ENCABEZADO o DETALLE. Default: ENCABEZADO.
tipoValorStringSíFIJO o CALCULADO.
valorFijoStringCondicionalValor estático (requerido si tipoValor es FIJO).
expresionCalculoStringCondicionalFórmula aritmética matemática (requerida si tipoValor es CALCULADO).
tokensDependientesString (JSON)NoArreglo JSON de tokens que intervienen (ej. '["$Encabezadodescuentos$", "$Encabezadototal$"]').
tipoDatoResultadoStringNoSTRING, NUMERIC, INTEGER. Default: STRING.
escalaDecimalesIntegerNoNúmero de decimales para redondeo. Default: 2.
tipoRedondeoStringNoAlgoritmo de redondeo: HALF_UP, ROUND_UP, ROUND_DOWN. Default: HALF_UP.
ordenEvaluacionIntegerNoOrden de cálculo cuando un token depende del resultado de otro. Default: 1.
descripcionStringNoComentario funcional.

Ejemplo A: Token Custom Fijo​

curl -X POST http://localhost:9090/api/v1/configuraciones/plantillas/1/custom-tokens \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"claveTokenCustom": "$CustomAcreedor$",
"alcance": "ENCABEZADO",
"tipoValor": "FIJO",
"valorFijo": "983527",
"tipoDatoResultado": "STRING",
"descripcion": "Número fijo de acreedor para tiendas Soriana"
}'

Ejemplo B: Token Custom Calculado (Fórmula Matemática)​

curl -X POST http://localhost:9090/api/v1/configuraciones/plantillas/2/custom-tokens \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
"claveTokenCustom": "$ResultadosDescuentos$",
"alcance": "ENCABEZADO",
"tipoValor": "CALCULADO",
"expresionCalculo": "$Encabezadodescuentos$ / $Encabezadototal$",
"tokensDependientes": "[\"$Encabezadodescuentos$\", \"$Encabezadototal$\"]",
"tipoDatoResultado": "NUMERIC",
"escalaDecimales": 4,
"tipoRedondeo": "HALF_UP",
"ordenEvaluacion": 1,
"descripcion": "Factor de descuento porcentual para Tiendas 3B"
}'

6.3 Eliminar Token Custom de una Plantilla​

  • Método: DELETE
  • Path: /api/v1/configuraciones/plantillas/{id}/custom-tokens/{tokenId}
  • Rol requerido: ADDENDA_ADMIN

Ejemplo cURL:​

curl -X DELETE http://localhost:9090/api/v1/configuraciones/plantillas/1/custom-tokens/10 \
-H "Authorization: Bearer <TOKEN>"

6.4 Referencia Técnica del Motor de Reglas de Addendas​

Para un diseño exhaustivo de reglas de negocio, fórmulas aritméticas y transformaciones, consulte la Sección 5.7 del Documento de Diseño de Alto Nivel (HLD) y el diagrama de flujo oficial en diagrama_motor_reglas.mmd.

Resumen de Capacidades del Motor de Reglas:​

  1. Reglas de Cálculo Aritmético (tipoValor: "CALCULADO"):
    • Sintaxis con delimitadores $Token$: $SubtotalNeto$ = ($Detalleimporte$ - $DetalleDescuento$) / $Detallecantidad$.
    • Operaciones: +, -, *, /, %, ( ), funciones (abs, round, ceil, floor, min, max).
    • Precisión BigDecimal con escala decimal configurable (nu_escala_decimales: 2 a 6) y modos de redondeo (HALF_UP, HALF_EVEN).
    • Secuenciación determinista (nu_orden_evaluacion: $1, 2, 3 \dots$) para resolver cálculos en cascada y dependencias topológicas.
    • Tolerancia a fallos: protección automática contra división entre cero (retorno de fallback 0.00) y coerción de nulos.
  2. Reglas de Transformación Condicional (Reglas de Valor):
    • Operador = (igualdad literal o pertenencia a listas separadas por coma IN ("58743,58750...")).
    • Operador <> o != (desigualdad o exclusión).
    • Operador =r (igualdad con asignación dinámica del valor de otro token destino: tokenDestino).
    • Operador <>r (desigualdad con redirección alterna hacia otro token).
    • Mapeo de clase fiscal SAT (claseDoc: I $\rightarrow$ 1, E $\rightarrow$ 3).
  3. Modificadores de Formato y Longitud Fija:
    • $DetalleSKU{Size_14_0}$: Relleno con ceros a la izquierda a 14 posiciones.
    • $EncabezadoSerie{Size_10_S}$: Relleno con espacios a la derecha a 10 posiciones.
    • $FechaEmision{yyMMdd}$: Formateo de fecha compacta.

7. Módulo 4: Monitoreo, Actuator y Healthchecks​

El servicio cuenta con endpoints de observabilidad para balanceadores de carga, Kubernetes (Liveness/Readiness probes) y Prometheus:

MétodoEndpointDescripción
GET/api/v1/healthcheckHealthcheck global del arquetipo base ("OK").
GET/api/v1/addendas/healthcheckHealthcheck del controlador de addendas.
GET/api/v1/configuraciones/plantillas/healthcheckHealthcheck del controlador de plantillas.
GET/actuator/healthEstado de salud integral de Spring Boot (DB H2/PostgreSQL, disco, etc.).
GET/actuator/infoMetadatos de la aplicación.
GET/actuator/prometheusMétricas en formato OpenMetrics para monitoreo con Prometheus y Grafana.

Ejemplo de Consulta de Salud:​

curl -X GET http://localhost:9090/actuator/health
{
"status": "UP"
}

8. Flujos de Trabajo Recomendados (Integration Workflows)​

Flujo 1: Ciclo de Vida de una Nueva Addenda​

Flujo 2: Generación en Línea durante el Timbrado CFDI​

El sistema de facturación o timbrado únicamente debe invocar:

POST /api/v1/addendas/generar

Enviando el identificador del comprobante recién generado:

{
"cadena": "TIENDAS_SORIANA",
"tipoComprobante": "I",
"invoiceId": "FA-987654",
"legacy": false
}

El orquestador ejecutará el patrón Scatter-Gather contra las tablas de facturación (billing.*) en menos de 50 ms y retornará el bloque XML listo para incrustarse en el CFDI timbrado.


9. Catálogo de Tokens Canónicos Principales​

Tokens estándar reconocidos por el motor extraídos de la fuente de datos empresarial:

Token CanónicoOrigen (tipo_origen)Descripción
$EncabezadoserieComprobante$FACTURASerie de la factura (ej. FA).
$EncabezadofolioComprobante$FACTURAFolio de la factura (ej. 987654).
$Encabezadosubtotal$FACTURASubtotal del comprobante con 2 decimales.
$Encabezadodescuentos$FACTURADescuento total aplicado.
$Encabezadototal$FACTURATotal general de la factura.
$Encabezadomoneda$FACTURAClave SAT de moneda (ej. MXN).
$EncabezadonumProveedor$FACTURANúmero de proveedor asignado por la cadena.
$EncabezadonumOrdenCompra$PEDIDOOrden de compra emitida por el cliente.
$EncabezadofolioRecepcion$PEDIDOFolio de nota de entrada o recibo de mercancía.
$Encabezadoimpuestos$RUBROS_IMPUESTOSTotal de impuestos trasladados (IVA).
$EncabezadoreceptorNombreReceptor$CLIENTERazón social del receptor de la factura.
$EncabezadoreceptorRfcReceptor$CLIENTERFC del receptor (ej. TSO991022PB6).
$EncabezadoreceptorNumeroSucursal$CLIENTENúmero de tienda o sucursal de entrega.
$DetalleNumLinea$FACTURANúmero de partida o renglón (1, 2, 3...).
$DetalleSKU$FACTURACódigo de barras o GTIN del producto.
$Detalledescripcion$FACTURADescripción comercial del artículo.
$Detallecantidad$FACTURACantidad facturada.
$DetalleprecioUnitario$FACTURAPrecio unitario antes de impuestos.
$Detalleimporte$FACTURAImporte total de la partida (cantidad * precioUnitario).

10. Catálogo y Tratamiento Canónico de Excepciones​

El servicio responde con la estructura estándar corporativa Alpura ante cualquier error o excepción de negocio:

10.1 Estructura Estándar de Respuesta de Error (JSON)​

{
"header": {
"code": 404,
"message": "La plantilla solicitada no fue encontrada o se encuentra inactiva",
"detail": "Error de negocio al resolver recurso"
},
"success": false,
"data": null,
"errors": [
{
"code": 2001,
"message": "La plantilla solicitada no fue encontrada o se encuentra inactiva",
"field": "idPlantilla"
}
],
"newToken": null,
"hash": null
}

10.2 Matriz Canónica de Códigos de Error​

CódigoConstante EnumHTTP StatusOrigen / CausaAcción Correctiva
0UNKNOWN_ERROR500Error no controlado o fallo de infraestructura.Consultar telemetría con correlationId.
1REQUIRED_FIELD400Campo mandatorio ausente (@NotNull, @NotBlank).Enviar todos los campos requeridos en el JSON.
2EXCEEDS_MAX_LENGTH400Texto excede la longitud máxima configurada.Truncar o reducir longitud del campo.
404NO_RESULTS404Consulta sin registros coincidentes.Verificar criterios o IDs suministrados.
500ADDENDA_PROCESSING_ERROR500Error interno en compilación de plantilla o SpEL.Verificar sintaxis de la plantilla y variables.
1001ADDENDA_CADENA_REQUIRED400Falta parámetro cadena en la petición.Indicar código de cadena (ej. "TIENDAS_SORIANA").
1002ADDENDA_REQUEST_EMPTY400Payload JSON vacío o sin parámetros.Enviar un payload JSON válido.
2001PLANTILLA_NOT_FOUND404 / 422Plantilla no encontrada por ID o sin versión activa.Registrar y publicar plantilla para la fecha/cadena.
2002PLANTILLA_DUPLICATE_VERSION409Ya existe una versión activa para la cadena y tipo.Incrementar la versión (v1.0.1, etc.).
2003PLANTILLA_INVALID_XML422XML de encabezado o detalle mal formado.Corregir sintaxis y balanceo de etiquetas XML.
2004CUSTOM_TOKEN_NOT_FOUND404Token custom inexistente en la plantilla.Verificar el identificador del token custom.
2005PLANTILLA_REQUIRED_FIELD400Parámetro obligatorio nulo en configuración.Completar todos los atributos mandatorios del DTO.
3001CATALOG_SERVICE_ERROR502 / 503Falla o timeout en comunicación con catálogos.Reintentar la operación o validar sistema fuente.
504ADDENDA_TIMEOUT_FAIL_FAST504Timeout en orquestación concurrente (> 1500 ms).Optimizar respuesta de BD o fuentes externas.

Para el mapeo detallado por cada flujo y endpoint REST, consultar HLD.md - Sección 7.3.