Resolución de problemas
Validación y estados de error
Cuando el iframe carga, valida el token y el origen contra la API de Heuristik:
Códigos de error
| Código HTTP | Constante | Significado |
|---|---|---|
401 | UNAUTHORIZED_CODE | El token es inválido o la región no es la asociada |
403 | — | El origen no coincide con la URL registrada |
409 | CONFLICT_CODE | El token ya está asociado a una sesión activa |
421 | MISDIRECTED_CODE | La solicitud fue dirigida al servidor incorrecto |
424 | FAILED_DEPENDENCY_CODE | Un servicio upstream requerido no está disponible |
Cuando la validación falla, el iframe muestra el NotAllowedIframeModal con un mensaje de error. No se envía ningún postMessage al padre.
Problemas comunes
| Síntoma | Causa | Resolución |
|---|---|---|
| El iframe muestra un modal de error inmediatamente | tokenIframe y/o regionCode inválidos | Contacta a tu representante de Heuristik para verificar el token y cóidgo de región |
| El iframe muestra un modal de error con token válido | Discrepancia de origen — tu URL no coincide con la URL registrada | Verifica con tu representante de Heuristik que la URL permitida coincida exactamente con tu dominio |
| Aparece advertencia de cookies | Las cookies de terceros están bloqueadas | Habilita cookies para iframe.heuristik.com en la configuración del navegador |
| Aparece advertencia de permiso de redes locales | El permiso de 'Aplicaciones en dispositivo' no está aceptado o no se está delegando al iframe | Revisa en la configuración de tu navegador que tu sitio web tenga habilitado el permiso para 'Aplicaciones en dispositivo' y que en la carga del iframe se esté delegando dicho permiso mediante allow="local-network-access" |
| Aparece advertencia de permiso de redes locales (II) | El iframe se está cargando en una web http y el navegador bloquea la conexión por contenido mixto | Genera y configura un certificado de seguridad para poder cargar tu web con el protocolo https y evitar la comunicación por contenido mixto |
| Los botones de copiado no funcionan | El permiso de 'Portapapeles' no está aceptado o no se está delegando al iframe | Revisa en la configuración de tu navegador que tu sitio web tenga habilitado el permiso para 'Portapapeles' y que en la carga del iframe se esté delegando dicho permiso mediante allow="clipboard-write" |
| Escáner no detectado | Driver local no está en ejecución | Inicia el servicio del driver local en la estación de trabajo |
| Escáner no detectado (driver en ejecución) | Conexión WebSocket bloqueada | Asegúrate de que ws://127.0.0.1:2794 no esté bloqueado por firewall o proxy |
No se recibe postMessage | La validación de origen en el listener es incorrecta | Verifica que compruebas contra https://iframe.heuristik.com |
Error 409 Conflict | Token ya en uso por otra sesión | Espera a que la sesión activa finalice, o contacta a tu representante de Heuristik para liberar el token |