FT-USR-03 · Control de acceso por API para terceros

En 30 segundos

Cuando un proveedor o seller catalogue por API, el PIM tiene que saber quién llama, poder cortarlo sin afectar a los demás y no dejar que lo cargue a sus anchas. Esta épica registra a cada tercero en MS-13 con sus negocios, tiendas, alcances y límites, le da credenciales propias en el proveedor de identidad, hace que el gateway de terceros revise cada llamada y su límite, y que Reportes mida el uso para avisar cuando cruce un umbral.

• Módulo dueño: MS-13 Identidad y acceso. También participan: MS-02 Producto, MS-04 Reportes, MS-14 Avisos y ayuda, MS-05 Auditoría.
• Etapa T · Transversal. Recibe de otras épicas y entrega «PE-T · Usuario con permisos y bitácora».
• APIs: construye 8 y usa 4 que construyen otras épicas.
• Eventos: publica 1 y consume 1.

1. Dónde encaja

Recibe

Entrega

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 Rebasa su límite

3.2 Suspender a un tercero

3.3 Medir el nivel de servicio y alertar

4. Si algo sale mal

• Un tercero sin límites configurados intenta escribir. El gateway responde 403 LIMITS_NOT_CONFIGURED; puede leer y validar en sandbox. En su ficha el límite sale «sin configurar», nunca cero ni ilimitado.
• Pasa su tope diario de productos nuevos. El gateway responde 429 DAILY_QUOTA_EXCEEDED hasta el día siguiente; el tercero ve su consumo y Marketplace recibe un aviso si se repite tres días.
• MS-13 no responde al gateway. El gateway usa lo que tiene en caché hasta 60 segundos; sin caché responde 503 DEPENDENCY_UNAVAILABLE. Nunca deja pasar una llamada sin revisar.
• El token no trae el alcance o pide un negocio o tienda que no es suyo. El gateway responde 403 SCOPE_MISSING o BUSINESS_NOT_ALLOWED y el intento queda en MS-05.
• Se filtra el secreto de un tercero. Su administrador lo rota en la pantalla de permisos y el anterior vence de inmediato o en menos de 24 horas; mientras, Gobierno de Producto o Marketplace pueden suspenderlo.

5. APIs

Las que construye esta épica (8)

null

{
  "success": true,
  "data": {
    "items": [
      {
        "partnerId": "PTN-0007",
        "name": "Seller Demo 01",
        "type": "SELLER",
        "status": "ACTIVE",
        "businesses": [
          "MKP"
        ],
        "sellerId": "SELLER-0001",
        "supplierId": null,
        "clients": 2,
        "limitsConfigured": true,
        "createdAt": "2026-10-02T17:20:00Z"
      }
    ],
    "page": 1,
    "size": 50,
    "total": 1
  }
}

null

{
  "success": true,
  "data": {
    "partnerId": "PTN-0007",
    "name": "Seller Demo 01",
    "type": "SELLER",
    "status": "ACTIVE",
    "statusReason": null,
    "version": 5,
    "businesses": [
      "MKP"
    ],
    "sellerId": "SELLER-0001",
    "supplierId": null,
    "shopIds": [
      "SHOP-2231"
    ],
    "scopes": [
      "catalog.read",
      "proposals.write"
    ],
    "limits": {
      "perMinute": {
        "read": 600,
        "write": 60,
        "suggest": 30
      },
      "dailyNewProducts": 500,
      "batchesInProgress": 2
    },
    "sla": {
      "p95Ms": null,
      "errorRatePct": null,
      "availabilityPct": null
    },
    "imageDomains": [
      "(dominio de imágenes del seller)"
    ],
    "clients": [
      {
        "clientId": "cli-7d1e44",
        "env": "SANDBOX",
        "status": "ACTIVE",
        "secrets": [
          {
            "createdAt": "2026-10-03T16:00:00Z",
            "expiresAt": null
          }
        ]
      },
      {
        "clientId": "cli-9a02f8",
        "env": "PROD",
        "status": "ACTIVE",
        "secrets": [
          {
            "createdAt": "2026-10-10T16:00:00Z",
            "expiresAt": null
          }
        ]
      }
    ]
  }
}

{
  "operation": "CREATE",
  "type": "SELLER",
  "name": "Seller Demo 01",
  "sellerId": "SELLER-0001",
  "shopIds": [
    "SHOP-2231"
  ],
  "businesses": [
    "MKP"
  ],
  "scopes": [
    "catalog.read",
    "proposals.write"
  ],
  "limits": {
    "perMinute": {
      "read": 600,
      "write": 60,
      "suggest": 30
    },
    "dailyNewProducts": 500,
    "batchesInProgress": 2
  },
  "sla": {
    "p95Ms": null,
    "errorRatePct": null,
    "availabilityPct": null
  },
  "imageDomains": [
    "(dominio de imágenes del seller)"
  ],
  "clients": [
    {
      "env": "SANDBOX"
    }
  ],
  "reason": "Piloto de catalogación por API"
}

{
  "success": true,
  "data": {
    "planId": "pln-5b1e90",
    "expiresAt": "2026-10-18T15:14:05Z",
    "items": [
      {
        "partnerId": "PTN-0007",
        "from": null,
        "to": "ACTIVE",
        "identityProviderActions": [
          "CREATE_CLIENT_SANDBOX"
        ],
        "gatewayEffect": "Puede llamar en sandbox en cuanto el administrador del seller genere su secreto"
      }
    ],
    "applyUrl": "/api/v2/identity-plans/pln-5b1e90/apply"
  }
}

null

{
  "success": true,
  "data": {
    "clientId": "cli-9a02f8",
    "env": "PROD",
    "partnerId": "PTN-0007",
    "type": "SELLER",
    "status": "ACTIVE",
    "businesses": [
      "MKP"
    ],
    "sellerId": "SELLER-0001",
    "supplierId": null,
    "shopIds": [
      "SHOP-2231"
    ],
    "scopes": [
      "catalog.read",
      "proposals.write"
    ],
    "limits": {
      "perMinute": {
        "read": 600,
        "write": 60,
        "suggest": 30
      },
      "dailyNewProducts": 500,
      "batchesInProgress": 2
    },
    "sla": {
      "p95Ms": null,
      "errorRatePct": null,
      "availabilityPct": null
    },
    "version": 5,
    "cacheSeconds": 60
  }
}

{
  "reason": "ROTACION_PROGRAMADA",
  "keepPreviousHours": 24
}

{
  "success": true,
  "data": {
    "clientId": "cli-9a02f8",
    "secret": "(se muestra una sola vez)",
    "createdAt": "2026-10-18T15:10:00Z",
    "previousSecretExpiresAt": "2026-10-19T15:10:00Z"
  }
}

null

{
  "success": true,
  "data": {
    "partner": {
      "partnerId": "PTN-0007",
      "name": "Seller Demo 01",
      "type": "SELLER",
      "status": "ACTIVE",
      "businesses": [
        "MKP"
      ],
      "limits": {
        "perMinute": {
          "read": 600,
          "write": 60,
          "suggest": 30
        },
        "dailyNewProducts": 500
      }
    },
    "usage": {
      "calls": 18240,
      "rateLimited": 12,
      "errorRatePct": 0.4,
      "p95Ms": 820,
      "slaState": "SIN_UMBRAL"
    },
    "actions": [
      "UPDATE_LIMITS",
      "SUSPEND",
      "ADD_CLIENT"
    ]
  }
}

{
  "window": {
    "from": "2026-10-18T15:04:00Z",
    "to": "2026-10-18T15:05:00Z"
  },
  "replica": "gw-2",
  "items": [
    {
      "clientId": "cli-9a02f8",
      "partnerId": "PTN-0007",
      "operation": "POST /partner/v1/proposals",
      "calls": 58,
      "rateLimited": 0,
      "errors4xx": 3,
      "errors5xx": 0,
      "p95Ms": 840
    }
  ]
}

{
  "success": true,
  "data": {
    "accepted": 1
  }
}

null

{
  "success": true,
  "data": {
    "partnerId": "PTN-0007",
    "from": "2026-10-11",
    "to": "2026-10-18",
    "byOperation": [
      {
        "operation": "POST /partner/v1/proposals",
        "calls": 18240,
        "rateLimited": 12,
        "errorRatePct": 0.4,
        "p95Ms": 820,
        "availabilityPct": 99.95
      }
    ],
    "sla": {
      "p95Ms": null,
      "errorRatePct": null,
      "availabilityPct": null,
      "state": "SIN_UMBRAL"
    },
    "breaches": []
  }
}

Las que usa y construye otra épica (4)

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-USR-03-1. Una credencial por consumidor: cada tercero registrado en MS-13 tiene uno o más clientes de máquina en el proveedor de identidad (credenciales de cliente de OAuth 2.0), uno para sandbox y otro para producción. El token sólo identifica al cliente, su audiencia y sus alcances; negocio, tienda, límites y estado salen del registro (API-13-012). Por qué: Así se sabe quién llama y se corta a uno sin esperar a que venza su token; la propuesta funcional metía negocios y tiendas en el token. Se apoya en PD-26, RF-GEN-08.
• D-USR-03-2. El secreto lo genera el administrador del propio tercero en la pantalla de permisos y se muestra una sola vez; el PIM no lo guarda, sólo el proveedor de identidad. Puede haber dos vigentes para rotar sin corte; el anterior vence en 24 horas como máximo. Por qué: Nadie de Liverpool tiene que ver ni mandar un secreto, y la rotación por API queda fuera de la v1. Se apoya en RF-GEN-08, DUD-33.
• D-USR-03-3. Los límites no tienen valor por omisión: sin límites configurados un tercero no escribe (LIMITS_NOT_CONFIGURED) y su consulta devuelve null. El gateway aplica el límite por minuto por cliente con un contador en cada réplica y cuenta el tope diario sobre los productos que creó; la entrada pone además un tope por puerta para que un tercero no afecte a los demás. Para sandbox y piloto se arranca con 600, 60 y 30 llamadas por minuto (lectura, escritura y sugerencias). Por qué: Ningún consumidor cataloga sin límites (RN-GEN-08) y los talleres no fijaron cifras; un cero o un ilimitado por omisión mentiría. Se apoya en RF-GEN-08, RN-GEN-08, PD-26.
• D-USR-03-4. Suspender o revocar publica PARTNER_CHANGED; el gateway y MS-02 vacían su caché (vigencia máxima de 60 segundos) y la siguiente llamada responde 403 PARTNER_SUSPENDED. Los demás terceros siguen sin cambio. Por qué: La historia pide cortar a uno sin afectar a los demás y sin esperar a que venza el token. Se apoya en PD-26.
• D-USR-03-5. El nivel de servicio se mide desde el primer día por cliente y operación (p95 del tiempo de respuesta, tasa de error y disponibilidad) con el uso por minuto que el gateway entrega a Reportes (API-04-014). No se compromete un SLA hasta la prueba de carga y el piloto; mientras, un umbral configurado en el tercero dispara el aviso de MS-04 por MS-14, y sin umbral el reporte dice «sin umbral». Por qué: No hay cifras en las fuentes; medir primero da la base para fijar el SLA sin prometer algo no medido. Se apoya en RF-GEN-08, PD-26.
• D-USR-03-6. El permiso de catalogar por API (PARTNER-ADMIN) lo da Gobierno de Producto para proveedores y Marketplace para sellers, en la misma pantalla, que compone el BFF con el registro de MS-13 y el uso de MS-04. Por qué: Cada área ya responde por su tipo de tercero y así no hace falta levantar un ticket. Se apoya en RF-GEN-08.

Qué falta decidir

Fuentes

1. [D] trazabilidad/features/FT-USR-03-control-de-acceso-por-api.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.