Buenas prácticas en VTEX Master Data: datos sensibles y formularios

Master Data no es un sitio para dejar datos personales públicos. Repasamos las buenas prácticas para escribir desde la tienda de forma segura, antes de que VTEX bloquee esos campos por ti.

Master Data es una de las piezas más versátiles de VTEX: sirve para guardar suscriptores, mensajes de contacto, solicitudes B2B o cualquier dato propio de la tienda. Pero esa flexibilidad tiene una contrapartida. Durante años se ha vuelto habitual configurar campos públicos para que el navegador lea o escriba sin autenticación, y muchos de esos campos contienen datos personales.

En resumen: los datos personales en Master Data deben ser privados y el acceso debe pasar por una capa que controlas tú. Desde el 26 de octubre VTEX ya no permite crear campos públicos nuevos, así que conviene revisar formularios, newsletter e integraciones y migrar lo que haya quedado abierto.

Qué cambia el 26 de octubre según VTEX

VTEX lo ha confirmado en una nota de release del 22 de octubre: a partir del 26 de octubre de 2026, Master Data v1 y v2 restringen temporalmente la creación de campos públicos. En concreto: 26 de octubre. Para estar preparado, VTEX recomienda dos revisiones:

Los campos nuevos solo se pueden crear como privados.
Los campos privados existentes ya no se pueden pasar a públicos. Cualquier intento de crear un campo público o de convertir uno privado en público devuelve un error y no se aplica.

El motivo que da VTEX es el mismo que defendemos en este artículo: reforzar la seguridad de los datos para que el acceso a la información de la tienda y de los clientes requiera siempre autenticación. Y deja una vía de excepción: si tienes un caso de uso legítimo que necesita campos públicos, puedes abrir un ticket de soporte explicando por qué, y el equipo de producto lo revisa caso por caso. El cambio aplica tanto a campos nativos como personalizados, en v1 y v2, y afecta a todos los que contienen información de identificación personal (PII): nombre, email, teléfono, documento, dirección… y no solo a entidades nativas como CL o AD, sino a cualquier entidad, incluidas las que hayas creado tú.Y no solo en las entidades nativas como CL o AD, sino en todas las entidades de Master Data, incluidas las que hayas creado tú. Los campos que hoy son públicos son los que más probabilidades tienen de verse afectados.

Un matiz importante: los campos públicos que ya existen no se cierran solos. La restricción del 26 bloquea crear campos públicos nuevos y convertir privados en públicos, pero no toca los campos que ya estaban públicos. Si tu tienda tiene una entidad con lectura o escritura pública montada hace meses, sigue abierta después del 26. El cambio frena la sangría nueva, no cierra lo viejo. Por eso no basta con esperar: hay que revisar y migrar a mano lo que ya tengas expuesto.

Por qué los datos sensibles deben ser privados

En Master Data v1 cada campo puede configurarse para que se pueda leer, editar o filtrar sin credenciales. En Master Data v2 ocurre algo parecido con los permisos del JSON Schema de la entidad. Durante años ha sido la forma rápida de montar un formulario: el navegador hace una petición directa a /api/dataentities y listo.

El problema es que lo que el navegador puede hacer sin autenticación, en principio puede hacerlo cualquiera. Por eso los datos personales nunca deberían ser legibles ni modificables desde el frontal sin credenciales: ese acceso es justo lo que VTEX está cerrando.

La forma correcta y segura de trabajar con Master Data es que los datos sean privados por defecto y que el acceso pase siempre por una capa autenticada que controlas tú. Es hacia donde VTEX está empujando a todas las tiendas.

Conviene dejarlo claro: la escritura en Master Data desde la tienda es una necesidad y no se trata de acabar con ella. Una tienda necesita captar suscriptores, recibir mensajes de contacto o guardar solicitudes de sus clientes. Lo que cambia es el camino: el objetivo es consolidar la privacidad de los datos de nuestras entidades, de modo que se pueda seguir escribiendo sin que esos datos queden expuestos.

Lo que puede dejar de funcionar cuando se bloquea un campo

Cualquier funcionalidad que hoy lea o escriba en Master Data desde el frontal sin autenticación es candidata a romperse. Los casos más habituales que vemos en proyectos VTEX son:

Suscripción a la newsletter sin login. Muchas implementaciones escriben o actualizan el campo de opt-in directamente sobre la entidad de clientes, que contiene datos personales.
Formulario de contacto y similares. Trabaja con nosotros, avísame cuando haya stock, solicitudes de presupuesto B2B, reclamaciones…
Scripts heredados de CMS/Portal. Llamadas con fetch o jQuery a /api/dataentities que llevan años funcionando y que nadie recuerda que existen.
Integraciones externas. ERPs, CRMs o herramientas de marketing que leen la entidad sin credenciales o con una appKey sin permiso para campos privados.

Los síntomas típicos serán errores 403, mensajes del tipo “Cannot read private fields” o, lo que es peor, formularios que aparentemente se envían bien pero cuyos registros nunca llegan a guardarse. Por eso conviene probarlos uno a uno, no esperar a que un cliente avise.

Campos sensibles y ofuscación: la nueva gestión nativa de PII

El mismo 22 de octubre VTEX anunció una segunda funcionalidad que encaja con todo lo anterior y que, bien usada, resuelve de raíz buena parte del problema: la gestión nativa de datos personales en Master Data v2. Hasta ahora, si querías cifrar o enmascarar un dato personal, tenías que montar tú esa capa. Ahora la plataforma lo hace por ti.

La idea es declarar, a nivel de entidad, qué campos contienen datos personales y cuál identifica al titular. A partir de ahí, VTEX aplica tres cosas de forma automática:

Cifrado. Los valores de esos campos se almacenan por separado, cifrados y con reglas propias de residencia de datos. El resto de campos se guardan de forma normal.
Enmascaramiento por defecto. Al leer un documento, los campos personales vuelven ofuscados (los caracteres se sustituyen por asteriscos). Para obtener el valor real hay que pedirlo explícitamente con _unmasked=true, lo que deja un rastro claro de quién accede a datos en claro.
Flujos de titulares de datos. Los campos declarados participan automáticamente en las solicitudes de titulares, como el derecho al olvido, lo que te ayuda con el cumplimiento de RGPD.

Se configura con el endpoint PUT /api/dataentities/{entidad}/personalData, indicando los campos y el SubjectIdField. Por ejemplo, declarar email, nombre y documento como datos personales de una entidad de newsletter, usando el email como identificador del titular:

PUT /api/dataentities/Newsletter/personalData

{
  "Fields": ["email", "firstName", "document"],
  "SubjectIdField": "email"
}

Dos límites a tener en cuenta: solo funciona en entidades de Master Data v2 (las v1 como CL o AD no están soportadas) y es opt-in. Las entidades existentes siguen comportándose igual hasta que configuras los campos personales, así que no se activa solo: hay que declararlo entidad por entidad.

Combinado con lo anterior, el patrón recomendado queda redondo: la escritura entra por tu servicio autenticado, los campos sensibles se declaran como datos personales para que VTEX los cifre y enmascare, y la lectura en claro queda restringida y auditable. Defensa en profundidad, sin construir tú la capa de cifrado.

¿Recibes spam o datos de bots que no deseas? Un servicio de escritura propio en Node.js

¿Te llega spam por el formulario de contacto, suscripciones falsas a la newsletter o registros basura que ensucian tu Master Data? Es uno de los problemas más comunes cuando un formulario escribe directamente desde el navegador: al ser un endpoint abierto, cualquier bot puede llenarte el buzón de envíos que no quieres. La escritura en sí no es el problema (tu tienda necesita recibir estos datos); el problema es que no hay nada entre el bot y tu base de datos. La solución habitual es poner en medio un servicio backend que filtre lo que entra antes de guardarlo:

El formulario envía los datos a un endpoint propio, no a /api/dataentities.
El servicio verifica el token de un captcha (reCAPTCHA, hCaptcha o Cloudflare Turnstile) para frenar bots y envíos masivos.
Valida y limpia los campos: solo acepta los que espera, con el formato que espera.
Escribe en Master Data con las credenciales de la propia app, que nunca salen del servidor.
Devuelve al frontal solo lo imprescindible (por ejemplo, un 201), nunca el registro completo.

En una tienda VTEX IO lo más natural es crear una app con el builder node. Así el servicio vive en la infraestructura de VTEX, se despliega con el resto de apps y accede a Master Data mediante policies, sin gestionar appKeys a mano.

Ejemplo: endpoint de contacto en VTEX IO

Primero declaramos una ruta pública en node/service.json:

{
  "memory": 256,
  "timeout": 10,
  "minReplicas": 2,
  "maxReplicas": 4,
  "routes": {
    "contact": {
      "path": "/_v/contact",
      "public": true
    }
  }
}

El handler verifica el captcha, valida los datos y escribe en la entidad con las credenciales de la app. En el ejemplo usamos reCAPTCHA, pero el flujo es idéntico con hCaptcha o Cloudflare Turnstile:

// node/handlers/contact.ts
import { json } from 'co-body'

const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

export async function contact(ctx: Context) {
  const body = await json(ctx.req)
  const { token, name, email, message } = body

  // 1. Verificar reCAPTCHA en el servidor
  const { secretKey } = await ctx.clients.apps.getAppSettings(
    process.env.VTEX_APP_ID as string
  )
  const captcha = await ctx.clients.recaptcha.verify(secretKey, token)

  if (!captcha.success || (captcha.score ?? 1) < 0.5) {
    ctx.status = 403
    return
  }

  // 2. Validar y limitar los campos aceptados
  if (!name || !EMAIL_RE.test(email) || String(message ?? '').length > 2000) {
    ctx.status = 400
    return
  }

  // 3. Escribir en Master Data con las credenciales de la app
  await ctx.clients.masterdata.createDocument({
    dataEntity: 'CT',
    fields: {
      name: String(name).trim(),
      email: String(email).trim().toLowerCase(),
      message: String(message ?? '').trim(),
    },
  })

  // 4. Responder sin devolver datos
  ctx.status = 201
}

El cliente del captcha es un ExternalClient sencillo contra la API de verificación del proveedor. Los tres servicios funcionan igual: reciben el secret y el token del usuario en un POST y devuelven si la verificación es válida. Para cambiar de proveedor basta con cambiar la URL base (https://api.hcaptcha.com para hCaptcha o https://challenges.cloudflare.com/turnstile/v0 para Turnstile) y el host de la policy outbound-access.

// node/clients/recaptcha.ts
import { ExternalClient, InstanceOptions, IOContext } from '@vtex/api'

export default class Recaptcha extends ExternalClient {
  constructor(context: IOContext, options?: InstanceOptions) {
    super('https://www.google.com/recaptcha/api', context, options)
  }

  public verify(secret: string, response: string) {
    return this.http.post<{ success: boolean; score?: number }>(
      '/siteverify',
      new URLSearchParams({ secret, response }).toString(),
      { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
    )
  }
}

Y en el manifest.json damos a la app los permisos que necesita: acceso a Master Data y salida hacia el endpoint de Google.

"policies": [
  { "name": "ADMIN_DS" },
  {
    "name": "outbound-access",
    "attrs": {
      "host": "www.google.com",
      "path": "/recaptcha/api/*"
    }
  }
]

En el frontal, el formulario solo tiene que obtener el token del captcha y hacer un POST a /_v/contact. La entidad CT ya puede tener todos sus campos privados: el navegador nunca habla directamente con Master Data.

¿Qué captcha elegir? reCAPTCHA, hCaptcha o Cloudflare Turnstile

Un endpoint público sigue siendo público: cualquiera puede llamarlo. La diferencia es que ahora tú decides qué entra. Para eso cualquiera de estas tres opciones es válida:

Google reCAPTCHA. El más extendido. La versión v3 (o Enterprise) funciona de forma invisible y devuelve una puntuación de riesgo con la que puedes decidir el umbral.
hCaptcha. Una alternativa centrada en la privacidad, interesante si quieres reducir la dependencia de Google o tienes requisitos estrictos de RGPD.
Cloudflare Turnstile. Gratuito, sin puzzles ni imágenes que resolver y muy poca fricción para el usuario. Puedes usarlo aunque tu tienda no esté detrás de Cloudflare.

Elijas el que elijas, la verificación tiene que hacerse siempre en el servidor, nunca solo en el navegador. Complementarla con validación estricta y un límite de longitud por campo cierra la puerta a la mayoría de abusos.

Checklist de buenas prácticas en Master Data

Inventariar todas las entidades de Master Data v1 y v2 y qué campos son públicos para lectura, edición o filtro.
Buscar en el código del tema y en los archivos del CMS cualquier llamada a /api/dataentities desde el navegador.
Listar todos los formularios de la tienda: newsletter, contacto, solicitudes B2B y cualquier otro.
Revisar con qué credenciales se conectan las integraciones externas y si tienen permiso para campos privados.
Migrar las escrituras públicas a un servicio Node.js protegido con un captcha y probarlo en un workspace.
En entidades v2, declarar los campos personales con el endpoint de personalData para que VTEX los cifre y enmascare.
Recordar que los campos ya públicos no se cierran solos el 26: migrarlos a mano.
Repetir la revisión periódicamente y probar cada formulario de principio a fin, comprobando que los registros llegan a Master Data.

Conclusión

Master Data debería usarse siempre así: datos privados y acceso controlado desde el servidor. Con la restricción de campos públicos del 26 de octubre y el cifrado y enmascaramiento nativos para datos personales, VTEX da pasos firmes en esa dirección. Revisar ahora tus entidades, formularios e integraciones y apoyarte en estas buenas prácticas evita perder leads, suscriptores o solicitudes de contacto, y te deja alineado con el camino que marca la propia plataforma.

Si necesitas ayuda para auditar tu cuenta o construir el servicio de escritura, escríbenos.

Fuentes

VTEX — Master Data: Temporary restriction on public fields (release notes, 22 oct 2026).
VTEX — Master Data v2: Personal data fields with encryption and masking (release notes, 22 oct 2026).
VTEX — Managing personal data in Master Data v2 (guía de desarrollador).
VTEX — Restrict public access to Master Data fields (tutorial).
VTEX — Sobre el modelo de cobro por uso de Master Data (comunidad VTEX).
Google reCAPTCHA, hCaptcha y Cloudflare Turnstile (documentación oficial).

Buenas prácticas en VTEX Master Data: cómo proteger los datos sensibles sin romper tus formularios