Menu
Guides
VTEX IO Apps

VTEX IO Apps
API de lectura del vendor (`empathymx`)
Community extension
Version: 0.2.4
Latest version: 0.2.4

Estado: prototipo probado con vtex link en empathymx/vendorread (11-nov), en la rama claude/feat-vendor-read-api-208e4b (parte de v0.2.1, e3d0a5e). No está publicado ni desplegado.

Objetivo

Que Jorge pueda, desde la cuenta del vendor empathymx, leer las entidades de Master Data propias del conector en cualquier cuenta cliente que lo tenga instalado, sin pedir acceso al cliente. Además, borrar registros de empathyProduct para forzar que un producto vuelva a entrar en el feed (el caso del 304 de Master Data).

Fuera de alcance: datos que no sean del conector, escrituras que no sean ese borrado y cualquier entidad con datos personales.

Arquitectura

Rutas nuevas

Route IDRutaDónde respondeAcceso
vendorReadGET /_v/empathy/vendor/entities/:entityTodas las cuentasPrivada, access: authorized, política get con principal fijado a empathymx, más verifyVendorCaller
vendorDeleteProductsDELETE /_v/empathy/vendor/products?ids=&notify=Todas las cuentasIgual, con la acción delete
vendorProxyReadGET /_v/empathy/vendor-proxy/:account/entities/:entity?workspace=Solo en empathymx (404 en el resto)adminMiddleware (usuario admin de empathymx)
vendorProxyDeleteDELETE /_v/empathy/vendor-proxy/:account/products?ids=&notify=&workspace=Solo en empathymxIgual

Parámetros de lectura (los valida node/utils/vendorQuery.ts):

  • ids=a,b,c: hasta 100 ids de documento. Responde data y missing.
  • Sin ids, lectura por páginas con la búsqueda de Master Data (nunca scroll, ver Riesgos): page (desde 1), size (1–100, por defecto 100), eq.<campo>=<valor> sobre campos indexados de la lista blanca, y since/until (fechas ISO) sobre dateField (por defecto lastInteractionIn en empathyProduct y createdIn en el resto). Se ordena por dateField. La búsqueda solo sirve los primeros 10.000 resultados de cada consulta: para más, se acota con fechas.
  • fields=a,b: un subconjunto de los campos permitidos. Siempre incluye id.
  • La respuesta trae total y, si hay otra página alcanzable, nextPage.

El llamante nunca manda un where libre: el servidor lo construye con nombres de campo de la lista blanca y valores de un alfabeto cerrado ([A-Za-z0-9_.-]). Así no se pueden inyectar cláusulas ni usar un where sobre un campo oculto para adivinar su valor.

Opción A frente a B (elegida: A)

A: ruta del conector (elegida)B: app aparte empathymx.connector-reader
DespliegueVa con la próxima versión del conector, sin nada más que instalarUna app más que publicar, versionar e instalar en empathymx
Confianza en el destinoEl principal ya es este conector (el mismo patrón de las white labels)El conector tiene que confiar en un segundo principal y en otro ciclo de versiones
SuperficieLa ruta proxy existe en todas las cuentas, pero responde 404 si la cuenta no es empathymx y exige un admin válidoAislada: solo existe en empathymx
CosteSM

Se elige A por coste y porque reutiliza un mecanismo ya verificado (verifyWhiteLabelCaller, 5-nov). El inconveniente de A, que la ruta proxy está en todas las cuentas, queda cubierto: sin la cuenta empathymx responde 404 antes de hacer nada.

Lo verificado (y lo que no)

PreguntaRespuestaFuente
¿Cómo se autentica una llamada app→app?Ruta privada con política de recurso. El principal es un VRN vrn:{service}:{region}:{account}:{workspace}:{path}; para apps, service=apps y path=app/{vendor}.{app}@{version}developers.vtex.com, Controlling access to app resources y VTEX Resource Name (VRN)
¿Se puede fijar la cuenta que llama?El VRN tiene el segmento account. El builder acepta el principal vrn:apps:*:empathymx:*:app/…, y la llamada de empathymx a empathymx pasa (prueba e2e del 11-nov). Falta probar que rechaza al conector de otra cuenta: de eso se encarga también verifyVendorCallerDoc VRN; e2e en empathymx/vendorread
¿Qué cabeceras pone el router?En una llamada app→app consume el Authorization y pone x-vtex-caller (vendor.app@versión), x-vtex-caller-role, x-vtex-account y x-vtex-workspace. Pone x-vtex-origin-account/-workspace solo cuando la llamada cruza de cuenta: estaban en aconnector (5-nov) y no en la llamada de empathymx a empathymx (11-nov). Por eso verifyVendorCaller, si falta el origen, toma la cuenta propia (así solo se pueden leer los datos de empathymx). No viene en la docObservado; log temporal en vendorread
¿Se pueden falsificar desde fuera?No (verificado el 11-nov). Por myvtex.com, las rutas privadas ni existen (404, con o sin token y cabeceras falsas). Por app.io.vtex.com sin token, el router responde 401 (Credential required). Con el token de admin de la propia cuenta más x-vtex-caller y x-vtex-origin-account falsos, el router responde 403 (Role User:… cannot perform action GET on resource vrn:…). Las cabeceras falsas nunca llegan a la appe2e, ver "Resultados"
¿Sirve un principal de usuario (vrn:vtex.vtex-id:…:user/*@empathy.co) entre cuentas?No se usa. Los tokens de usuario de VTEX ID pertenecen a una cuenta, y no está documentado que una política de la cuenta B acepte un usuario autenticado en A. Además, la doc dice que la política evalúa solo al dueño del token que llega; por eso el proxy llama con el token de la app, no con el del usuarioDoc Controlling access… (sección del dueño del token)
¿Basta el token de la app en el cliente para leer empathyProduct?Sí. Es lo que ya hace el conector (getProduct, el feed, las limpiezas), con la política ADMIN_DS del manifestCódigo actual
VolumenGandhi tiene millones de empathyProduct. La API pagina con la búsqueda (100 por página, hasta 10.000 por consulta), así que una población grande se recorre por tramos de since/until o por ids en tandas de 100. No usa scroll: cada scroll ocupa durante minutos uno de los 10 que permite MD por cuenta, que son los mismos que necesita el feedUpdate (ver Riesgos)Incidente del 11-nov en Gandhi
#PruebaResultado
1Proxy con sesión de admin → empathyProduct (scroll, 3 docs)✅ 200, solo los campos pedidos, con cursor
1bProxy → empathyConnectorAuditLog✅ 200, sin user ni actionData
1cPedir el campo user✅ 400 field "user" is not readable
1dEntidad fuera de la lista (CL)✅ 404
2Proxy sin sesión✅ 401
3–4bRuta del destino por myvtex.com: sin token, con cabeceras falsas y con el token de usuario✅ 404: el host público no expone rutas privadas
5Destino por app.io.vtex.com sin token y con cabeceras falsas✅ 401 del router
5b–5cDestino con el token de admin de empathymx (Bearer o VtexIdclientAutCookie) más cabeceras falsas✅ 403 del router (la política solo admite la app)
6DELETE en el destino con token de usuario y cabeceras falsas✅ 404
7SSRF por el proxy (:account = evil.com)✅ 400
8Lectura por ids con uno inexistente✅ 200 y missing: ["999999999-1"] (corregido en d1716c8: Master Data responde 200 vacío, no 404)
9–10Segunda página con cursor; filtro eq.whitelabel=1 + since✅ 200
11DELETE por el proxy de un id inexistente, sin notify✅ 200 not-found (corregido en d1716c8: Master Data da éxito al borrar un id inexistente, así que se comprueba antes)

Entre cuentas: empathymx → superxtrapanama/vendorread (11-nov)

#PruebaResultado
X1, X3, X4Lectura de empathyProduct, empathyIndex y auditoría de XtraLa llamada pasa el router, el principal fijado a empathymx y verifyVendorCaller, y llega al handler. Master Data responde 403 "Cannot read private fields"
—CausaLa credencial que llega al destino es la del conector en Xtra (account: superxtrapanama, sub: empathymx.empathy-feed-connector-mr), pero de tipo link, con userLogin: latam@empathy.co. Con una app linkeada, Master Data aplica los permisos de ese usuario, que no puede leer en Xtra. Comprobado: getproduct (ruta existente) da el mismo 403 en el workspace linkeado y responde bien en master con la app instalada. Instaladas, las rutas nuevas usan el token de la app, como getproduct
X2Scroll con filtro en 1,4 M docs504 a los 30 s. Se quita el sort (094473b), y conviene usar since/until en entidades grandes
X5Destino en master (sin la versión nueva)403 del router: la ruta no existe en la versión instalada

Pendiente para después del deploy: lectura y borrado real entre cuentas con la app instalada (primero una lectura en Gandhi).

No probado: el 403 cuando llama el conector instalado en otra cuenta (solo había empathymx; está cubierto por tests unitarios y por el principal fijado) y un borrado real con notify=true.

Modelo de amenazas

Actor y ataqueQué lo para
Cualquiera en internet llama a /_v/empathy/vendor/...Ruta privada: el router exige un token del principal
Una appkey o un usuario de la cuenta clienteNo son el principal (que es una app): 403 del router
El conector instalado en otra cuenta cliente (p. ej. un cliente lee a otro)El principal está fijado a empathymx y verifyVendorCaller exige x-vtex-origin-account === 'empathymx': 403
Otra app de cualquier vendorEl principal es solo este conector, y verifyVendorCaller comprueba x-vtex-caller: 401 o 403
Cabeceras x-vtex-* falsificadasSin token del principal no se llega a la app: 401 o 403 del router (verificado)
Usuario de empathymx sin rol admin, o la ruta proxy en otra cuentaadminMiddleware (audiencia admin) → 401; fuera de empathymx → 404
SSRF por el proxy (:account = evil.com/...)account y workspace deben cumplir ^[a-z0-9]{1,64}$; el host es fijo (app.io.vtex.com)
Exfiltrar datos personalesLa lista blanca no los incluye (ver abajo) y tampoco se puede filtrar por ellos
Inyección en el whereNo hay where libre; los valores van con un alfabeto cerrado
Abuso de volumenrateLimitPerReplica: lectura 120/min y 5 concurrentes; borrado 10/min y 1 concurrente; hasta 100 docs por página y 10.000 por consulta, 100 ids por lectura y 50 por borrado
Borrado masivo por errorSolo empathyProduct y solo por id (sin borrado por filtro), hasta 50 por llamada, y queda en el log
Un admin de empathymx lee datos de clientesEs la intención. Queda trazado: el proxy registra usuario, cuenta destino, entidad y parámetros, y el destino registra la cuenta que llamó, la entidad y cuántos registros devolvió (vtex logs / Splunk de VTEX)

Riesgo residual

  • Cualquier admin de empathymx puede leer. Si se quiere solo a Jorge, se puede añadir una lista de correos en un setting oculto de empathymx (S).
  • Si el token de la app del conector en empathymx se filtrara, daría lectura y borrado de empathyProduct en todas las cuentas. Ese token solo existe dentro del runtime de VTEX IO y no se expone. La ruta pública indexerAuth sí devuelve el token de la app de cada cliente (ver "Cerrar las rutas públicas").

Cómo cumple la regla master-data-security-data-exposure

La regla prohíbe rutas que consulten Master Data y devuelvan los datos tal cual, sobre todo los personales, y recuerda que public:false no es seguridad. Este diseño es una excepción acotada que Jorge tiene que aprobar de forma explícita. Lo justifica esto:

  1. No hay datos personales. Las entidades son del propio conector (catálogo, estados de trabajos y auditoría técnica). En la auditoría se quitan user (correo del admin) y actionData (cuerpos de petición, entre ellos los settings con clientId de Empathy).
  2. La seguridad no es solo public:false. La autenticación la hace la plataforma: access: authorized con una política de recurso cuyo principal es una app concreta fijada a una cuenta. Encima va un segundo control con la identidad que pone el router. No se reinventa la autenticación.
  3. Lo mínimo. Lista blanca de campos y filtros, paginación con límite y sin where libre.
  4. Trazabilidad. Log estructurado en el proxy (quién) y en el destino (qué y cuánto).
  5. No existe la alternativa que propone la regla ("que el navegador consulte la API de VTEX con las credenciales del usuario"). Jorge no tiene usuario en las cuentas de los clientes, y eso es justamente lo que se quiere evitar.
  6. Reduce la exposición actual: permite cerrar getproduct, que hoy es pública y sin autenticación.

Lista blanca

EntidadCampos legiblesFiltros eq.dateField
empathyProductid, createdIn, lastInteractionIn y los campos del feed (FEED_FIELDS: productID, name, skuId, isActive, isVisible, precios, offers, whitelabel, purchased, …)productID, skuId, whitelabel, isActive, isVisiblelastInteractionIn, createdIn
empathyIndexid, fechas, status, mode, totalItems, progress, listedSkus, errorCount, errorstatuscreatedIn, lastInteractionIn
empathyConnectorAuditLogid, fechas, action, status, errorMessageaction, statuscreatedIn, lastInteractionIn
empathyProductCleanupid, fechas, kind, status, stage, workspace, contadores, hasMore, errorstatus, kindcreatedIn, lastInteractionIn

Excluidos a propósito: user y actionData de la auditoría; batches, itemsWithErrors, markFailures y attemptId (cargas codificadas grandes o tokens internos).

Borrado para forzar reindexación

DELETE …/products?ids=7751437-1,7751881-1&notify=true

  • Solo empathyProduct, solo ids <skuId>-<whitelabel>, hasta 50 por llamada.
  • Por qué funciona: si el conector reescribe un documento con los mismos valores, Master Data responde 304 y no mueve lastInteractionIn, así que el documento no vuelve a entrar en ningún parcial. Un documento borrado se crea de nuevo en el siguiente evento de producto, con lastInteractionIn nuevo, y entra en el siguiente parcial.
  • Con notify=true, el conector dispara al momento el mismo evento que skuUpdate (update-empathy-product), con An = la cuenta para la white label 1 y el id de la white label en el resto. También renotifica los ids que no existían (recrearlos es el objetivo).
  • Cuidado: sin notify, el documento queda borrado hasta el próximo cambio del SKU, y un feed completo enviado mientras tanto lo quitaría del índice. Usar siempre notify=true salvo que se quiera eso.
  • Respuesta: results[] con deleted, not-found o failed por id; 207 si alguno falló.

Ejemplo: Gandhi (MD frente al índice)

Regla: un SKU está desalineado si no existe en el índice gandhinew-catalog-es o si lastInteractionIn (MD) es más nuevo que indexMetrics.readTime (índice) por más de 30 minutos.


_10
TOKEN=$(vtex local token) # con sesión de admin en empathymx
_10
BASE="https://empathymx.myvtex.com/_v/empathy/vendor-proxy/gandhi"
_10
_10
# 1. MD: los 24 SKUs del diagnóstico del 11-nov
_10
curl -s -H "Cookie: VtexIdclientAutCookie=$TOKEN" \
_10
"$BASE/entities/empathyProduct?ids=1-1,7751437-1,7751881-1&fields=skuId,isActive,price,lastInteractionIn" > md.json
_10
_10
# 2. Índice: Kibana Latam Main → gandhinew-catalog-es/_search
_10
# {"query":{"ids":{"values":["1-1","7751437-1","7751881-1"]}},"_source":["indexMetrics.readTime","isActive","price"]}
_10
# Guardar la respuesta como es.json


_17
// compare.js — node compare.js md.json es.json
_17
const [md, es] = process.argv.slice(2).map(f => require(require('path').resolve(f)))
_17
const THRESHOLD_MS = 30 * 60 * 1000
_17
const index = new Map(es.hits.hits.map(h => [h._id, h._source]))
_17
_17
const rows = md.data.map(doc => {
_17
const hit = index.get(doc.id)
_17
const mdTime = Date.parse(doc.lastInteractionIn)
_17
const readTime = hit && Date.parse(hit.indexMetrics?.readTime)
_17
const misaligned = !hit || mdTime - readTime > THRESHOLD_MS
_17
_17
return { id: doc.id, lastInteractionIn: doc.lastInteractionIn, readTime: hit?.indexMetrics?.readTime ?? null, misaligned }
_17
})
_17
_17
console.table(rows)
_17
console.log('desalineados:', rows.filter(r => r.misaligned).map(r => r.id).join(','))
_17
console.log('sin documento en MD:', md.missing.join(','))

Para corregir los desalineados (con OK previo, porque es una escritura en producción):


_10
curl -s -X DELETE -H "Cookie: VtexIdclientAutCookie=$TOKEN" \
_10
"$BASE/products?ids=<ids desalineados, hasta 50>&notify=true"

Para una población grande (por ejemplo, todo lo tocado en un día), conviene paginar con since/until y page en lugar de usar ids:


_10
curl -s -H "Cookie: VtexIdclientAutCookie=$TOKEN" \
_10
"$BASE/entities/empathyProduct?eq.whitelabel=1&since=2026-11-10T00:00:00Z&until=2026-11-10T06:00:00Z&size=100&fields=lastInteractionIn"
_10
# Repetir con &page=<nextPage> hasta que no venga nextPage. Si total pasa de 10.000, acortar el tramo.

Cerrar las rutas públicas existentes

RutaQuién la usaPropuestaCoste
getproduct (GET, pública, sin auth)Diagnóstico (Jorge)La sustituye vendor/entities/empathyProduct?ids=. Quitar la ruta o ponerle adminMiddlewareS
skuupdate (POST, pública, sin auth)El broadcaster de catálogo de VTEX (webhook) y las notificaciones manualesSuscribirse al evento IO vtex.broadcaster (broadcaster.notification) en service.json en lugar del webhook HTTP. Mientras convivan, exigir un secreto aleatorio (setting oculto generado al instalar) en la query de la URL registrada. Las notificaciones manuales pasan por la ruta del vendorM
feedupdate (POST, pública, sin auth)index-vtex-connector al terminar un índice delegado; el panel de adminExigir fullIndexId de un empathyIndex en in-progress/generating-files más el secreto del punto siguiente (el mismo patrón que indexerAuth), o un usuario admin. Una llamada sin eso → 403M
indexer-auth (GET, pública) devuelve el token de la app a quien conozca un id de empathyIndex recienteindex-vtex-connector (cada contenedor pide un token por callback)El conector genera un secreto aleatorio por trabajo, guarda su hash en el empathyIndex y lo manda en POST /indexation-requests (por TLS). indexer-auth exige id + secreto. Requiere un cambio coordinado en index-vtex-connector. A largo plazo, que el indexador use una appkey propia por cliente con un rol mínimo (lectura de catálogo y empathyProduct) en lugar del token de la appM (+ cambio en el indexador)
logcleanup (POST, pública, sin auth)Cron internoadminMiddleware o pasarla a eventoS
fullupdate/status, fullupdate/status/:id (GET, públicas)Panel de adminadminMiddlewareS

Las white labels no se ven afectadas: ya usan whitelabelnotify/whitelabelproduct, que son privadas con política y verifyWhiteLabelCaller.

Tareas

#TareaTamañoEstado
1Rutas vendor/entities, vendor/products (DELETE) y proxy, con middleware, lista blanca y testsM✅ 52c1b9b, 90dbf98, d1716c8; 68 suites y 585 tests en verde
2vtex link en empathymx (workspace de dev) y prueba e2e, incluidas las negativasS✅ 11-nov, ver "Resultados"
3Confirmar si el principal fijado a empathymx funciona; si no, volver a *S✅ Admite a empathymx; falta ver que rechaza a otra cuenta (tarea 4)
4Probar entre dos cuentas reales (p. ej. empathymx → empathymxwl1), incluido 403 desde otra cuentaSPendiente
5Opcional: lista de usuarios permitidos para el proxy (setting oculto en empathymx)S—
6Cerrar getproduct, logcleanup y los statusS—
7skuupdate con evento del broadcaster y secreto transitorioM—
8feedupdate + indexer-auth con secreto por trabajo (coordinar con index-vtex-connector)M—
9Script de reconciliación Gandhi a escala (MD por scroll frente a ids en ES)M—
10Publicar como beta, desplegar e instalar en clientes (requiere OK)S—

Riesgos

  • No está probado que el principal fijado rechace a otra cuenta (tarea 4). Mitigación: verifyVendorCaller también comprueba la cuenta.
  • Las cabeceras del router no están documentadas: si VTEX las cambia, el acceso se cierra (falla de forma segura: 401).
  • Agotar los scrolls de MD de la cuenta cliente (ocurrió el 11-nov en Gandhi con la 0.2.2): cada lectura por páginas abría un scroll, y unas 150 seguidas llenaron el cupo de 10 por cuenta. Los parciales del cron fallaron con "Maximum simultaneous scrolls rate exceeded (10)". Corregido en la rama fix/vendor-read-no-scroll: la API pagina con la búsqueda, que no usa scroll. Lección: una ruta que lee en el contexto del cliente no debe usar recursos de cupo compartido con el conector.
  • Borrado sin notify: deja el producto fuera hasta el siguiente cambio, y un feed completo lo quitaría del índice. Mitigación: documentado; se podría hacer notify=true por defecto.
  • Clientes con versiones viejas: la ruta solo existe donde esté instalada la versión nueva (@0.x se propaga sola tras el deploy).
On this page
Was this helpful?