FTL Trace TX

Especificación técnica · Datos requeridos desde QLever · Mayo 2026 · v1.0

Propósito: Documento técnico para el equipo de QLever / Trento que especifica exactamente qué campos y reportes consume el sistema FTL Trace TX, y para qué los usa.
Alcance: 4 reportes del sistema QLever (ERP de Trento). Datos del piloto: OPs 6223–6230, proveedor Textil San Ramón S.A.
Clave de join: El campo op_codigo (OP-XXXX) es el identificador que vincula todos los reportes entre sí y con los checkpoints de FTL Trace.

1. Contexto

QLever es el sistema ERP de Confecciones Trento para gestión de almacenes, compras y movimientos de materiales. FTL Trace TX requiere datos de QLever para completar la trazabilidad en los checkpoints CP1 a CP8.

Se identificaron cuatro fuentes de datos en QLever:

Órdenes de Compra de Telas (PDF) — trazabilidad de compra, precio y proveedor de tela → CP1
Reporte de Recepción de Tela (Excel) — recepción física de partidas de tela y cantidades → CP1
Reporte de Compra de Avíos (Excel) — compra de materiales de empaque y avíos → CP5, CP8
Reporte de Transferencias de Materiales (Excel) — movimientos entre almacenes por OP → CP2, CP4, CP6

📄 Formato: PDF ⚠ Estado: No implementado ✓ Checkpoint: CP1

Las OC de telas son documentos generados por Trento en QLever al comprar tela al proveedor Textil San Ramón S.A. (RUC 20102261551). Se exportan en formato PDF. El piloto comprende 5 OC: 3-2025-119 al 3-2025-123, todas con fecha 18-09-2025, en dólares americanos, con condición LETRA 90 DÍAS.

Acción requerida: Parsear los PDFs con pdfplumber o cargar manualmente los campos clave por backoffice. El campo de join principal es numero_oc → Partida.orden_compra.

Campos disponibles en cada OC PDF

Campo en PDF	Campo FTL Trace	Usa	Descripción
Número de OC	`numero_oc`	✓	Formato '3-2025-119' → Partida.orden_compra
Tipo	—	—	Siempre TELA DE PRODUCCION
Fecha	`fecha_oc`	✓	Fecha de emisión
Proveedor	`proveedor_nombre`	✓	Nombre del proveedor
RUC Proveedor	`proveedor_ruc`	✓	RUC → Proveedor.ruc
País	`pais_origen`	✓	País de origen
Condición Pago	—	—	Referencia comercial
Glosa	`op_codes`	✓	OPs destino de esta tela
Moneda	`moneda`	✓	DOLARES AMERICANOS
Artículo (línea)	`codigo_tela`	✓	Código interno Trento
Producto (línea)	`descripcion_tela`	✓	Descripción completa
UM (línea)	`unidad_medida`	✓	KG
Cantidad (línea)	`cantidad_kg`	✓	Kilos pedidos
P. Unit (línea)	`precio_unit_usd`	✓	Precio USD por kg
Parcial (línea)	`subtotal_usd`	✓	Subtotal línea
Total	`total_usd`	✓	Total OC incluyendo IGV

✓ Estado: IMPLEMENTADO ✓ Endpoint: POST /api/v1/recepcion-tela/upload ✓ Checkpoint: CP1

Archivo: 5. DPP - RECEPCIÓN TELA - QLEVER.xlsx. Registra los ingresos físicos de tela al almacén. Cada fila es una partida de tela recibida. El parser recepcion_tela.py lee exactamente las 26 columnas de este archivo. El campo clave de join con la OC de telas es Glosa (col 10) = orden_compra_tela.

La columna 19 (Nro. de Lote) contiene la partida del proveedor, que vincula este registro con Partida.lote_proveedor en CP1.

Mapeo de columnas

Col #	Nombre en QLever	Campo FTL Trace	Usa	Descripción
0	Número	`numero_ingreso`	✓ usado	Número de ingreso al almacén
1	Tipo	—	—	I = Ingreso
2	Motivo	—	—	Código de motivo
3	Desc. Motivo	—	—	Descripción del motivo
4	Almacen	—	—	Código de almacén
5	Desc. Almacen	—	—	Nombre del almacén
6	Fecha	`fecha_ingreso`	✓ usado	Fecha de recepción de la partida de tela
7	Estado	`estado`	✓ usado	ATENDIDO / PENDIENTE
8	RUC	`proveedor_ruc`	✓ usado	RUC del proveedor de tela
9	Razon Social	`proveedor_razon_social`	✓ usado	Nombre del proveedor
10	Glosa	`orden_compra_tela`	✓ usado	N° de OC tela (ej. '3-2025-119')
11	Secuencia	`secuencia`	✓ usado	Secuencia del ítem
12	Item	`item_codigo`	✓ usado	Código interno del producto tela
13	Nombre Item	`nombre_item`	✓ usado	Descripción: tipo, composición, color, estilo
14	Cantidad	`cantidad_kg`	✓ usado	Kilos recibidos
15	Costo Unitario S/.	`costo_unitario_pen`	✓ usado	Precio unitario en soles
16	Costo Total S/.	`costo_total_pen`	✓ usado	Total en soles
17	Costo Unitario USD	`costo_unitario_usd`	✓ usado	Precio unitario en dólares
18	Costo Total USD	`costo_total_usd`	✓ usado	Total en dólares
19	Nro. de Lote	`partida`	✓ usado	Partida → Partida.lote_proveedor
20	Fecha Vencim.	`fecha_vencimiento`	✓ usado	Fecha de vencimiento del lote
21-23	(vacías)	—	—	Sin datos
24	Marca	—	—	Tipo de producto
25	Centro de gestión	`op_codigo`	✓ usado	Código de OP (ej. OP-6224)

Fila celeste = campo activamente usado por FTL Trace

⚠ Estado: No implementado ⚠ Checkpoints: CP5 (costura) / CP8 (acabados)

Archivo: 4. DPP - COMPRA DE AVÍOS - QLEVER.xlsx. Contiene las OC de avíos (hilo, botones, etiquetas, cajas, RFID, bolsas, cintas, etc.) por línea de ítem. El piloto tiene 166 filas, 14 OC únicas (oct–dic 2025). Proveedores mixtos: locales (RUC 11 dígitos) e importados (código PE000000007). Moneda mixta: SOLES y DOLARES.

La columna 24 (Centro Gestión) contiene la OP de referencia —clave de join con la producción. La columna 36 (CG Actual) puede tener múltiples OPs separadas por |.

Acción requerida: Crear entidad MaestroAvios y endpoint POST /api/v1/compra-avios/upload similar al de recepción de tela.

Mapeo de columnas

Col #	Nombre en QLever	Campo FTL Trace	Usa	Descripción
1	Fecha	`fecha_oc`	✓ usado	Fecha de la OC
2	Tipo O/C	—	—	N = normal
3	B/S	—	—	B = Buy
4	Número	`numero_oc`	✓ usado	N° de OC de avíos
5	Tipo Orden	—	—	5 = AVIOS
6	Desc. Tip. Orden	`tipo_orden`	✓ usado	AVIOS / IMPORTACIONES
7	Número Ord.	—	—	N° de orden interna
8	RUC	`proveedor_ruc`	✓ usado	RUC o código de importado
9	Razón Social	`proveedor_nombre`	✓ usado	Nombre del proveedor
10	Secuencia	—	—	Línea dentro de la OC
11	ID Producto	`codigo_avio`	✓ usado	Código interno del avío
12	Descripción	`descripcion_avio`	✓ usado	Nombre + categoría entre paréntesis
13	Cantidad	`cantidad`	✓ usado	Cantidad pedida
14	Unidad de Med.	`unidad_medida`	✓ usado	CN, UND, MTR, B
15	Valor Unit.	`precio_unitario`	✓ usado	Precio unitario
16	% Descuento	—	—
17	Valor con Dscto.	—	—
18	% Aplicado	—	—
19	Valor Venta	`subtotal`	✓ usado	Subtotal
20	IGV	—	—	IGV 18%
21	Total	`total`	✓ usado	Total con IGV
22	Moneda	`moneda`	✓ usado	SOLES / DOLARES
23	Nro Req	—	—	N° de requisición
24	Centro Gestión	`op_codigo`	✓ usado	OP asociada o STOCK GENERAL
25	Estado	`estado`	✓ usado	ATENDIDO / APROBADO
26	Usuario (OC)	—	—	Usuario creador
27	Documento	`factura_proveedor`	✓ usado	N° factura del proveedor
28	Cantidad Recep.	`cantidad_recibida`	✓ usado	Cantidad físicamente recibida
29	Usuario (Recep.)	—	—
30	Ingresos	`numero_ingreso`	✓ usado	N° de ingreso al almacén
31	Cantidad Ing.	—	—
32	UM (Ingreso)	—	—
33	Usuario (Log.)	—	—
34	Lote	—	—	Vacío en dataset actual
35	Fecha Vencim.	—	—	Vacío en dataset actual
36	CG Actual	`op_destino_real`	✓ usado	OP real de destino (pipe-delimited)
37	Cant. Saldo	—	—	Saldo pendiente
38	Núm. Almacén	—	—
39	Nombre Almacén	`almacen`	✓ usado	ALMACEN DE MATERIAS PRIMAS AVIOS
40	Núm. Salidas	`numero_salida`	✓ usado	N° de salida del almacén

Fila celeste = campo activamente usado por FTL Trace

⚠ Estado: No implementado ⚠ Checkpoints: CP2 / CP4 / CP6

Archivo: 7. DPP - TRANSFERENCIAS MATERIALES-PP - QLEVER.xlsx. Registra todos los movimientos internos de materiales entre almacenes de Trento. Incluye tres tipos de flujo que se corresponden con checkpoints de FTL Trace:

TRANSFERENCIA: Tela → Almacén de Corte (soporta CP2)
TRANSFERENCIA: Prendas cortadas → Almacén de Costura PP (soporta CP6)
TRANSFERENCIA: Avíos → Almacén de Productos Intermedios (soporta CP5/CP8)
DIRECTO: Consumo sin guía formal (ajuste/merma)

La columna 18 (Proyecto) contiene la OP — clave de join principal con todos los checkpoints. La columna 20 (Almacén) y 21 (Almacén Destino) identifican el tramo del movimiento.

Acción requerida: Crear entidad TransferenciasMateriales y endpoint POST /api/v1/transferencias-materiales/upload.

Mapeo de columnas

Col #	Nombre en QLever	Campo FTL Trace	Usa	Descripción
1	Fecha	`fecha`	✓ usado	Fecha de la transferencia
2	Número	`numero_guia`	✓ usado	N° de guía de remisión interna
3	Serie Guía	—	—	T001 o vacío para DIRECTO
4	(vacía)	—	—
5	Número Guía	—	—	N° de guía complementario
6	Tipo Salida	`tipo_salida`	✓ usado	TRANSFERENCIA / DIRECTO
7	RUC/NRO DOC	`ruc_receptor`	✓ usado	RUC del receptor externo (si aplica)
8	Razón Social	`receptor_nombre`	✓ usado	Nombre del receptor
9	Sec	—	—	Secuencia
10	Id Producto	`codigo_producto`	✓ usado	Código interno del ítem
11	Descripción	`descripcion`	✓ usado	Nombre + categoría y referencia OP
12	Cod. Marca	`codigo_marca`	✓ usado	Código de marca
13	Descripción Marca	`marca`	✓ usado	Nombre de la marca destino
14	Cantidad	`cantidad`	✓ usado	Cantidad transferida
15	Costo Promedio	`costo_promedio`	✓ usado	Costo promedio unitario (S/)
16	Año Req.	—	—	Año de la requisición
17	Or. Nro	—	—	N° de orden interna
18	Proyecto	`op_codigo`	✓ usado	OP de referencia — clave de join
19	Descripcion	—	—	Descripción del proyecto
20	Almacén	`almacen_origen`	✓ usado	Almacén de origen
21	Almacén Destino	`almacen_destino`	✓ usado	Almacén de destino
22	Usuario	—	—	Usuario que registró
23	Ingreso (Año-Nro-Sec)	`referencia_ingreso`	✓ usado	Referencia al ingreso de origen
24	Serie Ítem	—	—	Serie del ítem

Fila celeste = campo activamente usado por FTL Trace

6. Resumen de implementación

Reporte QLever	Formato	Columnas	Estado	Checkpoints	Campos clave para FTL
OC de Telas	PDF	—	No implementado	CP1	`numero_oc`, `proveedor_ruc`, `op_codes`, artículos + cantidades
Recepción de Tela	Excel	26	IMPLEMENTADO	CP1	`partida`, `orden_compra_tela`, `op_codigo`, `cantidad_kg`, costos
Compra de Avíos	Excel	40	No implementado	CP5 / CP8	`codigo_avio`, `descripcion_avio`, `cantidad`, `op_codigo`, proveedor
Transferencia de Materiales	Excel	24	No implementado	CP2 / CP4 / CP6	`op_codigo`, `tipo_salida`, `almacen_origen/destino`, `cantidad`

Para los tres reportes pendientes se recomienda el mismo patrón del reporte de Recepción de Tela: endpoint de carga de archivo, parser columna-a-campo, batch_uuid para trazabilidad de la carga, y query con filtros por op_codigo y fecha.