FT-REF-03 · Servicio de matching

En 30 segundos

Antes de catalogar algo hay que saber si ya existe y en qué negocio, para no tener dos fichas del mismo producto. Esta épica busca el producto en Marketplace, Liverpool y Suburbia por EAN y por características (marca, modelo, tipo, color…), le pone una confianza a cada coincidencia y responde lo mismo al alta individual, a la carga masiva y a la API. Si la confianza queda en la zona gris, decide una persona de Gobierno de Datos.

• Módulo dueño: MS-06 Evaluación. También participan: MS-01 Catálogo, MS-02 Producto.
• Etapa 1 · ¿Ya existe?. Recibe «PE-1 · Propuesta en Borrador» y entrega «PE-2 · Sin duplicado».
• APIs: construye 6 y usa 8 que construyen otras épicas.
• Eventos: publica 3 y consume 1.

1. Dónde encaja

Recibe

Entrega

Tareas que abre o cierra: Gobierno de Datos.

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 Coincidencia dudosa: decide una persona

3.2 Buscar para ofertar

3.3 Ajustar pesos, bandas y acciones

4. Si algo sale mal

• La confianza cae entre las dos bandas. La propuesta se guarda y se abre una tarea de Gobierno de Datos. El seller ve «encontramos un producto muy parecido; lo estamos revisando», puede seguir capturando pero no enviar hasta que se resuelva; si era el mismo, se le lleva a ofertar con un aviso.
• El EAN coincide pero la marca no. No pasa como producto nuevo: la confianza se calcula por pesos y cae en revisión, porque puede ser un EAN inventado o un error de captura.
• MS-02 no responde con los candidatos. MS-06 responde 503: la propuesta queda en Borrador sin darse por identificada, no puede elegir plantilla ni enviarse, y MS-02 reintenta; el seller ve que se está revisando su producto.
• Un cambio de bandas manda demasiados casos a revisión. El plan muestra antes cuántas decisiones cambiarían con las evaluaciones de 30 días; si se aplicó y no sirvió, otro plan regresa la versión anterior. Cada evaluación guarda con qué versión se hizo.

5. APIs

Las que construye esta épica (6)

{
  "mode": "LOOKUP",
  "business": "MKP",
  "identifier": {
    "type": "EAN",
    "value": "7501234567893"
  },
  "similar": null,
  "max": 10
}

{
  "success": true,
  "data": {
    "items": [
      {
        "productId": "PRD-0004812",
        "business": "MKP",
        "sku": "1000004812",
        "productName": "Batería externa de 20,000 mAh con carga rápida USB-C",
        "brandCode": "MARCA01",
        "mainImageAssetId": "ast-0009120",
        "confidence": 1.0,
        "allowedAction": "MULTI_OFFER",
        "message": "Vas a ofertar sobre un producto que ya existe: sólo capturas precio e inventario."
      }
    ],
    "page": 1,
    "size": 10,
    "total": 1
  }
}

null

{
  "success": true,
  "data": {
    "business": "MKP",
    "version": 4,
    "updatedAt": "2026-10-15T18:20:00Z",
    "match": {
      "directRule": "EAN_Y_MARCA",
      "weights": {
        "MARCA": 25,
        "MODELO": 25,
        "TIPO_PRODUCTO": 15,
        "COLOR": 10,
        "CATEGORIA": 10,
        "GENERO": 10,
        "CONTENIDO": 5
      },
      "bands": {
        "low": 0.7,
        "high": 0.9
      },
      "bulkFields": [
        "EAN",
        "MARCA"
      ]
    },
    "decisionTable": [
      {
        "rule": "MARCA_O_GRUPO_VETADO",
        "action": "BLOCK",
        "message": "No se puede catalogar: son productos que comercializa Liverpool (1P o Mercaderías)."
      },
      {
        "rule": "MARCA_SOLO_SELLERS_AUTORIZADOS",
        "action": "BLOCK",
        "message": "Esta marca sólo la catalogan los sellers autorizados."
      },
      {
        "matchBusiness": "MKP",
        "sameOwner": false,
        "action": "MULTI_OFFER",
        "message": "Crear multioferta porque existe en Marketplace"
      },
      {
        "matchBusiness": "MKP",
        "sameOwner": true,
        "action": "OWN_DUPLICATE",
        "message": "Ya tienes este producto: modifícalo en lugar de darlo de alta otra vez"
      },
      {
        "matchBusiness": "MER",
        "brandRule": "PERMITIDA",
        "action": "STOCK_OUT",
        "message": "Crear multioferta porque está en Liverpool"
      },
      {
        "matchBusiness": "MER",
        "brandRule": "CON_PERMISO",
        "action": "REVIEW",
        "message": "Necesita autorización antes de ofertar sobre este producto"
      },
      {
        "matchBusiness": "MER",
        "brandRule": "VETADA_PARA_MER",
        "action": "BLOCK",
        "message": "No se puede catalogar: es producto de Mercaderías"
      },
      {
        "matchBusiness": "MER",
        "targetStatus": "DESCONTINUADO",
        "action": "REVIEW",
        "message": "Producto descontinuado en Liverpool: una persona decide si se puede ofertar"
      },
      {
        "matchBusiness": "SUB",
        "brandRule": "CUALQUIERA",
        "action": "BLOCK",
        "message": "No se puede catalogar: es producto de Suburbia y Marketplace sólo vende en Liverpool"
      },
      {
        "match": "ENTRE_BANDAS",
        "action": "REVIEW",
        "message": "Encontramos un producto muy parecido; una persona lo revisa antes de seguir"
      },
      {
        "match": "NINGUNO",
        "action": "CONTINUE",
        "message": "Producto nuevo"
      }
    ],
    "score": {
      "weights": {
        "MANDATORY": "CHECK",
        "RECOMMENDED": 2,
        "OPTIONAL": 1
      },
      "vistoBuenoMinimum": 0,
      "publicationBands": [
        {
          "from": 95,
          "band": "PUBLICAR"
        },
        {
          "from": 85,
          "to": 95,
          "band": "REVISION_PRIORITARIA"
        },
        {
          "to": 85,
          "band": "RETENER"
        }
      ]
    }
  }
}

{
  "business": "MKP",
  "version": 4,
  "changes": {
    "match": {
      "bands": {
        "low": 0.75
      }
    },
    "decisionTable": [
      {
        "matchBusiness": "SUB",
        "brandRule": "CUALQUIERA",
        "action": "REVIEW"
      }
    ]
  },
  "reason": "Bajar falsos positivos de la revisión de coincidencias"
}

{
  "success": true,
  "data": {
    "planId": "pln-6e21b0",
    "expiresAt": "2026-10-18T16:40:00Z",
    "impact": {
      "window": "últimos 30 días",
      "replayedEvaluations": 5000,
      "decisionsChanged": 214,
      "byChange": [
        {
          "from": "REVIEW",
          "to": "CONTINUE",
          "count": 187
        },
        {
          "from": "BLOCK",
          "to": "REVIEW",
          "count": 27
        }
      ]
    },
    "applyUrl": "/api/v2/validation-plans/pln-6e21b0/apply"
  }
}

{}

{
  "success": true,
  "data": {
    "planId": "pln-6e21b0",
    "status": "APPLIED",
    "business": "MKP",
    "version": 5,
    "appliedAt": "2026-10-18T16:12:30Z"
  }
}

{
  "verdict": "SAME_PRODUCT",
  "candidateProductId": "PRD-0002031",
  "taskId": "tsk-40211",
  "comment": "Mismo cargador: el modelo coincide y el EAN del seller es interno"
}

{
  "success": true,
  "data": {
    "evaluationId": "evl-0000740",
    "status": "DONE",
    "review": {
      "verdict": "SAME_PRODUCT",
      "candidateProductId": "PRD-0002031",
      "reviewedAt": "2026-10-19T15:10:00Z",
      "reviewer": {
        "area": "GOBIERNO-DATOS",
        "role": "GOBIERNO_DE_DATOS"
      }
    },
    "decision": {
      "action": "MULTI_OFFER",
      "reasonCode": "EXISTS_IN_MKP_REVIEWED",
      "targetSku": "1000002031",
      "targetBusiness": "MKP",
      "message": "Este producto ya existe en Marketplace: puedes ofertar sobre su SKU."
    }
  }
}

null

{
  "success": true,
  "data": {
    "taskId": "tsk-40211",
    "taskType": "GOBIERNO_DE_DATOS",
    "queue": "COINCIDENCIAS",
    "proposal": {
      "productId": "PRD-0004815",
      "business": "MKP",
      "seller": "SELLER-0002",
      "title": "Cargador rápido 25 W",
      "brandCode": "MARCA03",
      "model": "CG-25W",
      "ean": "7509876500018",
      "mainImageAssetId": "ast-0004502"
    },
    "evaluation": {
      "evaluationId": "evl-0000740",
      "bands": {
        "low": 0.7,
        "high": 0.9
      },
      "decision": "REVIEW"
    },
    "candidates": [
      {
        "productId": "PRD-0002031",
        "business": "MKP",
        "sku": "1000002031",
        "productName": "Cargador de pared 25 W USB-C",
        "confidence": 0.78,
        "fields": [
          {
            "field": "MARCA",
            "matched": true
          },
          {
            "field": "MODELO",
            "matched": true
          },
          {
            "field": "EAN",
            "matched": false
          }
        ],
        "mainImageAssetId": "ast-0002210"
      }
    ],
    "actions": [
      "SAME_PRODUCT",
      "DIFFERENT_PRODUCT"
    ]
  }
}

Las que usa y construye otra épica (8)

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-REF-03-1. MS-06 no lee products ni identifier_registry: pide candidatos a MS-02 por una ruta interna (PEDIDA-FT-REF-03-1) que busca por índice (EAN exacto; marca y modelo normalizados) y devuelve a lo más 10 por consulta. MS-06 calcula la confianza con sus pesos. Por qué: Un dato, un dueño: el producto es de MS-02. Buscar por índice y con tope evita recorrer todo el catálogo en cada alta. Se apoya en ADR-12, RF-MAT-08, DEC-33.
• D-REF-03-2. Cómo se mide: EAN igual con la misma marca es coincidencia directa (confianza 1.0); sin EAN igual, la confianza es la suma de los pesos de las características que coinciden entre las que trae la propuesta. EAN igual con marca distinta nunca pasa como nuevo. Bandas por negocio que arrancan en 0.70 y 0.90: arriba de la alta es el mismo producto (decide FT-FLU-03), entre las dos revisa una persona y abajo es producto nuevo. Por qué: Toma el criterio de taller (match contra el producto por EAN con la marca como peso, umbrales de referencia 70 y 90) y deja la acción de cada rango explícita, que era lo abierto. Se apoya en RF-MAT-06, RF-MAT-07, RN-MAT-11, PEN-22.
• D-REF-03-3. Pesos y bandas son de MS-06 (validation_thresholds) y se cambian con plan y vista previa del impacto. Los MatchingWeights de P360 se migran como punto de partida; la mención de «pesos» en product_reference_tables de MS-02 se retira en la conciliación. Por qué: Quien calcula la confianza es quien guarda sus parámetros; dejarlos también en MS-02 serían dos copias. El umbral de hoy ni siquiera se lee por un nombre mal escrito. Se apoya en DUD-32, RF-MAT-07, ADR-12.
• D-REF-03-4. La zona gris la decide una persona: MS-02 guarda la propuesta, abre GOBIERNO_DE_DATOS en la cola «Coincidencias» y el seller puede seguir capturando pero no enviar hasta que se resuelva. El veredicto se registra en MS-06 (API-06-010), que avisa con EVALUATION_DONE. Reemplaza la bandeja «Revisión Matching» de P360. Por qué: La IA y las reglas proponen y una persona decide lo dudoso, sin que el seller pueda darle la vuelta ni pierda su avance. Se apoya en PEN-22, RN-MAT-07, DEC-62.
• D-REF-03-5. La carga masiva usa la misma evaluación por renglón, sólo con EAN y marca (sin imagen ni URL), con los mismos pesos y la misma tabla: con los mismos datos, el alta individual y la masiva dan la misma decisión. Por qué: Si los canales usan reglas distintas el seller recibe respuestas distintas para el mismo producto. Se apoya en RF-MAT-20, DEC-57, DEC-61, RN-MAS-03.
• D-REF-03-6. En propuestas de Mercaderías y Suburbia, el EAN igual en su propio negocio es duplicado y no se crea (lo cuida además el registro de identificadores de FT-PRD-03); una coincidencia por características sólo avisa a Compras en su visto bueno, no bloquea. Por qué: La sesión de matching de Mercaderías no tiene fecha; esto conserva la regla de hoy (EAN duplicado) sin frenar al proveedor con reglas de Marketplace. Se apoya en DUD-32, PEN-25.
• D-REF-03-7. EVALUATION_DONE sirve para tres casos: el bloque de una carga masiva, la evaluación que tardó por la IA y la revisión de una persona; el cuerpo dice cuál (kind). No se pide un tipo nuevo. API-06-001 y API-06-002 sólo los llama MS-02: aunque su ruta es /api/v2, el BFF no los publica. Por qué: Un solo aviso de «la evaluación cambió» basta para MS-02, que es su único consumidor; menos tipos que mantener. Se apoya en ADR-12.

Qué falta decidir

También siguen abiertos: PEN-22, Ratificar con Gobierno de Producto y Marketplace las bandas (aquí 0.70 y 0.90) y la acción de cada rango; PEN-25, Confirmar que en Mercaderías una coincidencia por características o por imagen sólo avisa.

Fuentes

1. [D] trazabilidad/features/FT-REF-03-servicio-de-matching.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.