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:
- 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.*). - Modo
LEGACY(Contingencia / Oracle):
Se activa enviando"legacy": trueen el payload JSON. Rutea la consulta hacia el servicio heredado de Oracle/OBI.
1.2 Ambientes y URLs Base
| Ambiente | Host / Base URL | Puerto | Context Path |
|---|---|---|---|
| Local | http://localhost:9090 | 9090 | / |
| Development | https://apw-dev.alpura.com:8243/addendas | 8243 | / |
| UAT / Staging | https://apw-uat.alpura.com:8243/addendas | 8243 | / |
| Producción | https://api.alpura.com/addendas | 443 | / |
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 Keycloak | Endpoints Permitidos | Descripción |
|---|---|---|
ADDENDA_GENERAR | POST /api/v1/addendas/generar | Permite timbrar y generar el XML oficial de la addenda. |
ADDENDA_ADMIN | POST /api/v1/addendas/previsualizar* /api/v1/configuraciones/plantillas/** | Gestión administrativa de plantillas, tokens custom y pruebas en borrador. |
[!NOTE] En ambiente
localconalpuraSecurity.disableSecurity: trueo pruebas unitarias, la validación estricta de roles puede omitirse; en ambientesdevelopment,stagingyproductionel 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ódigo | Clave / Constante | Mensaje |
|---|---|---|
404 | NO_RESULTS | La búsqueda de los recursos solicitados no arrojó ningún resultado. |
500 | ADDENDA_PROCESSING_ERROR | Error en el procesamiento de generación de addenda. |
1001 | ADDENDA_CADENA_REQUIRED | El campo 'cadena' es requerido para la generación de addenda. |
1002 | ADDENDA_REQUEST_EMPTY | La petición de generación de addenda es requerida. |
2001 | PLANTILLA_NOT_FOUND | La plantilla solicitada no fue encontrada o se encuentra inactiva. |
2002 | PLANTILLA_DUPLICATE_VERSION | Ya existe una plantilla registrada con la misma versión para esta cadena y tipo. |
2003 | PLANTILLA_INVALID_XML | El contenido XML de la plantilla es inválido o malformado. |
2004 | CUSTOM_TOKEN_NOT_FOUND | El token custom solicitado no fue encontrado en la plantilla. |
2005 | PLANTILLA_REQUIRED_FIELD | Los campos obligatorios de la plantilla no fueron provistos. |
3001 | CATALOG_SERVICE_ERROR | Error 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)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
cadena | String | Sí | Código identificador de la cadena comercial (ej. TIENDAS_SORIANA, TIENDAS_TRES_B, COMERCIAL_CITY_FRESKO, OXXO). |
tipoComprobante | String | No | Tipo de CFDI: I (Ingreso) o E (Egreso). Por defecto I. |
fechaEmision | String | No | Fecha/hora ISO (yyyy-MM-dd'T'HH:mm:ss) para resolver la versión vigente. |
invoiceId | String | No | ID 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.*. |
legacy | Boolean | No | false (por defecto) para orquestación moderna Assembled; true para invocar Oracle/OBI heredado. |
encabezado | Object (AddendaHeaderVO) | No | Datos de cabecera suministrados directamente (opcional si se usa invoiceId). |
detalle | Array (List<AddendaItemVO>) | No | Partidas 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ámetro | Tipo | Default | Descripción |
|---|---|---|---|
size | Integer | 50 | Cantidad de elementos por página. |
offset | Integer | 0 | Desplazamiento inicial (índice en filas). |
cadena | String | (Opcional) | Filtrar por código de cadena (ej. TIENDAS_SORIANA). |
tipoComprobante | String | (Opcional) | Filtrar por tipo: I o E. |
estado | String | (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)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
cadenaCodigo | String | Sí | Identificador de cadena comercial (ej. CHEDRAUI). |
tipoComprobante | String | Sí | I (Ingreso) o E (Egreso). |
version | String | Sí | Identificador de versión (ej. v1.0.0, 2026-12). |
fechaInicioVigencia | String (ISO) | Sí | Fecha en que entra en vigor (2026-12-01T00:00:00). |
fechaFinVigencia | String (ISO) | No | Fecha límite de vigencia. null para indefinida. |
estado | String | No | BORRADOR (por defecto recomendado) o PUBLICADA. |
xmlPlantillaEncabezado | String | Sí | XML del nodo encabezado. Debe contener el marcador <cfdi:DetalleAddenda/>. |
xmlPlantillaDetalle | String | Sí | XML de la partida que se repite por cada ítem. |
numeroCliente | String | No | Números de cliente Alpura asociados separados por coma. |
rfcReceptor | String | No | RFC del receptor asociado. |
glnReceptor | String | No | Código GLN del cliente. |
descripcion | String | No | Comentarios o descripción funcional. |
customTokens | Array | No | Lista 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)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
claveTokenCustom | String | Sí | Sintaxis del token entre signos de peso (ej. $CustomTipoBulto$, $ResultadosDescuentos$). |
alcance | String | No | Nivel de aplicación: ENCABEZADO o DETALLE. Default: ENCABEZADO. |
tipoValor | String | Sí | FIJO o CALCULADO. |
valorFijo | String | Condicional | Valor estático (requerido si tipoValor es FIJO). |
expresionCalculo | String | Condicional | Fórmula aritmética matemática (requerida si tipoValor es CALCULADO). |
tokensDependientes | String (JSON) | No | Arreglo JSON de tokens que intervienen (ej. '["$Encabezadodescuentos$", "$Encabezadototal$"]'). |
tipoDatoResultado | String | No | STRING, NUMERIC, INTEGER. Default: STRING. |
escalaDecimales | Integer | No | Número de decimales para redondeo. Default: 2. |
tipoRedondeo | String | No | Algoritmo de redondeo: HALF_UP, ROUND_UP, ROUND_DOWN. Default: HALF_UP. |
ordenEvaluacion | Integer | No | Orden de cálculo cuando un token depende del resultado de otro. Default: 1. |
descripcion | String | No | Comentario 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:
- 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
BigDecimalcon escala decimal configurable (nu_escala_decimales:2a6) 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.
- Sintaxis con delimitadores
- Reglas de Transformación Condicional (Reglas de Valor):
- Operador
=(igualdad literal o pertenencia a listas separadas por comaIN ("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).
- Operador
- 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étodo | Endpoint | Descripción |
|---|---|---|
GET | /api/v1/healthcheck | Healthcheck global del arquetipo base ("OK"). |
GET | /api/v1/addendas/healthcheck | Healthcheck del controlador de addendas. |
GET | /api/v1/configuraciones/plantillas/healthcheck | Healthcheck del controlador de plantillas. |
GET | /actuator/health | Estado de salud integral de Spring Boot (DB H2/PostgreSQL, disco, etc.). |
GET | /actuator/info | Metadatos de la aplicación. |
GET | /actuator/prometheus | Mé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ónico | Origen (tipo_origen) | Descripción |
|---|---|---|
$EncabezadoserieComprobante$ | FACTURA | Serie de la factura (ej. FA). |
$EncabezadofolioComprobante$ | FACTURA | Folio de la factura (ej. 987654). |
$Encabezadosubtotal$ | FACTURA | Subtotal del comprobante con 2 decimales. |
$Encabezadodescuentos$ | FACTURA | Descuento total aplicado. |
$Encabezadototal$ | FACTURA | Total general de la factura. |
$Encabezadomoneda$ | FACTURA | Clave SAT de moneda (ej. MXN). |
$EncabezadonumProveedor$ | FACTURA | Número de proveedor asignado por la cadena. |
$EncabezadonumOrdenCompra$ | PEDIDO | Orden de compra emitida por el cliente. |
$EncabezadofolioRecepcion$ | PEDIDO | Folio de nota de entrada o recibo de mercancía. |
$Encabezadoimpuestos$ | RUBROS_IMPUESTOS | Total de impuestos trasladados (IVA). |
$EncabezadoreceptorNombreReceptor$ | CLIENTE | Razón social del receptor de la factura. |
$EncabezadoreceptorRfcReceptor$ | CLIENTE | RFC del receptor (ej. TSO991022PB6). |
$EncabezadoreceptorNumeroSucursal$ | CLIENTE | Número de tienda o sucursal de entrega. |
$DetalleNumLinea$ | FACTURA | Número de partida o renglón (1, 2, 3...). |
$DetalleSKU$ | FACTURA | Código de barras o GTIN del producto. |
$Detalledescripcion$ | FACTURA | Descripción comercial del artículo. |
$Detallecantidad$ | FACTURA | Cantidad facturada. |
$DetalleprecioUnitario$ | FACTURA | Precio unitario antes de impuestos. |
$Detalleimporte$ | FACTURA | Importe 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ódigo | Constante Enum | HTTP Status | Origen / Causa | Acción Correctiva |
|---|---|---|---|---|
0 | UNKNOWN_ERROR | 500 | Error no controlado o fallo de infraestructura. | Consultar telemetría con correlationId. |
1 | REQUIRED_FIELD | 400 | Campo mandatorio ausente (@NotNull, @NotBlank). | Enviar todos los campos requeridos en el JSON. |
2 | EXCEEDS_MAX_LENGTH | 400 | Texto excede la longitud máxima configurada. | Truncar o reducir longitud del campo. |
404 | NO_RESULTS | 404 | Consulta sin registros coincidentes. | Verificar criterios o IDs suministrados. |
500 | ADDENDA_PROCESSING_ERROR | 500 | Error interno en compilación de plantilla o SpEL. | Verificar sintaxis de la plantilla y variables. |
1001 | ADDENDA_CADENA_REQUIRED | 400 | Falta parámetro cadena en la petición. | Indicar código de cadena (ej. "TIENDAS_SORIANA"). |
1002 | ADDENDA_REQUEST_EMPTY | 400 | Payload JSON vacío o sin parámetros. | Enviar un payload JSON válido. |
2001 | PLANTILLA_NOT_FOUND | 404 / 422 | Plantilla no encontrada por ID o sin versión activa. | Registrar y publicar plantilla para la fecha/cadena. |
2002 | PLANTILLA_DUPLICATE_VERSION | 409 | Ya existe una versión activa para la cadena y tipo. | Incrementar la versión (v1.0.1, etc.). |
2003 | PLANTILLA_INVALID_XML | 422 | XML de encabezado o detalle mal formado. | Corregir sintaxis y balanceo de etiquetas XML. |
2004 | CUSTOM_TOKEN_NOT_FOUND | 404 | Token custom inexistente en la plantilla. | Verificar el identificador del token custom. |
2005 | PLANTILLA_REQUIRED_FIELD | 400 | Parámetro obligatorio nulo en configuración. | Completar todos los atributos mandatorios del DTO. |
3001 | CATALOG_SERVICE_ERROR | 502 / 503 | Falla o timeout en comunicación con catálogos. | Reintentar la operación o validar sistema fuente. |
504 | ADDENDA_TIMEOUT_FAIL_FAST | 504 | Timeout 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.