FT-FLU-04 · Carga masiva de productos por archivo

En 30 segundos

Un seller o proveedor con cientos o miles de productos baja una plantilla de Excel por categoría y negocio, la llena fuera de línea y la sube. El PIM le da al momento un número de carga, valida todo en segundo plano (estructura, listas, obligatorios, lista negra y si ya existe) y al final le entrega un reporte por renglón, haya o no errores. Cada renglón válido nace como propuesta en Borrador, igual que si la hubiera capturado en pantalla.

• Módulo dueño: MS-02 Producto. También participan: MS-01 Catálogo, MS-06 Evaluación, MS-14 Avisos y ayuda.
• Etapa 0 · Entrada. Recibe «PE-C · Catálogo vigente», «PE-T · Usuario con permisos y bitácora» y entrega «PE-1 · Propuesta en Borrador».
• APIs: construye 8 y usa 7 que construyen otras épicas.
• Eventos: publica 4 y consume 1.

1. Dónde encaja

Recibe

Entrega

Cambios de estado que hace

Tareas que abre o cierra: Validación automática.

2. Diagrama de contexto

Quién participa y cómo se conecta. Las pantallas llegan por el BFF del portal, que valida el token y compone; cada módulo vuelve a validar el token y decide sus permisos con los roles de MS-13.

🟩 Verde: nuevo, se construye · 🟦 Azul: ya existe y se queda, se reutiliza su código · 🟧 Naranja: temporal o se retira (se apaga en R3) · ⬜ Gris: sistema externo · ★ módulo dueño

3. Diagrama de flujo

El camino principal, paso por paso. Cuando una pantalla llama a un módulo se ven dos flechas: la pantalla al BFF y el BFF al módulo. Los eventos salen del outbox del módulo después de guardar; quien los consume ignora los repetidos.

3.1 Plantilla prellenada para corregir

3.2 Mercaderías por la misma carga

3.3 Reporte por renglón al terminar

4. Si algo sale mal

• La estructura del archivo no coincide con la plantilla. La subida responde 422 con las columnas que sobran o faltan y no se procesa ningún renglón; el seller ve «esta estructura no coincide» y baja la plantilla vigente.
• Un renglón trae un color fuera de la lista, letras en un número o un EAN repetido. Ese renglón queda «por corregir» con la columna y el motivo (por ejemplo, «EAN duplicado»); los demás siguen. El seller corrige en el mismo archivo y vuelve a subir sólo lo que falló.
• MS-06 no responde o tarda en evaluar. La carga se queda en «evaluando» y MS-02 reintenta por bloque; ningún renglón se crea sin evaluación. Si pasa de dos horas, la carga termina con error de dependencia y el seller recibe el aviso para subirla de nuevo; el archivo original queda guardado.
• La plantilla cambió entre que la bajó y la subió. Los renglones a los que les falta algo que pide la versión vigente salen con TEMPLATE_VERSION_OUTDATED y el detalle de qué falta; si sólo cambió lo opcional, se procesan.
• El archivo pasa de 20,000 renglones o trae más de cinco plantillas. Se rechaza completo con el motivo, nunca se trunca; el seller lo parte en archivos más chicos.

5. APIs

Las que construye esta épica (8)

null

{
  "success": true,
  "data": {
    "business": "MKP",
    "profiles": [
      {
        "profile": "PROPOSALS",
        "maxRows": 20000,
        "maxTemplates": 5
      }
    ],
    "usualTemplates": [
      {
        "templateId": "EU4-0711",
        "path": "Salud > Farmacia > Analgésicos",
        "products": 214,
        "preselected": true
      },
      {
        "templateId": "EU4-0412",
        "path": "Tecnología > Energía > Baterías portátiles",
        "products": 37,
        "preselected": true
      }
    ],
    "recentLoads": [
      {
        "importId": "imp-20261018-0042",
        "status": "DONE_WITH_ERRORS",
        "createdAt": "2026-10-18T16:02:11Z",
        "summary": {
          "rows": 12000,
          "created": 11841,
          "toCorrect": 101,
          "alreadyExists": 49,
          "blocked": 7
        }
      }
    ]
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "profile": "PROPOSALS",
        "name": "Propuestas por plantilla y negocio",
        "for": [
          "PROVEEDOR",
          "SELLER",
          "INTERNO"
        ],
        "formats": [
          "XLSX",
          "CSV"
        ],
        "maxRows": 20000,
        "maxTemplates": 5,
        "permission": "ENT-E"
      },
      {
        "profile": "PLACEHOLDERS",
        "name": "Placeholders de pre-compra",
        "for": [
          "PROVEEDOR",
          "INTERNO"
        ],
        "formats": [
          "XLSX"
        ],
        "maxRows": 20000,
        "maxTemplates": 5,
        "permission": "ENT-E"
      },
      {
        "profile": "PRODUCT_VALUES_V1",
        "name": "Valores de producto (paridad con P360)",
        "for": [
          "INTERNO"
        ],
        "formats": [
          "CSV",
          "XLSX"
        ],
        "maxRows": 100000,
        "maxTemplates": null,
        "permission": "VAL-E"
      }
    ],
    "page": 1,
    "size": 50,
    "total": 8
  }
}

null

"Archivo XLSX: una hoja por plantilla con su versión en el encabezado; cada columna en rojo (obligatorio), amarillo (recomendado) o blanco (opcional) para el negocio; listas cerradas por código; si se pidió por SKU o EAN, un renglón por producto con sus datos. Una hoja «Léeme» explica por qué baja vacía cuando se pidió por categoría."

{
  "profile": "PROPOSALS",
  "business": "MKP",
  "source": {
    "type": "FILE",
    "fileName": "carga-octubre.xlsx",
    "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "sha256": "9f2c41d0…",
    "content": "(el archivo va en la misma petición, multipart/form-data, hasta 50 MB)"
  },
  "applyWhenValidated": false,
  "submitWhenComplete": true,
  "notify": [
    "SCREEN",
    "EMAIL"
  ]
}

{
  "success": true,
  "data": {
    "importId": "imp-20261018-0042",
    "jobId": "job-7c31e0",
    "status": "VALIDATING",
    "received": {
      "rows": 12000,
      "templates": 3
    },
    "links": {
      "self": "/api/v2/product-imports/imp-20261018-0042",
      "apply": "/api/v2/product-imports/imp-20261018-0042/apply",
      "report": "/api/v2/product-imports/imp-20261018-0042/report"
    }
  }
}

{
  "apply": "ALL_VALID",
  "excludeRows": [
    118,
    4021
  ],
  "submitWhenComplete": true
}

{
  "success": true,
  "data": {
    "importId": "imp-20261018-0042",
    "requestId": "req-91d2a4",
    "status": "APPLYING",
    "toApply": 11841,
    "receiptUrl": "/api/v2/product-receipts/req-91d2a4",
    "links": {
      "self": "/api/v2/product-imports/imp-20261018-0042"
    }
  }
}

null

{
  "success": true,
  "data": {
    "importId": "imp-20261018-0042",
    "profile": "PROPOSALS",
    "business": "MKP",
    "origin": "BULK",
    "channel": "FILE",
    "status": "VALIDATED",
    "createdAt": "2026-10-18T16:02:11Z",
    "validatedAt": "2026-10-18T16:09:40Z",
    "summary": {
      "rows": 12000,
      "valid": 11843,
      "toCorrect": 101,
      "alreadyExists": 49,
      "blocked": 7,
      "created": 0
    },
    "items": [
      {
        "row": 7,
        "externalRef": "SKU-PROV-00071",
        "result": "CORRECTION_REQUIRED",
        "errors": [
          {
            "column": "COLOR",
            "attribute": "COLOR",
            "variantRow": 2,
            "code": "VALUE_NOT_IN_LIST",
            "value": "Rojo vino",
            "message": "«Rojo vino» no está en la lista; usa el código"
          }
        ]
      },
      {
        "row": 12,
        "externalRef": "SKU-PROV-00112",
        "result": "ALREADY_EXISTS",
        "match": {
          "matchType": "EAN",
          "catalog": "MARKETPLACE",
          "sku": "1000004812"
        },
        "allowedAction": "MULTI_OFFER",
        "message": "Crea una multioferta: el producto ya existe en Marketplace"
      },
      {
        "row": 15,
        "externalRef": "SKU-PROV-00115",
        "result": "REJECTED",
        "errors": [
          {
            "column": "MARCA",
            "code": "BRAND_BLOCKED",
            "message": "La marca no se puede catalogar en Marketplace"
          }
        ]
      },
      {
        "row": 31,
        "externalRef": "SKU-PROV-00131",
        "result": "CORRECTION_REQUIRED",
        "errors": [
          {
            "column": "EAN",
            "code": "EAN_DUPLICATED",
            "value": "7501234567923",
            "message": "EAN duplicado: lo usa otro SKU del mismo negocio"
          }
        ]
      }
    ],
    "page": 1,
    "size": 200,
    "total": 157
  }
}

null

{
  "success": true,
  "data": {
    "items": [
      {
        "importId": "imp-20261018-0042",
        "profile": "PROPOSALS",
        "business": "MKP",
        "channel": "FILE",
        "status": "DONE_WITH_ERRORS",
        "createdAt": "2026-10-18T16:02:11Z",
        "finishedAt": "2026-10-18T16:21:05Z",
        "summary": {
          "rows": 12000,
          "created": 11841,
          "toCorrect": 101,
          "alreadyExists": 49,
          "blocked": 7
        }
      }
    ],
    "page": 1,
    "size": 20,
    "total": 1
  }
}

null

"Archivo XLSX o CSV: el archivo original con las columnas RESULTADO, ID_PROPUESTA y DETALLE al final de cada renglón; por ejemplo «CORRECTION_REQUIRED | | COLOR: «Rojo vino» no está en la lista»."

Las que usa y construye otra épica (7)

Su request y su response están en la página de la épica que la construye.

6. Eventos

Publica

Consume

7. Datos

Cada colección tiene un solo dueño, el único que escribe en ella.

8. Historias que cubre

9. Decisiones de esta épica

Las tomó el TL como arquitecto; quedan como [Propuesta] hasta que el equipo de la épica las revise.

• D-FLU-04-1. La carga masiva es un trabajo de MS-02 (product_jobs) que corre en su despliegue de trabajo, el mismo artefacto del módulo, como hoy product-massive en Entrada Única. El archivo original y el reporte se guardan en el almacén de archivos; la carga sólo guarda su referencia. Por qué: Las cargas pesadas no deben competir con las pantallas, y separar el despliegue no agrega una pieza que operar (decisión 6 de la validación con código). Se apoya en ADR-12, PD-05.
• D-FLU-04-2. Dos pasos, como hoy en Entrada Única (validar y procesar): subir valida todo sin crear nada y da el ID al momento; al terminar, el seller ve el resultado y confirma los válidos. Con applyWhenValidated los válidos se crean solos al terminar la validación: lo usan el gateway para sus lotes y el seller que lo pida. Por qué: Medido en el código del front (18-oct): hoy son validate-proposal-file y process-proposal-file. Mantener los dos pasos no cambia el hábito del seller y sigue la regla de escribir en dos pasos. Se apoya en RN-MAS-02, RN-MAS-01, DEC-54.
• D-FLU-04-3. Renglón por renglón: un renglón malo no tumba la carga y los válidos se crean. El todo o nada se queda para la carga de configuración del catálogo. Por qué: Es lo que pidieron los talleres (S10: se crea lo que no tiene coincidencia) y lo que hace hoy Entrada Única; resuelve la duda de RQ-14. Se apoya en RN-MAS-04, DEC-58, RF-MAS-08.
• D-FLU-04-4. Un archivo es de un solo negocio. Quien vende en varios negocios baja y sube un archivo por negocio, cada uno con sus colores: rojo obligatorio, amarillo recomendado y blanco opcional. Por qué: El encabezado no admite obligatoriedad por negocio; separar por negocio resuelve PEN-56 sin plantillas combinadas y es la misma regla de un negocio por lote de la API de terceros. Se apoya en PEN-55, PEN-56, DUD-32, RF-MAS-09, RF-MAS-10.
• D-FLU-04-5. Límites de arranque: hasta 20,000 renglones, cinco plantillas y 50 MB por archivo, y dos cargas en proceso por cuenta; lo que pasa el límite se rechaza completo con el motivo, nunca se trunca. La plantilla lleva su versión: si la vigente pide algo que el archivo no trae, el renglón sale con TEMPLATE_VERSION_OUTDATED. Por qué: Cubre los 10,000 a 20,000 productos por archivo de los talleres y las cinco plantillas por archivo de P-07; los valores se ajustan con la prueba de carga. Se apoya en RF-MAS-05, P-07, RN-PLA-08.
• D-FLU-04-6. Prellenado sólo cuando se busca por SKU o EAN (hasta 500 productos por descarga); pedida por categoría, la plantilla baja vacía y lo explica. Un renglón con ID de producto existente es un cambio: vacío = no cambiar y __NULL__ = vaciar, con la misma validación y el mismo motor que un cambio en pantalla; si el producto ya está aprobado, abre la revisión del cambio. Por qué: Cubre H7 y la modificación masiva que hoy hace Entrada Única (RQ-15) sin un flujo aparte. Se apoya en RF-MAS-01, RF-MAT-21, FT-PRD-05.
• D-FLU-04-7. Mercaderías y Suburbia usan la misma carga. Cada renglón válido sigue la ruta de su negocio: en Mercaderías se envía al visto bueno de Compras como cualquier propuesta, y las reglas de datos (EAN usado por otro SKU) las corre MS-06 con la evaluación del bloque. Por qué: El SKU se crea con la misma lógica por cualquier canal y Compras no pierde su revisión por el canal de entrada; resuelve la duda de H5. Se apoya en DEC-59, RN-ALT-12, RN-ALT-05.
• D-FLU-04-8. El reporte sale siempre al final: el mismo archivo con tres columnas de resultado (resultado, ID de la propuesta y detalle) y el resultado por renglón en la pantalla. El aviso de fin lo manda MS-14 por pantalla y correo. Sin SLA hasta medir; la referencia es de 5 a 10 minutos. Por qué: «La clave es el reporte»: siempre, por renglón y sin mandar al seller a otra pantalla; el formato elegido resuelve PEN-59. Se apoya en RN-MAS-04, PEN-59, PEN-12.
• D-FLU-04-9. «Mis categorías» no se guardan aparte: el BFF las calcula de los productos del proveedor (cuenta por plantilla en MS-02) y las nombra con la ruta del árbol de MS-01. Por qué: Un dato que se deduce no se duplica y siempre refleja lo que el proveedor sí catalogó (H6). Se apoya en ADR-12.

Qué falta decidir

También siguen abiertos: PEN-55, Marketplace con Gobierno de Producto confirma cómo se identifica el negocio de un proveedor híbrido (aquí, un archivo por negocio); PEN-59, Ratificar el formato del reporte (aquí, el mismo archivo con columnas de resultado); PEN-12, Confirmar canal y frecuencia del aviso de fin de carga.

Fuentes

1. [D] trazabilidad/features/FT-FLU-04-carga-masiva-productos-por-archivo.md: la ficha de la épica, con sus historias, reglas y bloqueos.
2. [D] ADR-12 · Un solo sistema: backend compartido y una sola base (sección 3.4).
3. [D] docs/arquitectura/por-epica/base/: piezas, colecciones, eventos y el hilo de punta a punta.
4. [D] docs/arquitectura/omega-a-pim-headless/contratos-api.md: convenciones y endpoints de partida.
5. [D] docs/arquitectura/maquina-de-estados-to-be/propuesta-maquina-de-estados.md §7: estados, tareas y canales.
6. [I] Las decisiones de la sección 9 son del TL sobre esas fuentes.