- Qué responde
- Cómo entran al Nuevo PIM los sistemas de los proveedores de Mercaderías y de los sellers de Marketplace para dar de alta, corregir, seguir y modificar sus productos por API: qué pieza los atiende, qué reglas aplica, qué avisos reciben y qué falta decidir.
- Para quién
- Los equipos del Nuevo PIM, de Marketplace y de Gobierno de Producto, y arquitectura.
- Estado
- Propuesta del 16-oct-2026. Las decisiones se tomaron para avanzar y esperan a quien las ratifica, que se dice en cada una.
- De dónde sale
- De la propuesta funcional de catalogación por API del 16-oct y del discovery del Nuevo PIM: talleres hasta el 16-oct, la máquina de estados propuesta, el plan de ataque y los contratos del PIM headless.
1. En 30 segundos
- Una sola puerta para los sistemas externos: la API de terceros. Valida el token, revisa que el consumidor esté activo y con permiso, aplica sus límites, orquesta los lotes y manda los avisos. No tiene reglas propias: el producto pasa por las mismas reglas que en el portal.
- Cada servicio vuelve a validar el token. La API de terceros es lo único que se publica para sistemas externos; el núcleo del PIM no queda expuesto.
- El tercero siempre sabe qué pasó. Errores por producto y por campo, un aviso firmado por cada cambio de estado, un feed de respaldo y catorce estados con significado claro.
- Llega con la Fase 2, cuando el Nuevo PIM ya es la fuente del producto. Antes se publican el contrato y un ambiente de pruebas para un piloto.
- Los límites y los tiempos todavía no tienen dato. Se configuran por consumidor, ninguno tiene valor por omisión y no se compromete un nivel de servicio hasta medir.
2. Qué se pidió
- Un quinto camino de alta, además del alta individual, la carga masiva, el scraping y la IA: la catalogación por API del proveedor, abierta y con alertas en tiempo real (RF-ALT-14).
- Con control: «lo que yo no quiero es darle vía libre a un proveedor… de que esté catalogando por APIs a sus anchas» (RN-GEN-08). Una capa delante de las APIs con límite por consumidor, credenciales, nivel de servicio y permisos (RF-GEN-08).
- Lo que contó un seller que sube todo su catálogo por API (taller del 16-oct): que sea estándar y sencilla; la plantilla en JSON por categoría; errores que digan dónde está el problema; la categoría sugerida con una o dos opciones; primero lo básico y luego los atributos.
- Lo que se vio de otro marketplace (taller del 15-oct): el obligatorio y el tipo se rechazan en la petición y la calidad llega después; Liverpool fija el estándar por plantilla y el seller integra una vez.
3. La propuesta: una API de terceros delgada
NuevoExiste y cambiaSe usa tal cualFuera del PIM
Lo que hace
- Valida el token y que el consumidor esté activo, con el alcance, el negocio y la tienda.
- Aplica los límites de cada consumidor: por minuto y un tope diario de productos nuevos.
- Revisa el sobre y traduce el contrato público al del núcleo.
- Orquesta los lotes: un producto malo no detiene a los demás.
- Entrega los avisos firmados, con reintentos, y guarda el feed.
Lo que no hace
- Reglas de producto: blacklist, coincidencias, obligatorios y score viven en el núcleo, igual que para el portal.
- Guardar el catálogo.
- Decidir qué campo puede cambiar cada quien: lo calcula el núcleo.
- Crear ofertas: se crean en Mirakl.
- Escribir en P360.
Por qué es una pieza aparte. El plan sólo separa un servicio con una razón de escala, de equipo o de ritmo de entrega. Aquí hay dos: los límites, los lotes y los reintentos de avisos crecen con el número de terceros y no deben competir con el portal ni con la creación de SKU; y es lo único expuesto a sistemas externos, así que no debe tener acceso a lo que no necesita. El plan ya pedía un gateway sólo para terceros.
Por qué no es un BFF. Un BFF sirve a un front y a la sesión de una persona. Esta pieza sirve a sistemas, con un contrato público y versionado, credenciales de cliente y límites por consumidor.
Una sola tabla de estados. Lo que ve el tercero sale de la misma tabla que usa el portal, dentro del motor de estados. Si el motor agrega un estado y nadie le da su equivalente, fallan las pruebas: nada llega como «desconocido».
4. El alta de punta a punta
- Uno por uno, en línea. El envío individual y la validación previa responden al momento hasta la identificación: si la marca está bloqueada, si el producto ya existe o si no cumple la plantilla, el tercero lo sabe en la respuesta y no se crea nada.
- Lotes, en segundo plano. Se acusan al momento con un identificador; el resultado llega por producto, ligado a la referencia del tercero y nunca a su posición en el lote, y un aviso al terminar.
- Lo demás, por avisos: visto bueno, SKU, imágenes, calidad y publicación.
- Sin borradores por API: la validación previa ocupa su lugar.
5. Lo que ve el proveedor o seller
| Estado | Qué quiere decir para el tercero |
|---|---|
| Requiere corrección | Tiene que corregir o completar algo. Trae los motivos por campo, la acción (corregir campos o subir imágenes) y hasta cuándo puede hacerlo; si ese plazo todavía no está definido, lo dice como «sin plazo», no como una fecha inventada. |
| En aprobación | Liverpool revisa: Compras en Mercaderías; la IA y el score en Marketplace. |
| Aceptada, creando SKU | Recibió el visto bueno y se pidió el SKU a SAP. |
| SKU creado | Ya tiene SKU y EAN por variante. |
| En preparación Liverpool | Liverpool trabaja fotos, calidad o categoría web. |
| En publicación y Publicada | Se envió a cada canal y el canal acusó. El acuse dice que el canal recibió el producto, no que ya se vea. |
| En modificación | Un cambio después de publicar está en revisión; lo publicado sigue a la venta. |
| Retirada y Cancelada | Ya no está a la venta en ningún canal, o se canceló antes del SKU y sus EAN quedaron libres. |
6. Las decisiones
Todas son propuestas, tomadas para avanzar. Ninguna está ratificada.
| Tema | Propuesta | Por qué | Qué la haría cambiar | La ratifica |
|---|---|---|---|---|
| Token, límites y enrutamiento (PD-26) | Cada servicio valida el token; para terceros, una sola puerta: la API de terceros | Lo recomienda el plan (ADR-05) y evita que una sola pieza, si falla, deje todo abierto | Que se exija un producto de gateway administrado, o que el proveedor de identidad no alcance | Arquitectura con Seguridad |
| Primera salida (PD-02) | La API va en la Fase 2; antes, el contrato y el sandbox | Abrir cuando el Nuevo PIM ya es la fuente evita escribir en dos sistemas | Que se suba a los sellers a la Fase 1, o que alguien use hoy el servicio por API de P360 | Dirección, PM y Marketplace |
| Score de Marketplace (PD-24) | Las dos, cada una con lo suyo: antes del SKU frena el visto bueno, que sólo mide lo que el SKU necesita; la calidad del contenido frena sólo la publicación | Cumple a la vez la regla acordada, los diagramas TO-BE y el principio de crear el SKU con lo mínimo | Que se confirme la propuesta de un taller posterior de poner el score antes de publicar | Gobierno de Producto con Marketplace |
| Ofertas en Mirakl (PEN-23) | El PIM no crea ofertas: dice sobre qué SKU ofertar y si Mirakl ya acusó el producto | Producto y oferta van separados; no hace falta un módulo de ofertas | Que se quiera una sola integración para producto y oferta | Marketplace |
| Enriquecimiento (PEN-167) | Gana lo que mandó el dueño del contenido; la IA sólo llena vacíos o propone; cambiar un valor del dueño pide la aprobación de quien tiene permiso sobre ese campo, y se avisa con su origen | Lo que el proveedor entrega por API entra en la catalogación inicial (RN-ENR-13) | Que un título estandarizado por Liverpool deba reemplazar al del seller | Arquitectura con Gobierno de Producto |
| Dónde vive (PD-05) | Pieza propia; las reglas siguen en el núcleo | Escala y perímetro propios; no duplica reglas | Que la demanda medida sea muy baja | Arquitectura |
| Contrato (PD-06) | Un contrato propio para terceros, distinto del que usan Entrada Única y Foro | Un tercero necesita un contrato estable y versionado | Ninguna esperable | Arquitectura con Entrada Única |
| Alertas | Aviso firmado con reintentos, más feed y consulta de estado; para los dos negocios | Se pidieron alertas en tiempo real para ambos negocios | Que los integradores no puedan recibir avisos: entonces, sólo feed | Arquitectura con Seguridad |
| Convivencia con P360 | La API sólo escribe donde el Nuevo PIM ya es la fuente y nunca en P360; el servicio por API que hoy tiene P360 no se porta | Evita la doble escritura sobre lo que se apaga | Que alguien use hoy ese servicio | Arquitectura |
| Categoría de plantilla y categoría web | Separadas: el seller elige la plantilla; la categoría web la asigna Liverpool | Hay sellers que meten productos en categorías vacías para salir primero | Que una sesión dedicada decida un solo árbol | Gobierno de Producto con Category y Marketplace |
| Límites y nivel de servicio | Configuración por consumidor, sin valor por omisión; nivel de servicio sólo después de medir | No hay cifras para dimensionar | Las mediciones | Arquitectura con Seguridad, y Marketplace |
| Quién cambia qué campo | Lo decide el núcleo y la API lo muestra; lo no definido es de sólo lectura | La matriz completa sigue pendiente; mientras, se falla cerrado | La matriz firmada | Gobierno de Producto con Seguridad |
Lo que se deja fuera de la primera versión
- Rotar las credenciales de cliente por API: se hace desde la pantalla de permisos.
- Un plazo de gracia cuando una plantilla agrega un obligatorio: la plantilla tiene versión y se avisa cuando cambia.
- La coincidencia por imagen, el contenido enriquecido del seller, las ofertas desde el PIM, el lote de sólo validación y los avisos por correo.
Cada uno se puede agregar después sin romper la versión 1 del contrato.
7. Números: lo que se sabe y lo que falta medir
Lo que se sabe
- Un archivo de carga masiva trae de 10,000 a 20,000 productos, y hay del orden de 3,000 sellers (RF-MAS-05).
- Hoy salen unas 120 solicitudes de SKU al día a SAP, y la respuesta tarda de 3 a 15 minutos.
- Hoy el portal manda dos lotes a la vez.
Lo que falta medir
- Cuántos productos da de alta cada proveedor al día: se cuenta en la historia de altas de los últimos 90 días.
- Cuánto aguanta el núcleo: una prueba de carga en el ambiente de pruebas.
- Cuántos SKU al día procesa SAP como máximo: se pregunta al equipo de SAP.
- El umbral del score: en los talleres se oyeron tres cifras sin acuerdo.
Valores de arranque, sólo para el sandbox y el piloto. Son supuestos, no compromisos: 600 lecturas, 60 escrituras y 30 sugerencias por minuto; hasta 1,000 productos por llamada de lote y 2 lotes en proceso; hasta 100 productos por validación. El tope diario se fija a mano al dar el permiso. Un límite que nadie configuró se muestra como «sin dato», nunca como cero ni como ilimitado, y ese consumidor no puede escribir.
8. Cuándo llega y cómo convive con P360
| Momento | Qué hay | Qué puede hacer el tercero |
|---|---|---|
| Ahora | El contrato, revisado con un integrador el 19-oct y con un seller que se ofreció como piloto | Leer la documentación y comentarla |
| Antes de producción | Un sandbox con el mismo contrato, credenciales aparte y SAP, Compras y canales simulados | Probar altas, errores y avisos de punta a punta |
| Fase 2 | La API en producción, cuando el Nuevo PIM ya es la fuente del producto | Catalogar con permiso y límites |
- Nunca escribe en P360 ni se construye un puente hacia P360.
- P360 tiene hoy un servicio por API para Marketplace del que no se sabe quién lo usa. Antes de apagar P360 se revisan 30 días de registros: si nadie lo usa, se retira; si alguien lo usa, ese consumidor pasa a la API de terceros o al portal.
9. Lo que falta decidir
| Pendiente | Dónde está | Con quién |
|---|---|---|
| Quién emite los tokens de máquina a máquina y con qué cuota | PD-26 | Arquitectura con Seguridad |
| Quién usa el servicio por API que hoy tiene P360 | DUD-39 | Arquitectura con el equipo de integraciones de P360 |
| Si la API responde en línea o en segundo plano | DUD-38 | Arquitectura |
| Si las alertas son para los dos negocios | DUD-40 | Producto con Marketplace |
| Actualizar el documento de contratos, que todavía supone el gateway actual | DUD-37 | Arquitectura |
| A los cuántos días se cancela una propuesta que nadie corrige | PEN-211 | Compras |
| Dónde termina la rama «masivo por API» del diagrama y si lleva prellenado | PEN-212 | Marketplace con Gobierno de Producto |
| Si la API es para cualquier proveedor con permiso o sólo para los grandes | PEN-213 | Marketplace y Comercial con Gobierno de Producto |
| Qué pasa si el producto existe sólo en Suburbia, que no vende en Mirakl | PEN-19 | Marketplace |
| Si la blacklist aplica también a Mercaderías | PEN-18 | Gobierno de Producto |
| La matriz de quién cambia qué campo | DUD-22 | Gobierno de Producto con Seguridad |
10. Glosario y fuentes
Glosario
- API de terceros. La entrada para sistemas de proveedores y sellers. No es un BFF: sirve a sistemas, no a la pantalla de una persona.
- Núcleo del PIM. MS-01
catalog-governance(plantillas, listas y marcas) y MS-02catalog-product(producto, propuesta y motor de estados), con el servicio de evaluación. - Directorio único. Donde viven los usuarios, los roles y, con esta propuesta, el registro de terceros: quién es cada consumidor de la API, qué negocios y tiendas tiene, sus límites y si está activo.
- Token de máquina a máquina. Una credencial corta que un sistema obtiene con su identificador y su secreto, sin una persona de por medio.
- Webhook. Un aviso que el PIM manda a una dirección del tercero cuando algo cambia, firmado para que el tercero sepa que viene del PIM.
- Feed de eventos. La lista de avisos que el tercero puede consultar si se le perdió alguno.
- Sandbox. Un ambiente de pruebas con el mismo contrato que producción.
- Prefijos de los ID. RF y RN: requerimiento y regla de un taller. PD: decisión pendiente del programa. DUD: duda abierta. PEN: pendiente de taller. ADR: decisión de arquitectura del plan. FT: feature del producto.
Fuentes, en el repositorio del discovery
- La propuesta de arquitectura completa, con decisiones, contratos y riesgos:
docs/arquitectura/catalogacion-por-api/ - La propuesta funcional, con el catálogo de APIs y los estados:
docs/catalogacion-por-api/propuesta-flujo-catalogacion-api.md - La máquina de estados propuesta:
docs/arquitectura/maquina-de-estados-to-be/propuesta-maquina-de-estados.md - Los contratos del PIM headless:
docs/arquitectura/omega-a-pim-headless/contratos-api.md - El BFF por front, para distinguirlo de la API de terceros:
docs/arquitectura/bff-por-front/ - Las diez decisiones del plan de ataque:
docs/plan-de-ataque/README.md - Las decisiones y dudas del programa:
docs/arquitectura/pim-headless/decisiones.mdydudas.md - Requerimientos y pendientes de los talleres:
rag-nuevo-pim/30-requerimientos-funcionales.mdy41-preguntas-abiertas-y-pendientes.md