FT-ARQ-01 · Núcleo headless

En 30 segundos

El núcleo del PIM tiene una sola API de producto: los servicios de MS-02. Da igual si el alta llega de una pantalla, de un archivo, del sistema de un seller o de la migración: pasa por las mismas validaciones, nace igual en Borrador con su origen y sale una sola vez como evento. Las pantallas llegan a esa API por el BFF del portal y los sistemas de terceros por el gateway; ninguna de las dos puertas guarda datos ni decide reglas.

• Módulo dueño: MS-02 Producto. También participan: MS-01 Catálogo, MS-06 Evaluación, MS-13 Identidad y acceso, MS-05 Auditoría, MS-03 Migración y convivencia.
• Etapa T · Transversal. Recibe «PE-C · Catálogo vigente» y entrega «PE-1 · Propuesta en Borrador».
• APIs: construye 2 y usa 15 que construyen otras épicas.
• Eventos: publica 2 y consume 1.

1. Dónde encaja

Recibe

Entrega

Cambios de estado que hace

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 La misma alta por la API de terceros

3.2 Consulta por SKU o EAN, sin editar

3.3 Carga de la migración, sin eventos

4. Si algo sale mal

• Llega una llamada sin token o con un token vencido. El BFF o el gateway responden 401 sin tocar ningún servicio; si algo llega por dentro a un servicio sin token válido, el servicio también lo rechaza (ADR-05). Nadie confía en cabeceras de roles.
• Alguien cambió la propuesta o su plantilla entre el plan y la confirmación. La confirmación responde 409 VERSION_CONFLICT o PLAN_EXPIRED; la pantalla o el tercero piden el plan otra vez sobre la versión nueva y nada queda a medias.
• MS-06 no responde al evaluar. La identificación responde 503 DEPENDENCY_UNAVAILABLE y no se crea nada; la pantalla o el tercero reintentan. Si el evaluationId venció (24 horas) antes de crear, MS-02 evalúa otra vez al crear la propuesta.
• Falla la salida de un evento. El evento está en el outbox de MS-02, guardado en la misma transacción que el cambio: se reintenta hasta salir y nunca se pierde; quien lo consume descarta el eventId repetido.
• La migración trae un EAN que ya usa otro SKU. Ese registro sale rechazado con EAN_IN_USE en el resultado del lote y MS-03 lo deja en sus incidencias; los demás registros del lote sí se cargan.

5. APIs

Las que construye esta épica (2)

null

{
  "success": true,
  "data": {
    "productId": "PRD-0004812",
    "business": "MER",
    "status": "EN_ENRIQUECIMIENTO",
    "version": 9,
    "origin": "PORTAL",
    "matchedBy": {
      "type": "SKU",
      "value": "1000004813",
      "variantId": "VAR-0004812-02"
    },
    "templateId": "EU4-0412",
    "productAttributes": {
      "TITULO": "Licuadora de 10 velocidades",
      "MARCA": "MARCA01",
      "MODELO": "LV-10"
    },
    "variants": [
      {
        "variantId": "VAR-0004812-01",
        "sku": "1000004812",
        "ean": "7501234567893",
        "variantAttributes": {
          "COLOR": "ROJO"
        }
      },
      {
        "variantId": "VAR-0004812-02",
        "sku": "1000004813",
        "ean": "7501234567909",
        "variantAttributes": {
          "COLOR": "NEGRO"
        }
      }
    ],
    "issues": [
      {
        "variantId": "VAR-0004812-02",
        "code": "SAP_ERROR",
        "message": "SAP rechazó el artículo (141): falta el grupo de artículo"
      }
    ]
  }
}

{
  "runId": "mig-run-0007",
  "batch": 12,
  "records": [
    {
      "legacyId": "P360-1100-883421",
      "businessKey": {
        "business": "MER",
        "sku": "1000004812"
      },
      "status": "APROBADO",
      "templateId": "EU4-0412",
      "product": {
        "TITULO": "Licuadora de 10 velocidades",
        "MARCA": "MARCA01",
        "MODELO": "LV-10"
      },
      "variants": [
        {
          "legacyId": "P360-1000-883422",
          "sku": "1000004812",
          "ean": "7501234567893",
          "axes": {
            "COLOR": "ROJO"
          }
        }
      ],
      "channels": [
        {
          "channel": "TIENDA",
          "state": "Publicado",
          "lastSentAt": "2026-09-30T11:20:00Z"
        }
      ]
    }
  ]
}

{
  "success": true,
  "data": {
    "runId": "mig-run-0007",
    "batch": 12,
    "inserted": 98,
    "updated": 2,
    "rejected": 1,
    "items": [
      {
        "legacyId": "P360-1100-883421",
        "result": "INSERTED",
        "productId": "PRD-0004812"
      },
      {
        "legacyId": "P360-1100-883499",
        "result": "REJECTED",
        "code": "EAN_IN_USE",
        "message": "El EAN ya está registrado en MER con otro SKU"
      }
    ]
  }
}

Las que usa y construye otra épica (15)

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-ARQ-01-1. La API única de producto son los servicios de MS-02 (/api/v2/products…, con plan y confirmación). Las pantallas llegan por el BFF del portal y los sistemas de terceros por el gateway /partner/v1; ninguna de las dos puertas guarda datos ni decide reglas, y los servicios no se exponen a internet. Por qué: Un solo dueño del dato y de la regla: si cada puerta validara por su cuenta habría tantas reglas como canales, que es lo que hoy pasa entre Entrada Única y P360. Se apoya en ADR-12, ADR-05, PD-05, PD-26, RF-GEN-01, RF-GEN-10.
• D-ARQ-01-2. Toda alta pasa por las mismas operaciones de MS-02, con los mismos validadores contra la vista efectiva: primero la identificación (API-02-202), que pide a MS-06 la evaluación común sin crear nada; después el alta, paso a paso desde la pantalla (API-02-005 y luego plantilla, valores y variantes) o completa en un paso para archivo y API de terceros (API-02-006 sin productId). La propuesta nace en Borrador con su evaluationId (vale 24 horas; si venció, MS-02 evalúa otra vez); en la carga masiva la evaluación es por bloque (API-06-002). La Validación automática vuelve a evaluar al enviar. Por qué: Una alta en pantalla y la misma por archivo dan el mismo resultado (RF-MAT-20) y el SKU se crea igual por cualquier canal; si ya existe o la marca está vetada no nace nada, y la propuesta llega a PE-1 con lo que pide PE-2 ya guardado. Se apoya en RF-GEN-01, RN-ALT-12, DEC-59, DEC-62, RF-MAT-20.
• D-ARQ-01-3. El alta completa (API-02-006 sin productId) recibe un bloque intake con el origen (BULK o PARTNER_API), el tercero, su externalRef y, si ya se evaluó por bloque, el evaluationId; y acepta thenAction = SUBMIT para que, al confirmar, si está completa, se envíe a revisión en la misma operación. La pantalla sigue con su botón Enviar (API-02-028). Por qué: Un renglón o un tercero que mandan todo de una vez no deben necesitar ocho llamadas ni quedar a medias; así el gateway es un traductor sin estado. Se pide a quienes construyen API-02-006 y la confirmación (API-02-057) que lo acepten. Se apoya en DUD-38, RN-ENR-13, ADR-12.
• D-ARQ-01-4. El origen viaja en el producto, en cada valor y en el sobre de cada evento: PORTAL, BULK, PARTNER_API, SAP, IA o MIGRATION. Lo que propone la IA queda con origen IA y sin confirmar hasta que el usuario lo acepta. Por qué: Cumple H1 (lo prellenado por IA requiere confirmación) y permite que gane lo que mandó el dueño del contenido; DEC-65 ya pedía registrar el origen de toda actualización. Se apoya en DEC-65, PEN-167, RN-ENR-13.
• D-ARQ-01-5. Cada escritura confirmada guarda el cambio, el recibo y el evento del outbox en la misma transacción, y el evento sale una sola vez; los consumidores descartan el eventId repetido. El núcleo no manda avisos a sistemas viejos: los idmc_ los decide FT-INT-06 sólo mientras quede un consumidor que no sea el portal. Por qué:* H5: un cambio hecho en cualquier canal se aplica una vez y llega a todos; con el portal leyendo del PIM por el BFF, Entrada Única ya no necesita copias ni avisos. Se apoya en ADR-12, PD-06, RSG-26.
• D-ARQ-01-6. La consulta por SKU o EAN de cualquier variante es una ruta propia (API-02-201) que lee el registro de identidad y devuelve la familia con los atributos de producto y de variante separados; «no existe» es 404 y «existe con error» es 200 con issues[]. La meta de 50 ms p95 queda sin dato hasta la prueba de carga. Por qué: Es la lectura más frecuente de los consumidores (estudio, gateway, Gobierno de Datos) y no debe depender de la búsqueda general; cumple el criterio de RF-INT-04. Se apoya en RF-INT-04, DEC-PRD-02.
• D-ARQ-01-7. La carga de la migración (API-02-056) es interna, sólo para MS-03, por llave de negocio, sin plan ni eventos: replica lo que ya existía en P360 con su estado y su estado por canal, y el producto entra al hilo en PE-M. Por qué: Publicar millones de altas que no son altas saturaría a todos los consumidores; la trazabilidad de la carga la llevan las corridas de MS-03. Se apoya en ADR-08, FT-MIG-03.
• D-ARQ-01-8. Las reglas de validación viven en MS-02 contra la vista efectiva de MS-01, y la lista negra, las coincidencias y el score en MS-06; el BFF sólo compone y aplica permisos de pantalla, y el front sólo muestra. Un rol sólo de consulta ve la ficha completa: capabilities devuelve todo de sólo lectura y ninguna acción. Por qué: Responde H6 (la lógica vive en el backend) y H7 (consultar sin arriesgar un cambio), y cierra PD-05 y RF-GEN-10 con ADR-12 y la decisión 19. Se apoya en PD-05, RF-GEN-10, DEC-PRD-08, ADR-12.

Qué falta decidir

También siguen abiertos: PEN-05, Confirmar qué orígenes entran al núcleo en el primer corte; las altas que hoy nacen en SAP siguen llegando por el 122.

Fuentes

1. [D] trazabilidad/features/FT-ARQ-01-nucleo-headless-api-unica-producto.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.