Valida mi integración de Yuno VTEX headless Web siguiendo este archivo.Funciona igual con cualquier agente de programación (Cursor, Codex, Copilot): pega el archivo como prompt. Audita el código con base en la guía pública “Headless SDK integration” (docs.y.uno/docs/plugins/vtex/direct-sdk-integration) e informa qué está mal, con archivo y línea. Solo lee código y no cambia nada a menos que lo pidas.
El flujo que se valida
onPaymentDone.
Las afirmaciones marcadas como “casos de soporte” o “guía pública” son contexto: explican un síntoma, pero nunca son por sí solas una condición de FAIL.
Cada FAIL de abajo es algo que puedes ver en el código.
Verificaciones
Informa cada una como PASS / FAIL / N/A con la evidencia (archivo:línea). No apruebes una verificación porque el código “parezca correcto”: cita la línea que lo demuestra. Empieza por encontrar cada uso del SDK:grep -rn "sdk-web-vtex\|YunoVTEX\|loadScript\|\.mount(\|unmount(\|domainVTEX\|proxyUrlVTEX" --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build .
- El montaje se ejecuta solo después de que existe el payload del conector
- Rastrea de dónde viene
payload. Según la guía pública, es el payload que el conector de Yuno devuelve durante el paso de autorización de este pedido, y debe existir antes demount. Los casos de soporte muestran que VTEX lo entrega como elappPayloadde una respuesta 428 agatewayCallback(o tu backend retransmitiendopaymentAppData.payload). - FAIL si
mountpuede ejecutarse antes de que el código haya recibido ese payload (carga de la página,useEffectsin protección de payload, un temporizador), con un payload fijo o de ejemplo (el ejemplo del README o de la guía"{\"isVTEXCard\":true,...}"), o con un payload guardado en caché de un pedido anterior. - Por qué: el bundle no tiene contexto de pago propio. Un payload vacío lanza
payload = ... is not valid; uno obsoleto muestra una sesión de checkout que pertenece a otro pedido.
- El payload se pasa como la cadena sin analizar
MountProps.payloades de tipostring; el bundle llama aJSON.parse(payload)por su cuenta.- FAIL si el código pasa un objeto o vuelve a serializar una copia modificada. Pasar un objeto lanza
value.trim is not a functiondesde la validación de mount, antes de queonErrorpueda ejecutarse.
elementRoot es un id de elemento que existe y permanece
elementRoot es un id de elemento que existe y permaneceelementRootse pasa adocument.getElementById, así que es un id simple:'yuno-sdk-root', no'#yuno-sdk-root'(el README de npm muestra'#payment-container', que no funciona).- El elemento debe estar en el DOM cuando se espera
mounty no debe reemplazarse mientras el comprador paga (cambio dekeyde React, renderizado condicional, cambio de ruta en una SPA). - FAIL si hay un prefijo
#o., un montaje antes de que el elemento se renderice, o un contenedor que se vuelve a renderizar en medio del pago. - Por qué: un elemento ausente llama a
onError('Element with id <x> not found')y lanza una excepción; un elemento reemplazado deja el checkout desvinculado y al comprador frente a un área en blanco.
- Un montaje por pedido y
unmount al desmontar
unmount al desmontarwindow.YunoVTEXes una única instancia con una sola raíz de React. Un segundomountdesmonta en silencio el primero, sin importar qué elemento tenga como destino. Verifica quemountse llame una vez por pedido: no en el cuerpo de un render, no en un efecto sin una protección de ejecución única, no en un controladorwindow.addEventListener('message', ...)que acepte cualquier mensaje (la demo de WebView de Yuno hace esto; filtra por untypepropio de tu contrato de bridge e ignora el resto).await yunoVTEX.unmount()debe ejecutarse cuando la página o el componente se desmonta (cambio de ruta, destrucción del componente, WebView cerrado). La Payment App lo hace en la limpieza del efecto.- FAIL si mount puede ejecutarse dos veces para un mismo pedido, o si nada llama a
unmount.unmountsolo elimina la raíz de React:window.YunoVTEX,window.Yunoy las dos etiquetas script permanecen, lo cual es lo esperado.
domainVTEX es el origen exacto de la tienda: esquema y host, sin barra final, sin ruta
domainVTEX es el origen exacto de la tienda: esquema y host, sin barra final, sin ruta- Cita el valor (y de dónde viene: variable de entorno, configuración, cadena). Debe verse como
https://<account>.myvtex.como el propio hosthttps://de la tienda; las minúsculas están bien (el código también aceptahttp://, que una tienda en producción no debería usar). - FAIL si hay: una barra final (
https://mystore.myvtex.com/), cualquier ruta (https://store.com/br), un esquema ausente (store.myvtex.com), o un valor construido por concatenación que pueda terminar en/. - Por qué: el bundle convierte el valor a minúsculas y lo antepone tal cual (
yuno-api.ts), por lo que una barra final producehttps://<host>//api/io/_v/yunopartnerbr.yuno/v4/payments/yuno. En un incidente reportado (un flujo de checkout por WhatsApp), VTEX respondió la solicitud preflight de CORS en esa URL con 405 y sin encabezados CORS, el navegador bloqueó la llamada (Network Error, sin estado), no se creó ningún pago y los pedidos se cancelaron después de 24 h. Al momento de escribir esto, el bundle de producción no elimina la barra. Un valor sinhttp(s)://lanzaonError('Domain must be https. It is <value>'). - Las tiendas servidas bajo una subruta usan el campo
Store Base Pathde la afiliación del conector, nunca una ruta endomainVTEX. Si la página se sirve desde el propio origen de la tienda,domainVTEXpuede omitirse.
proxyUrlVTEX, solo si se usa, llega a la ruta de creación de pago
proxyUrlVTEX, solo si se usa, llega a la ruta de creación de pago- Cuando se define, el bundle envía por POST la creación del pago a este valor tal cual: no se agregan
domainVTEX, ni la ruta base de la tienda ni ningún sufijo/api/io/...(yuno-api.ts). El valor no se valida. - Se ven dos formas. Un host simple, como en el propio ejemplo de la guía pública (
https://proxy.mystore.com): el POST va a la raíz del proxy, por lo que el proxy debe reenviar su raíz a/api/io/_v/yunopartnerbr.yuno/v4/payments/yunode la cuenta de la tienda. Una ruta completa: el POST va a esa ruta, que el proxy debe reenviar de la misma manera. Ambas funcionan cuando el proxy las enruta; informa qué forma se usa. - FAIL solo si la configuración del proxy está en este repositorio y muestra que el valor no llega a la ruta de creación de pago. De lo contrario, informa “necesita confirmación” con el valor.
- Nota para el informe:
proxyUrlVTEXno se aplica a las cuotas de las wallets (/installments/apmusa solodomainVTEX), por lo que una tienda que llega a VTEX únicamente a través de un proxy no obtiene el selector de cuotas de wallets.
- Un solo host de cuenta VTEX por pedido y sin llamadas directas al conector
- El host usado para las llamadas de checkout (
orderForm,transaction,gatewayCallback) y el host dedomainVTEXdeben ser de la misma cuenta VTEX, y esa cuenta debe tener configurada la afiliación del conector de Yuno. La afiliación en sí no se puede verificar en el código. FAIL solo si los dos hosts nombran visiblemente cuentas distintas; informa “necesita confirmación” si provienen de claves de configuración separadas que pueden divergir. - FAIL si tu código llama a
/payments/yuno,/payments/yuno/statuso construye por su cuenta cualquier URL_v/yunopartnerbr.yuno. El bundle crea el pago con el token de un solo uso; una segunda llamada crea un segundo pago o falla. - La verificación de instalación de la Payment App no aplica a headless.
- Solo un Yuno SDK en la página
grep -rn "sdk-web\.y\.uno\|sdk-web\.sandbox\.y\.uno\|@yuno-payments/sdk-web['\"]\|window\.Yuno\b\|yuno-script\|webpackChunksdk_web\|sdk-web-vtex\.y\.uno"sobre el código fuente, las plantillas HTML y los fragmentos de gestores de etiquetas, y pregunta por scripts de terceros (botones express de VTEX IO, fragmentos de wallets).- FAIL si la página también carga sdk-web directamente, o agrega el bundle
sdk-web-vtexcon su propia etiqueta<script>junto aloadScript(el cargador solo evita duplicar su propio#yuno-vtex-script). - Por qué: todas las compilaciones de sdk-web comparten la variable global
webpackChunksdk_web. Una segunda versión de sdk-web corrompe el registro de chunks ystartCheckoutfalla conCannot read properties of undefined (reading 'call'): spinner infinito. Si se cargó otro sdk-web con el idyuno-script, el bundle reutiliza esewindow.Yunoen lugar de su propio v1.6. La Payment App lo soluciona conresetForeignYunoSdk(); una página headless no tiene tal reinicio. En un incidente reportado, dos copias del bundle en una misma página perdieron confirmaciones de pago.
- Opciones de
loadScript
loadScriptversion: déjala sin definir (por defecto'v1', la carpeta móvil que reemplaza cada versión 1.x). FAIL con cualquier otro valor, a menos que Yuno te lo haya dado por escrito;v1.11,v2yv2.0devuelven 404 hoy.env: déjala sin definir (por defecto'prod') en producción, y también en sandbox: el entorno del pago viene del prefijo depublicApiKeysdentro del payload, no del host del bundle. FAIL con'dev'o'staging'en la configuración publicada, e informa cualquier'sandbox':sdk-web-vtex.sandbox.y.unono tiene registro DNS (al momento de escribir esto), por lo queloadScriptse rechaza conFailed to load script.sdkWebEnvenMountPropses una opción distinta: elige el host de sdk-web que carga el bundle ('sandbox'cargahttps://sdk-web.sandbox.y.uno/v1.6/main.js, que sí se resuelve). Déjala sin definir en producción; FAIL con'dev'o'staging'en la configuración publicada.sdkWebVersionno tiene efecto desde el bundle 1.5.0 (el bundle fija sdk-web en v1.6). Infórmala como ruido N/A.- Reintento: si un primer
loadScriptfalló, la etiqueta#yuno-vtex-scriptpermanece en<head>y una segunda llamada espera para siempre un evento que ya se disparó. FAIL si la lógica de reintento vuelve a llamar aloadScriptsin eliminar esa etiqueta (o recargar la página).
- El resultado viene de
onPaymentDone y los errores se manejan
onPaymentDone y los errores se manejanonPaymentDone({ success, payments: [{ status, orderId, paymentId }] })se dispara una vez por montaje: después de que cada sesión de checkout fue exitosa, o en cuanto una falla. Cualquier error también termina el flujo: se ejecutaonErrory le sigueonPaymentDone({ success: false })(sdk.main.tsx), posiblemente antes de que se ejecuten las sesiones posteriores de un pedido dividido. Es la única señal para continuar: página de confirmación, mensaje al bridge nativo, lectura del pedido de VTEX. FAIL si el resultado se infiere del DOM, de una URL, de un temporizador o deonLoading, o si el código supone queonErroryonPaymentDoneson excluyentes (por ejemplo, dos pantallas de fallo, o un reintento iniciado desdeonErrorque elonPaymentDonesiguiente anula).successestrueparaSUCCEEDED,PENDING,READY_TO_PAYyVERIFIED. FAIL sisuccess === truese muestra como “aprobado” sin leerpayments[].statuso el estado del pedido de VTEX (los pagos pendientes se resuelven más tarde mediante el webhook).onError(message, error)debe pasarse y debe mostrar algo al comprador o al bridge. FAIL si está ausente o vacío.mountdebe esperarse dentro detry/catch: los fallos de validación llaman aonErrory además lanzan una excepción.- Recomendado en un WebView: enviar el resultado al bridge nativo primero, antes de cualquier otro trabajo de interfaz, y proteger
cada
JSON.parsede los mensajes del bridge (casos de soporte: un cargador que no esperó amounty publicó tarde perdió confirmaciones). - Para informar, no es FAIL: el bundle llama a
window.location.reload()cuando el comprador cancela la hoja de una wallet (CANCELED_BY_USER) o toca su botón de cerrar, y permanece en silencio (sinonError, sinonLoading(false)) si sdk-web no puede cargarse. Un watchdog puede ofrecer un reintento, pero nunca debe decidir el resultado del pago.
language y deviceFingerprints
language y deviceFingerprintslanguagees obligatorio. El bundle tiene cadenas paraen,es,pt(también acepta variantes regionales por sus primeras dos letras y recurre aen), y reenvía el valor sin cambios a sdk-web, cuyo tipo listapt, nopt-BR. Recomiendapt,esoen. FAIL si está vacío o se calcula comoundefined.deviceFingerprintses un arreglo de{ provider_id, session_id }, conprovider_idtal como está configurado en Yuno (RISKIFIED,SIGNIFYD,CYBERSOURCE,CIELO_CYBERSOURCE_FRAUD).session_iddebe ser elorderFormIdde VTEX en cada pedido: la guía pública dice que el conector envía ese mismo id del lado del servidor, por lo que el proveedor solo puede asociar los datos del dispositivo cuando el navegador también lo usa (y los pedidos divididos lo requieren). FAIL si hay un objeto en lugar de un arreglo, otros nombres de clave (providerId,sessionId), o unsession_idque no es elorderFormIdpara un proveedor configurado.
- Configuración del WebView (solo si la página se ejecuta dentro de una app)
Revisa el código nativo (WebView de Kotlin/Java, WKWebView de Swift, react-native-webview, webview de Flutter):
- JavaScript habilitado, almacenamiento DOM habilitado, cookies de terceros o compartidas habilitadas y un bridge bidireccional.
- Google Pay en Android: Payment Request API habilitada (
WebSettingsCompat.setPaymentRequestEnabled), nuevas ventanas con permiso para abrirse en el mismo WebView (window.open; una bloqueada muestraOR_BIBED_15) y el manifest<queries>conorg.chromium.intent.action.PAY,IS_READY_TO_PAYyUPDATE_PAYMENT_DETAILS. - Apple Pay en iOS: la página debe ser una URL alojada en un dominio verificado en Apple Developer y registrado en Yuno,
nunca un archivo local (
file://, recursos empaquetados). - FAIL por cada configuración faltante que aplique a los métodos de pago que ofrece la tienda.
- Ningún CSS ni JS personalizado depende de nombres internos del SDK
grep -rn "[yY]uno-" --include=*.{css,scss,less,js,ts,jsx,tsx,html,vue}, excluyendo tus propios ids.- Los nombres de clases e ids del SDK no son un contrato. El bundle carga sdk-web v1.6, que usa
yuno-*/Yuno-*; desde sdk-web 1.9 sonsdk-payments-*, y el bundle/v1/se reemplaza sin ningún despliegue de tu parte. La capa de VTEX mantiene sus propios nombres, que son seguros:yuno-checkout-root,yuno-form-root,yuno-external-button-root,yuno-vtex-script, el eventoyuno-sdk-vtex-ready. - FAIL con cualquier selector o
querySelectorsobre un nombre de sdk-web. Ejecuta el escáner y el mapa de renombrado en la verificación de actualización a 1.11 (node yuno-upgrade-check.mjs <dir>) y adjunta su salida.
Formato del informe
Diagnósticos que capturar de una ejecución fallida
- El
orderId/orderGroupde VTEX y la hora UTC del intento (los eventos del bundle están indexados pororderId). - El cuerpo 428 de
gatewayCallback(la cadenaappPayload), sin datos personales. - La entrada de red del POST de creación de pago y su preflight
OPTIONS: URL completa, estado, encabezados de respuesta. Una solicitud ausente después del envío del formulario, oNetwork Errorsin estado, apunta a las verificaciones 5 a 7. - La consola del navegador: el bundle registra las acciones
SET_ERROR,SET_STATUSySEND_STATUS. - Qué recibieron
onPaymentDone/onError, el origen de la página (o la rutafile://) y, para los WebViews, el dispositivo, el SO y la versión de Android System WebView.
Versiones
El bundlesdk-web-vtex 1.11.1 se sirve en https://sdk-web-vtex.y.uno/v1/main.js y carga sdk-web v1.6.
Cargador @yuno-payments/sdk-web-vtex 0.6.1. Pendiente al momento de escribir esto: la eliminación de la barra final de
domainVTEX. Hasta que se publique, la verificación 5 es la única protección.
Lo que este validador no cubre: wallets mediante los endpoints de preflight en apps nativas (consulta los validadores de Flutter y
React Native en esta carpeta), la Payment App de VTEX en sí y la configuración del conector.
Fuentes: la guía pública Headless SDK integration y
Advanced features, el cargador @yuno-payments/sdk-web-vtex 0.6.1, el SDK Web
para VTEX bundle 1.11.1, la Payment App, la demo de WebView de Yuno y el
mapa de renombrado de 1.11; sondeos de CDN y DNS del 2026-10-29.
Los detalles del incidente y el contrato 428 / appPayload provienen de casos de soporte y no se volvieron a verificar en el código.