Integración embebida de ONP

Este documento describe cómo incrustar la experiencia de onboarding de Guardline directamente dentro de su aplicación mediante un iframe. El modo embebido permite que sus usuarios completen la verificación de identidad sin salir de su interfaz.

El modo embebido y el modo de enlace directo comparten el mismo backend, el mismo motor de decisión y los mismos proveedores de verificación. Las únicas diferencias son el punto de entrada (el src del iframe frente a la navegación de página completa) y la presencia de un canal PostMessage para la comunicación en tiempo real con la página host. Para todo lo que no sea específico del iframe, consulte la referencia de la API de ONP.

Esta página se centra en lo que es específico de la incrustación en iframe: los atributos del iframe y los permisos necesarios, el indicador de modo embebido (surface_hint=embed), los eventos PostMessage, la compatibilidad de navegadores y las cuestiones de seguridad propias de un contexto de iframe cross-origin.

Principios de diseño

Cuatro principios guían la integración embebida:

• Transparencia para el usuario final: el onboarding debe percibirse como una parte nativa de la aplicación del integrador. El usuario no debe notar que está interactuando con un sistema externo. La identidad visual (colores, logotipos, textos personalizados) es totalmente configurable por flujo y la gestiona el backend de Guardline, no los parámetros de la URL ni el código del lado del cliente.
• Seguridad por defecto: el iframe opera en un contexto cross-origin, es decir, el sitio del integrador y el onboarding de Guardline se ejecutan en dominios distintos. Toda la comunicación entre ambos usa canales seguros: PostMessage con validación estricta de origen y webhooks con firmas HMAC-SHA256. Los tokens de sesión son efímeros, criptográficamente seguros y están vinculados a una única ejecución.
• El backend como fuente de verdad: toda la información persistente (estado de la sesión, datos recopilados, resultados de verificación, configuración visual) reside en el backend de Guardline. El frontend del iframe no mantiene ningún estado que no se pueda reconstruir desde el backend. Esto garantiza que las sesiones se puedan reanudar aunque el iframe se destruya y se vuelva a crear.
• La misma infraestructura, dos puntos de entrada: el modo embebido y el modo de enlace directo comparten toda la pila. El frontend detecta automáticamente si se está ejecutando dentro de un iframe y activa el canal PostMessage en consecuencia. No hace falta ninguna configuración aparte.

Flujo de integración

El onboarding embebido involucra a cuatro participantes que se comunican en secuencia: el backend del integrador, la API de Guardline, el frontend del integrador y el iframe de Guardline.

El proceso comienza cuando el backend del integrador crea una sesión. Llama a POST /api/v1/onboarding/sessions con surface_hint: "embed" para activar el saneamiento de PII en el resolutor. La API devuelve el token, el ID de ejecución y la embed_url que el frontend del integrador usa como src del iframe.

El iframe se carga, resuelve el token mediante GET /api/v1/link/{token} y recibe todo lo que necesita para renderizar el onboarding: configuración del flujo, identidad visual y datos del cliente (saneados). El usuario navega por los pasos; cada paso completado se persiste en el backend. El iframe envía eventos PostMessage a la página host informando del progreso.

Cuando se completa el último paso, el backend ejecuta automáticamente el motor de decisión. El iframe comunica la conclusión a la página host mediante PostMessage y el backend dispara un webhook al backend del integrador con el resultado.

Creación de una sesión en modo embebido

La creación de la sesión usa el mismo endpoint POST /api/v1/onboarding/sessions que el modo de enlace directo. Consulte Creating a Session para ver el esquema completo de la solicitud y el contrato de la respuesta.

La única diferencia específica del modo embebido es el campo surface_hint en la solicitud:

{
  "flow_type": "kyc",
  "surface_hint": "embed",
  "primary": {
    "full_name": "Maria Santos",
    "tax_id": "12345678900"
  }
}

Cuando se define surface_hint: "embed":

• La sesión queda marcada como de modo embebido en el momento de su creación.
• GET /api/v1/link/{token} devuelve un payload saneado que elimina los campos de PII que el iframe no debe mostrar (CPF, correo electrónico, teléfono, birth_date, URLs del representante).
• El indicador es interno del servidor y no se refleja en ninguna respuesta. Los integradores observan su efecto a través de la forma saneada de la respuesta del resolutor.

Para conocer el comportamiento completo del saneamiento, consulte PII Sanitization Behavior en la referencia de la API.

El campo embed_url de la respuesta de creación de la sesión es la URL canónica que se debe montar en el iframe. Apunta a la misma ejecución que url (el punto de entrada de enlace directo). Ambas URLs se resuelven en el servidor a través del mismo endpoint GET /api/v1/link/{token}; la diferencia está en la capa de frontend en la que aterriza el usuario.

Para la autenticación (X-API-Key), la idempotencia (Idempotency-Key), las respuestas de error y el esquema completo de solicitud y respuesta, consulte la referencia de la API de ONP.

Incrustación del iframe

El frontend del integrador incrusta el onboarding montando un elemento iframe que apunta a la embed_url devuelta por el endpoint de creación de la sesión.

La embed_url se devuelve sin cadena de consulta y, en esa forma, no emite ningún evento PostMessage. El puente de PostMessage permanece inerte hasta que el iframe recibe un origen padre válido, que lee de un parámetro de consulta origin en su propia URL. Añada ?origin=<el origen de su página> a la embed_url antes de montarla, donde el origen es el esquema, el host y el puerto exactos de la página que aloja el iframe (por ejemplo, https://app.acme.com, o https://app.acme.com:8443 cuando se usa un puerto no predeterminado). Si el parámetro falta, el iframe recurre al referrer del documento, lo que no es fiable y queda suprimido por las políticas de referrer más habituales. Defina el parámetro de forma explícita. El origen también debe figurar entre los orígenes permitidos configurados para su instancia.

Atributos obligatorios

El iframe requiere declaraciones de permisos explícitas para funcionar correctamente. Sin ellas, el navegador bloquea de forma silenciosa el acceso a la cámara y a los sensores de movimiento, y el onboarding no puede avanzar más allá de la verificación biométrica.

Atributo	Valor	Propósito
src	embed_url de la respuesta de creación de la sesión, con ?origin= añadido	Apunta al onboarding de Guardline correspondiente a esta sesión. El parámetro origin es obligatorio: sin él, el iframe no emite ningún evento PostMessage.
allow	camera; geolocation; accelerometer; gyroscope; magnetometer	La cámara es necesaria para la captura de documentos y la verificación biométrica. Los sensores de movimiento son necesarios en dispositivos móviles para la detección de liveness. La geolocalización permite que la pantalla de términos registre el lugar de la aceptación como evidencia de consentimiento; el usuario final puede rechazar la solicitud del navegador sin que eso bloquee el recorrido.
width	100%	El diseño del onboarding es responsivo y se adapta al ancho del contenedor.
height	100% del viewport o un valor fijo (mínimo 600px)	El diseño está pensado para ocupar toda la altura de su contenedor.

Atributos que se deben evitar

El atributo sandbox no se debe usar. Restringe las capacidades del iframe (formularios, scripts, ventanas emergentes, acceso a la cámara) de formas que dejan el onboarding inoperante.

Dimensionamiento

El integrador debe definir la altura del iframe con un valor fijo, normalmente el 100% del viewport. El diseño del onboarding está pensado para ocupar todo el contenedor.

El redimensionamiento automático de la altura en función del contenido está disponible mediante el evento PostMessage height-changed. El iframe informa de la altura de su contenido a medida que esta cambia, con un intervalo mínimo de 200 ms entre avisos, de modo que la página host recibe como máximo cinco actualizaciones de altura por segundo y debe tratar cada valor como la última altura conocida y no como un flujo continuo. La página host puede ajustar el elemento iframe en consecuencia. Este enfoque es opcional y funciona mejor en diseños en los que el iframe no ocupa todo el viewport.

Ejemplo

<iframe
  src="https://acme.onp.prod.guardline.com.br/embed/t/abc123def456?origin=https://app.acme.com"
  allow="camera; geolocation; accelerometer; gyroscope; magnetometer"
  width="100%"
  height="100vh"
  style="border: none;">
</iframe>

Token en la URL: mitigaciones de filtración

El token de sesión está presente en la ruta de la URL del iframe. Se trata de una decisión de compromiso deliberada: permite una incrustación sin estado sin exigir que la página host inyecte credenciales mediante PostMessage antes de que el iframe pueda inicializarse. Las siguientes mitigaciones limitan la superficie de exposición:

Vector de filtración	Mitigación
Cabecera Referer	El documento embebido no define Referrer-Policy, por lo que se aplica el valor predeterminado del navegador. Los navegadores actuales usan strict-origin-when-cross-origin por defecto; bajo esa política, las solicitudes salientes del iframe (a proveedores de verificación, CDNs) envían solo el origen (https://acme.onp.prod.guardline.com.br) y nunca la ruta completa que contiene el token. Un navegador configurado con una política más permisiva enviaría más información.
Historial del navegador	La URL con el token se carga dentro de un iframe, no en la navegación de nivel superior. Las navegaciones del iframe no se registran en la barra de direcciones ni en el historial del navegador.
Analítica y scripts de terceros	El frontend del onboarding no incluye scripts genéricos de analítica de terceros. Los SDK de los proveedores se cargan únicamente con fines de verificación y Guardline no reenvía valores de token como identificadores de analítica.
Registros del integrador	El integrador debe tratar los campos embed_url y token de la respuesta de creación de la sesión como datos sensibles. Evite registrar estos valores en texto plano. El execution_id es el identificador seguro para registros y correlación.

Configuración visual

La identidad visual del onboarding es totalmente dinámica y la gestiona el backend de Guardline. No se pasa ningún parámetro visual por URL, cadenas de consulta ni código del lado del cliente.

Cuando el iframe resuelve el token de sesión, el backend devuelve la configuración visual completa asociada al flujo:

Ajuste	Descripción
Colores primario y secundario	En variantes oscura y clara, usados en botones, acentos y elementos interactivos.
URLs de los logotipos	Alojadas en CDN, en versiones para fondos oscuros y claros.
Modo de tema	Oscuro, claro o automático (sigue la preferencia del sistema del usuario).
Estilo de los botones	Colores de fondo, de texto y de icono por tema.
Ajustes por paso	Cada paso puede sobrescribir los colores base y los ajustes de diseño.

El frontend aplica estos ajustes como propiedades personalizadas de CSS en el momento del renderizado. Cambiar la identidad visual no exige cambios de código ni un nuevo despliegue: actualice los ajustes en el panel administrativo de Guardline o mediante la API y la siguiente sesión reflejará la nueva configuración.

Este diseño garantiza la coherencia visual entre el modo de enlace directo y el modo embebido. Ambos usan la misma fuente de configuración (el backend), de modo que el integrador no necesita sincronizar parámetros visuales entre varios puntos de integración.

Eventos PostMessage

El iframe y la página host se comunican exclusivamente mediante PostMessage, el mecanismo nativo del navegador para la comunicación cross-origin entre ventanas. Cada mensaje enviado por el iframe lleva un identificador source que permite a la página host filtrar los mensajes relevantes.

Estructura del mensaje

Todos los mensajes siguen este formato:

{
  "source": "<slug>-onboarding",
  "event": "event-name",
  "payload": {}
}

El campo source es <slug>-onboarding, donde <slug> es el identificador de cliente de su instancia de Guardline. El valor es fijo para una instancia dada, pero cambia de una instancia a otra, de modo que no es la misma cadena para todos los integradores. Confirme el valor exacto de su instancia con el equipo de Guardline durante la puesta en marcha y filtre por ese valor. Un listener que filtra por un identificador genérico fijado en el código descarta todos los eventos en una instancia que define su propio slug.

Referencia de eventos

ready

Se emite cuando el iframe se ha montado y está listo para mostrar el primer paso. En las rutas con token se emite dos veces: una al montarse, antes de que se resuelva el token de sesión, y otra después de la resolución.

Campo del payload	Tipo	Descripción
executionId	UUID	El identificador de ejecución de esta sesión de onboarding. Úselo para correlacionar la sesión embebida con sus registros internos. Normalmente está ausente en el primer ready, que se produce antes de que la sesión se resuelva, y presente en el segundo.

La página host puede usar este evento para ocultar un indicador de carga y mostrar el iframe. Gestiónelo de forma idempotente: una página host que muestra el iframe con ready ejecutará esa lógica dos veces, y una página host que lee executionId en ready debe tolerar que el campo falte la primera vez.

step-changed

Se emite cada vez que el usuario avanza al paso siguiente o vuelve atrás.

Campo del payload	Tipo	Descripción
executionId	UUID	El identificador de ejecución.
stepId	string	El identificador del paso actual (por ejemplo, document-front, biometric-iproov).
stepIndex	integer	Índice del paso actual en el flujo, empezando en cero.
totalSteps	integer	Número total de pasos del flujo.

El conjunto de códigos de paso es específico de cada flujo y de cada país, por lo que los códigos anteriores son ejemplos y no una lista fija. Confirme los códigos de su flujo con el equipo de Guardline antes de ramificar según stepId y no fije en el código un switch basado en los ejemplos de este documento.

La página host puede usar este evento para mostrar un indicador de progreso externo, registrar analítica o ajustar la interfaz circundante.

completed

Se emite cuando el usuario ha enviado todos los pasos obligatorios. Este evento indica que la parte del recorrido que corresponde al usuario ha terminado, no que se haya tomado una decisión final. El campo decision ofrece una indicación inmediata del resultado, pero el webhook es la fuente autorizada del resultado final de la decisión.

Campo del payload	Tipo	Descripción
executionId	UUID	El identificador de ejecución.
decision	string	Indicación inmediata de la decisión: approved, rejected, in_review o unconfirmed. Cuando es in_review, la ejecución se ha derivado a un analista humano y el resultado final llegará exclusivamente por webhook (onboarding.approved u onboarding.rejected). Cuando es unconfirmed, el frontend no pudo confirmar el veredicto del backend; el recorrido terminó, pero el iframe desconoce el resultado.

Tratamiento habitual en el frontend según el valor de la decisión:

decision	UX sugerida
approved	Cerrar el iframe y mostrar una confirmación de éxito.
rejected	Cerrar el iframe y mostrar un mensaje adecuado o redirigir a un flujo de soporte.
in_review	Cerrar el iframe e informar al usuario de que la verificación está en revisión y de que será notificado. El backend del integrador recibirá el resultado final por webhook.
unconfirmed	Cerrar el iframe, pero sin presentar un resultado final al usuario. El recorrido terminó y el resultado no está confirmado. Trate el webhook como fuente autorizada e informe al usuario cuando llegue.

blocked

Se emite cuando el flujo se interrumpe por motivos de seguridad.

Campo del payload	Tipo	Descripción
executionId	UUID	El identificador de ejecución.
reason	string	El motivo del bloqueo: fraud_detected, invalid_data, max_attempts_exceeded, identity_mismatch.

La página host puede mostrar un mensaje de soporte u ofrecer canales alternativos.

error

Se emite cuando un error técnico impide continuar.

Campo del payload	Tipo	Descripción
code	string	Un código de error estandarizado (consulte Códigos de error de PostMessage).
message	string	Una descripción del error legible por personas.
status	integer	Presente solo cuando el error se originó en una respuesta HTTP. El código de estado HTTP de esa respuesta.

Este evento no lleva ningún executionId. Correlaciónelo con la ejecución que su backend creó para la sesión o con el executionId recibido en el evento ready ya resuelto.

height-changed

Se emite cuando cambia la altura del contenido del iframe, con un intervalo mínimo de 200 ms entre avisos (como máximo cinco actualizaciones por segundo). Resulta útil en diseños en los que el iframe no está definido al 100% del viewport.

Campo del payload	Tipo	Descripción
height	integer	La altura del contenido en píxeles.

El iframe también emite los dos eventos siguientes.

retry: se emite cuando el usuario activa el botón de reintento en la pantalla de error. La página host puede usarlo para limpiar cualquier estado de error que haya mostrado a su alrededor en respuesta a un evento error anterior, antes de que el iframe vuelva a intentar la operación fallida.

dismissed: se emite cuando el usuario cierra una pantalla terminal, es decir, cuando es el propio usuario quien descarta la pantalla final del recorrido en lugar de cerrarla la página host. Esta es la señal que necesita una página host para cerrar su propio modal u overlay ante una salida iniciada por el usuario. Una página host que solo cierra con completed dejará un contenedor vacío en pantalla después de que el usuario descarte la pantalla terminal.

Campo del payload	Tipo	Descripción
state	string	La pantalla terminal que descartó el usuario: review, approved, rejected o unconfirmed.

Validación de origen

PostMessage es, por naturaleza, un canal abierto: cualquier ventana puede enviar mensajes a cualquier otra. La seguridad depende de una validación rigurosa en ambos lados.

Del lado del iframe, la entrega no se difunde a una lista de dominios. El iframe resuelve exactamente un origen de destino, tomado del parámetro de consulta origin de su propia URL o del referrer del documento cuando ese parámetro falta. Valida que ese origen figure en la lista de orígenes permitidos configurada para la instancia del integrador y, a continuación, envía todos los mensajes a ese único origen. Los mensajes enviados con un origen restringido son rechazados por el navegador si el destinatario está en un dominio distinto.

Un origen en HTTP simple se rechaza, salvo que sea localhost. Por lo tanto, un host de pruebas servido por HTTP no recibe ningún mensaje, y lo hace de forma silenciosa: el iframe se renderiza y el recorrido funciona, pero ningún evento PostMessage llega a la página host. Sirva los hosts de pruebas por HTTPS o pruebe contra localhost.

Del lado del integrador, la página host debe verificar la propiedad origin de cada mensaje recibido contra el dominio exacto de la instancia de Guardline. La validación por subcadena o por expresión regular es insegura (un dominio como guardline.com.br.attacker.com superaría las validaciones ingenuas). Solo se debe usar la igualdad exacta de dominio.

Comunicación del host al iframe

En la versión actual, la página host no necesita enviar comandos al iframe. El onboarding es autónomo una vez iniciado: el usuario navega por los pasos y el iframe gestiona todo el estado internamente.

Las versiones futuras admitirán comandos como reiniciar el flujo mediante programación o terminar la sesión.

Reanudación de la sesión

El onboarding se puede interrumpir por muchos motivos: el usuario cierra el navegador, pierde conectividad, navega a otra página o la página host destruye y vuelve a crear el iframe. En todos estos casos, el usuario puede retomar el proceso donde lo dejó accediendo al mismo token.

La reanudación funciona porque el backend persiste el estado de cada paso de forma individual. Cuando el iframe se carga con un token, consulta al backend el estado de la ejecución. Si la ejecución está en curso, el frontend identifica el primer paso pendiente y sitúa allí al usuario. La posición del paso se reanuda correctamente, pero el contenido de los campos no: en modo embebido, el backend elimina de la respuesta del resolutor los datos de presentación de cada paso y los campos de prellenado, de modo que los valores introducidos anteriormente no se vuelven a cargar en el formulario.

Este enfoque es crítico en el contexto del iframe. El sessionStorage del navegador está aislado por origen en los iframes cross-origin. Si la página host destruye el iframe y lo vuelve a crear (por ejemplo, porque el usuario se fue y volvió), se pierde todo el sessionStorage. El backend como fuente de verdad garantiza que la sesión sobreviva a cualquier escenario de destrucción del iframe.

Si el token ha caducado, la ejecución está en un estado terminal o el token no es válido, el iframe muestra una pantalla informativa adecuada al escenario y no intenta iniciar un flujo nuevo.

Para conocer el ciclo de vida completo de la ejecución y la semántica de los estados, consulte Execution Lifecycle en la referencia de la API.

Contrato de sesión y webhook

El contrato de todo lo que no es específico del iframe está en la referencia de la API de ONP:

• Autenticación e idempotencia
• Recorridos disponibles
• Creación de una sesión
• Sujetos vinculados (para kyc_minor y los futuros flujos de representantes de kyb)
• Opt-in de notificaciones
• Resolución del enlace (el endpoint que el iframe llama en el servidor)
• Reenvío del enlace del representante
• Ciclo de vida de la ejecución
• Consulta de una ejecución
• Webhooks (taxonomía de eventos, payload, modos de autenticación, política de reintentos)
• Polling de notificaciones
• Referencia de errores (códigos de estado HTTP y códigos de error de dominio)
• Resumen de endpoints

Las indicaciones específicas del modo embebido que figuran a continuación se aplican por encima de estos contratos.

Seguridad

Aislamiento de instancias

La arquitectura de Guardline es single-tenant. Cada integrador recibe instancias dedicadas de backend, base de datos y frontend. No hay ningún tipo de compartición de datos ni de código de aplicación entre instancias. La infraestructura subyacente (clúster de Kubernetes, red, observabilidad) es compartida, pero el aislamiento lógico se aplica en todas las capas: bases de datos separadas, procesos de aplicación separados, almacenamiento separado y credenciales separadas. El iframe de un integrador no tiene acceso a los datos de otro integrador, ni siquiera de forma indirecta.

Cabeceras HTTP de seguridad

El documento embebido es un build estático servido por nginx. La única cabecera de seguridad que define es X-Content-Type-Options: nosniff. No incluye la directiva frame-ancestors de la Content Security Policy, ni X-Frame-Options, ni Permissions-Policy, ni Referrer-Policy. No confíe en las cabeceras de respuesta del documento embebido para restringir su incrustación en frames y no espere que una Permissions-Policy conceda el acceso a los sensores: el acceso a la cámara y a los sensores de movimiento dentro del iframe lo concede el atributo allow que el integrador define en el elemento iframe.

Restringir qué páginas pueden incrustar el onboarding en un frame es un elemento de la puesta en marcha, no una cabecera de respuesta. Los orígenes padre permitidos los configura por instancia el equipo de Guardline y se aplican mediante la verificación de origen de PostMessage descrita en la sección Validación de origen: el iframe solo envía mensajes a un origen que figure en esa lista. Los cambios en la lista requieren coordinación con el equipo de Guardline.

Cookies cross-origin

El recorrido de onboarding no se autentica con cookies. La credencial del recorrido es la cabecera de solicitud X-Journey-Token, combinada con el token del enlace que va en la ruta de la URL. No se define ninguna cookie de recorrido, de modo que la política de cookies de terceros del navegador no afecta al recorrido en sí, y no se requiere ninguna configuración de dominio propio ni de cookies del lado del integrador para que el onboarding funcione en un iframe cross-origin.

Las restricciones de cookies de terceros siguen siendo relevantes para el proveedor de perfilado de device, que es una cuestión aparte. Consulte Perfilado de device (Nethone) en el Apéndice A.

Protección contra ataques

Vector de ataque	Mitigación
Clickjacking	El documento embebido no define ninguna cabecera de framing, por lo que la incrustación en frames no se bloquea a nivel de navegador. Una página que incrusta el onboarding sin figurar entre los orígenes permitidos de la instancia no recibe ningún evento PostMessage, lo que impide que una página encubierta dirija el flujo del lado de la página host.
Reutilización de tokens	Los tokens están vinculados a una única ejecución y tienen un tiempo limitado (validez del enlace de 7 días, ventana de sesión activa de 24 horas). Un token capturado da acceso únicamente a la ejecución para la que se creó.
XSS por PostMessage	Validación de origen en ambos lados. El iframe solo envía mensajes al origen configurado; la página host debe validar el origen de cada mensaje recibido.
Reutilización de webhooks	Firma HMAC con marca de tiempo sobre el cuerpo, que lleva el event_id del evento. El endpoint del integrador debe rechazar los webhooks con más de 5 minutos de antigüedad y deduplicar por el event_id del cuerpo firmado, no por el encabezado.
Enumeración de tokens	Los tokens son valores hexadecimales de 32 caracteres procedentes de una fuente criptográficamente segura (128 bits de entropía). La enumeración por fuerza bruta es computacionalmente inviable.
Man-in-the-middle	HTTPS (TLS 1.2+) es obligatorio en toda la comunicación de red: llamadas a la API, carga del iframe y entrega de webhooks. PostMessage es un mecanismo interno del navegador entre ventanas del mismo agente de usuario y no atraviesa la red, por lo que no es susceptible de interceptación a nivel de red.

Compatibilidad de navegadores

El onboarding embebido es compatible con todos los navegadores modernos. El uso de la cámara en iframes cross-origin es compatible a partir de Chrome 64+, Firefox 90+, Safari 15+ y Edge 79+. La compatibilidad móvil incluye Chrome (Android) 64+ y Safari (iOS) 15+.

El iframe requiere los siguientes atributos allow: camera (obligatorio en todas las plataformas), accelerometer, gyroscope y magnetometer (obligatorios en móvil para la detección de liveness biométrico). Sin camera, el onboarding no puede avanzar más allá de los pasos de documento o biometría. Sin los sensores de movimiento, el proveedor biométrico puede funcionar en modo degradado en móvil.

Para consultar matrices detalladas de compatibilidad de navegadores, notas sobre dispositivos antiguos (iOS 14) y el comportamiento de los proveedores externos, consulte el Apéndice A: detalles de compatibilidad de navegadores.

Códigos de error de PostMessage

Los siguientes códigos de error se pueden emitir mediante el evento PostMessage error. Representan condiciones técnicas que impiden que el onboarding avance dentro del iframe. Para los códigos de error de nivel HTTP que devuelve la API, consulte la Error Reference en la referencia de la API.

Código	Descripción	Acción sugerida
camera_denied	El usuario denegó el acceso a la cámara cuando el navegador se lo solicitó.	Muestre un mensaje que explique que el acceso a la cámara es obligatorio e indique al usuario cómo concederlo en los ajustes del navegador.
camera_not_found	No se detectó ninguna cámara en el dispositivo.	Muestre un mensaje que sugiera al usuario cambiar a un dispositivo con cámara.
camera_play_failed	Se obtuvo el stream de la cámara, pero la reproducción en el elemento de vídeo no pudo iniciarse.	Muestre un mensaje de error y permita que el usuario reintente el paso. Si persiste, sugiera cerrar otras aplicaciones o pestañas que puedan estar ocupando la cámara.
device_unsupported	El dispositivo o el navegador no admite alguna capacidad que requiere el paso actual.	Muestre un mensaje que sugiera al usuario cambiar a un navegador o un dispositivo compatible. Consulte el Apéndice A: detalles de compatibilidad de navegadores.
permission_not_granted	El iframe no tiene el atributo allow necesario para la cámara. Se trata de un error de configuración del lado del integrador.	Verifique que el elemento iframe incluya allow="camera".
api_unavailable	No se puede acceder a la API de Guardline.	Muestre un mensaje de error genérico y sugiera reintentar. Si persiste, contacte con el soporte de Guardline.
sdk_load_failed	El SDK de verificación biométrica no se pudo cargar (problema de red o fallo de la CDN).	Muestre un mensaje de error y sugiera reintentar. El usuario puede volver a intentar el paso.
load_error	Un recurso que requiere el paso actual no se pudo cargar.	Muestre un mensaje de error y permita que el usuario reintente el paso.
token_invalid	El token de sesión está mal formado o no existe.	Muestre un mensaje que informe al usuario de que el enlace no es válido. El integrador debe generar una sesión nueva.
token_expired	El token de sesión ha caducado.	Muestre un mensaje que informe al usuario de que el enlace ha caducado. El integrador debe generar una sesión nueva.
session_completed	La ejecución asociada a este token ya está en estado rejected. Este código no se emite para otras decisiones finales.	Muestre un mensaje que informe al usuario de que el onboarding ya se ha finalizado.
session_cancelled	La sesión se canceló antes de que se completara el recorrido.	Muestre un mensaje que informe al usuario de que la sesión ya no está activa. El integrador debe generar una sesión nueva si el usuario necesita volver a intentarlo.
session_blocked	La sesión se bloqueó por motivos de seguridad.	Muestre un mensaje y dirija al usuario a los canales de soporte.

Resolución de problemas

Síntoma	Causa	Solución
No se reciben los eventos PostMessage	Falta ?origin= en la URL del iframe, la página host filtra por un valor de source equivocado o el origen permitido está mal configurado.	Confirme que la embed_url lleva ?origin= con el origen exacto de su página. Revise que el listener de eventos filtre por el valor de source de su instancia (<slug>-onboarding). Verifique que los orígenes permitidos coinciden con el origen exacto de su página host (protocolo, dominio y puerto).
La cámara no funciona en el iframe	Al elemento iframe le falta allow="camera".	Añada allow="camera" al iframe. En móvil, incluya también accelerometer; gyroscope; magnetometer.
La biometría falla en móvil	Los permisos de los sensores de movimiento no están declarados en el iframe.	Añada accelerometer; gyroscope; magnetometer al atributo allow del iframe.
La aceptación de los términos siempre se registra sin ubicación	Al elemento iframe le falta allow="geolocation", por lo que el navegador deniega la solicitud sin mostrar el aviso.	Añada geolocation al atributo allow del iframe. El recorrido nunca se bloquea por esto: una ubicación rechazada o no disponible se registra como tal en la evidencia de consentimiento.
El usuario pierde el progreso tras salir de la página	La página host destruyó y volvió a crear el iframe, perdiendo el sessionStorage.	Comportamiento esperado. El backend persiste todos los datos de los pasos. La sesión se reanuda automáticamente desde el último paso completado con el mismo token.
No llegan los webhooks	El endpoint no es accesible, devuelve un código distinto de 2xx o la verificación de firma rechaza payloads válidos.	Compruebe la accesibilidad del endpoint por HTTPS. Revise los registros en el panel administrativo de Guardline. Verifique que la firma se calcula sobre timestamp + "." + body.

Flujo de datos y privacidad

Los datos centrales del onboarding (nombre, CPF, datos de contacto, metadatos del documento e imágenes del documento) se almacenan en los sistemas de Guardline y se cifran en reposo. Las capturas biométricas las procesa iProov y Guardline no las conserva. Las huellas de device las procesa Nethone y Guardline no las conserva. El integrador es el responsable del tratamiento según la LGPD y Guardline actúa como encargado del tratamiento. Los plazos de retención, la base legal y los términos del DPA se definen por contrato.

Para consultar el diagrama completo de residencia de los datos, la tabla de retención y la matriz de responsabilidades de cumplimiento, consulte el Apéndice B: detalles del flujo de datos y del cumplimiento.

Rendimiento

Un flujo KYC típico de 6 pasos se completa en 3 a 5 minutos de interacción del usuario. Las operaciones del backend (resolución del token, envío de pasos, motor de decisión) tardan menos de un segundo. El paso de verificación biométrica (de 5 a 15 s) es el más variable y depende de la latencia de red hacia los servidores de iProov y del hardware de la cámara del dispositivo.

Estas cifras son una referencia de ingeniería, no compromisos de SLA. Los SLA de rendimiento se definen por contrato. Para consultar métricas P95 detalladas con su contexto de medición, consulte el Apéndice C: detalles de rendimiento.

Lista de verificación de la integración

Use esta lista de verificación para validar su integración con iframe antes de pasar a producción.

Integración del backend

• El endpoint de creación de sesiones incluye surface_hint: "embed" en las sesiones renderizadas en iframe.
• El endpoint de webhook está implementado, es accesible por HTTPS y responde con 2xx.
• La verificación de la firma del webhook está implementada usando el secreto compartido.
• La idempotencia del webhook está implementada usando el event_id del cuerpo firmado, con execution_id + event_sequence como alternativa cuando la entrega no lo trae; el encabezado X-Guardline-Event-ID sigue llegando con el mismo valor, pero no está cubierto por la firma.
• La validación de la marca de tiempo del webhook rechaza los eventos con más de 5 minutos de antigüedad.
• El polling del estado de la sesión está implementado como alternativa para los webhooks perdidos.
• La clave de API se almacena de forma segura (variable de entorno, gestor de secretos), no en el código fuente.

Integración del frontend

• El src del iframe es la embed_url con ?origin= añadido, con el origen exacto de la página host (esquema + host + puerto). Sin él no se emite ningún evento PostMessage.
• El elemento iframe incluye allow="camera; geolocation; accelerometer; gyroscope; magnetometer".
• El iframe no incluye el atributo sandbox.
• El listener de PostMessage filtra por el valor de source de su instancia (<slug>-onboarding), confirmado con el equipo de Guardline durante la puesta en marcha.
• La validación de origen de PostMessage comprueba el dominio exacto de Guardline (sin coincidencias por subcadena ni por expresión regular).
• Se gestiona el evento ready (ocultar el indicador de carga y mostrar el iframe).
• Se gestiona el evento completed con ramificación según el valor de decision: approved (confirmación), rejected (mensaje adecuado), in_review (informar al usuario de la revisión pendiente), unconfirmed (no mostrar ningún resultado final y esperar el webhook).
• Se gestiona el evento error (mostrar un mensaje comprensible para el usuario).
• Se gestiona el evento blocked (mostrar información de soporte).

Pruebas

• El flujo de onboarding de extremo a extremo funciona en Chrome, Safari y Firefox (escritorio).
• El flujo de onboarding de extremo a extremo funciona en Chrome (Android) y Safari (iOS 15+).
• El acceso a la cámara funciona dentro del iframe en todos los navegadores objetivo.
• La verificación biométrica se completa correctamente dentro del iframe.
• La reanudación de la sesión funciona: destruya el iframe, vuelva a crearlo con el mismo token y verifique que el flujo se reanuda en el paso correcto.
• Un token caducado muestra la pantalla informativa adecuada.
• Un token no válido muestra la pantalla informativa adecuada.
• La entrega de los webhooks está confirmada en el panel administrativo de Guardline.
• La verificación de la firma del webhook rechaza correctamente los payloads manipulados.

Entorno

• Los orígenes permitidos están configurados para sus dominios de producción (necesario para la validación de origen de PostMessage).
• Los certificados SSL son válidos y no están próximos a caducar.
• La clave de API del entorno de producción está aprovisionada y almacenada de forma segura.
• El secreto compartido del webhook está almacenado de forma segura.

Para obtener acceso al sandbox y soporte de pruebas, contacte con el equipo técnico de Guardline.

---

Apéndice A: detalles de compatibilidad de navegadores

Las versiones de navegador, las estadísticas de dispositivos, las versiones de SDK y los tiempos límite de los proveedores que figuran en este apéndice provienen de los fabricantes de los navegadores, de la plataforma y de los proveedores de verificación. El producto no realiza detección de capacidades (feature detection) ni verifica ninguno de esos valores en tiempo de ejecución, de modo que conviene tratarlos como orientación de los proveedores y no como un comportamiento garantizado por el onboarding.

Navegadores de escritorio

Navegador	Versión mínima	Cámara en iframe	Notas
Chrome	64+ (2018)	Sí	Compatibilidad total con Permissions Policy y con el acceso a la cámara en iframes cross-origin.
Firefox	90+ (2021)	Sí	Compatibilidad total. La Enhanced Tracking Protection puede afectar al perfilado de device de Nethone.
Safari	15+ (2021)	Sí	Compatibilidad total. La Intelligent Tracking Prevention puede afectar al perfilado de device de Nethone.
Edge	79+ (2020)	Sí	Basado en Chromium. Mismo comportamiento que Chrome.

Navegadores móviles

Navegador	Versión mínima	Cámara en iframe	Notas
Chrome (Android)	64+	Sí	Compatibilidad total.
Safari (iOS)	15+	Sí	Compatibilidad total con la cámara en iframes cross-origin.
Safari (iOS)	14 y anteriores	No	No admite la cámara en iframes cross-origin. El proveedor biométrico ofrece un patrón puente que abre la captura en una pestaña nueva y devuelve el resultado mediante PostMessage. Estas versiones representan menos del 5% de los dispositivos iOS activos y están en descenso.
Samsung Internet	12+	Sí	Basado en Chromium. Mismo comportamiento que Chrome.

Detalle de los permisos del iframe

Permiso	Obligatorio	Propósito	Impacto si falta
camera	Sí	Captura de documentos y verificación biométrica.	El onboarding no puede avanzar más allá de los pasos de documento o biometría. El iframe muestra un mensaje de error.
accelerometer	Solo en móvil	Detección de liveness en dispositivos móviles.	El proveedor biométrico puede funcionar en modo degradado (sin detección de movimiento) o fallar en algunos dispositivos.
gyroscope	Solo en móvil	Detección de liveness en dispositivos móviles.	Igual que accelerometer.
magnetometer	Solo en móvil	Detección de liveness en dispositivos móviles.	Igual que accelerometer.

Verificación biométrica (iProov)

El SDK web de iProov (versión 5.4.3+) admite su funcionamiento dentro de iframes. El SDK se comunica con los servidores de iProov usando sus propios tokens obtenidos del backend de Guardline y no depende de cookies de terceros ni de almacenamiento compartido.

En dispositivos móviles, iProov usa los sensores de movimiento para la detección de liveness (verificar que un dispositivo está siendo sostenido por una persona real). El iframe debe declarar los permisos de accelerometer, gyroscope y magnetometer. Sin estas declaraciones, iProov puede funcionar en modo degradado (sin detección de movimiento) o fallar.

Perfilado de device (Nethone)

Nethone recopila información del device (fingerprint, patrones de escritura, señales de fraude) mediante un agente JavaScript cargado desde una CDN externa. Este agente funciona con cookies de terceros para el seguimiento del device entre sesiones.

En un contexto de iframe cross-origin, los navegadores con políticas de privacidad restrictivas pueden limitar la funcionalidad de Nethone:

Navegador	Política	Impacto
Safari	Intelligent Tracking Prevention (ITP)	Cookies de terceros bloqueadas. La huella del device queda reducida a la sesión actual.
Firefox	Enhanced Tracking Protection (ETP)	Cookies de terceros bloqueadas en modo estricto. Impacto similar al de Safari.
Chrome	Configurable por el usuario	Cookies de terceros permitidas por defecto. Los usuarios pueden desactivarlas.

El onboarding está diseñado con degradación elegante para Nethone: si el script no se carga, si el perfilado no se completa dentro del tiempo límite (5 segundos) o si las cookies están bloqueadas, el flujo continúa con normalidad. El análisis de riesgo pierde la dimensión de inteligencia sobre el device, pero todas las demás verificaciones (biometría, verificación documental, validación en burós) funcionan de forma independiente.

En escenarios en los que el perfilado del device sea crítico, ejecutar Nethone en el dominio del integrador (contexto de primera parte, sin restricciones de cookies de terceros) y comunicar el resultado al iframe mediante PostMessage es una alternativa admitida. Contacte con el equipo de Guardline para esta configuración.

---

Apéndice B: detalles del flujo de datos y del cumplimiento

Dónde residen los datos

Retención de datos

Tipo de dato	Ubicación de almacenamiento	Retención	Cifrado en reposo
Token de sesión	Base de datos de Guardline	Hasta su caducidad o su finalización	Sí
Datos personales (nombre, CPF, correo electrónico)	Base de datos de Guardline	Según la política de retención de datos (configurable)	Sí
Imágenes de documentos	Almacenamiento de objetos de Guardline	Según la política de retención de datos (configurable)	Sí
Datos biométricos	Procesados por iProov, no almacenados por Guardline	No se conservan	N/A
Fingerprint del device	Procesado por Nethone, no almacenado por Guardline	No se conserva	N/A
Resultados de las decisiones	Base de datos de Guardline	Traza de auditoría inmutable	Sí
Payloads de webhook	Base de datos de Guardline (registro de entregas)	90 días	Sí

Matriz de responsabilidades de cumplimiento

Área	Lo que aporta Guardline (técnico)	Contractual o configurable	Responsabilidad del integrador
LGPD	Los datos se recopilan con una finalidad específica y documentada (verificación de identidad).	La duración de la retención, la base legal del tratamiento y el DPA (Data Processing Agreement) se definen por contrato. La retención de los datos de onboarding es un compromiso contractual y la plataforma no la aplica de forma automática.	El integrador es el responsable del tratamiento y debe garantizar una base lícita para iniciar el onboarding (por ejemplo, el consentimiento del usuario o la necesidad contractual). Guardline actúa como encargado del tratamiento.
Residencia de los datos	La plataforma admite el despliegue en regiones geográficas concretas o en on-premise.	La selección de región y el despliegue on-premise están sujetos a acuerdo contractual.	El integrador debe definir los requisitos de residencia en función de sus propias obligaciones regulatorias.
Traza de auditoría	Todas las operaciones se registran en un log de auditoría inmutable, accesible desde el panel administrativo.	El período de retención de los logs y el formato de exportación son configurables por contrato.	El integrador es responsable de consumir y archivar los logs de auditoría según lo exijan sus propias políticas de cumplimiento.
Minimización de datos	Solo se recopilan los datos necesarios para los pasos configurados en el flujo.	La configuración del flujo (qué pasos están activos, qué campos son obligatorios) se define durante la puesta en marcha.	El integrador controla qué datos de prellenado envía. Enviar datos personales innecesarios en la solicitud es responsabilidad del integrador.
Derecho de supresión	La plataforma admite técnicamente las solicitudes de eliminación de datos.	Los procedimientos de eliminación y sus SLA se definen por contrato.	El integrador debe trasladar a Guardline las solicitudes de supresión de los titulares de los datos y confirmar su cumplimiento a la parte solicitante.

---

Apéndice C: detalles de rendimiento

Los valores que figuran a continuación son mediciones P95 observadas en la región de Europa en condiciones de carga normales. El rendimiento real varía en función de la infraestructura del integrador, de la calidad de red del usuario final y de las capacidades del dispositivo. Estas cifras se ofrecen como referencia de ingeniería, no como compromisos de SLA. Los SLA de rendimiento se definen por contrato.

Métrica	P95	Contexto de medición
Carga inicial del iframe	< 2s	Banda ancha estándar (10 Mbps+). Incluye el bundle de la SPA (comprimido con gzip), las fuentes y la resolución del token. Los recursos en caché reducen las cargas posteriores a < 500ms.
Resolución del token	< 200ms	Solo el tiempo de procesamiento en el backend (consulta a la base de datos más ensamblaje de la configuración del flujo). No incluye el viaje de ida y vuelta de red desde el cliente.
Envío de un paso	< 300ms	Solo el tiempo de procesamiento en el backend (validación más persistencia).
Captura del documento (inicio de la cámara)	1-3s	Varía según el hardware de la cámara del dispositivo y el navegador. La primera captura tras cargar la página es más lenta por la solicitud de permiso de cámara y la inicialización del hardware.
Verificación biométrica	5-15s	De extremo a extremo, incluyendo la inicialización del SDK de iProov, la captura y el procesamiento en el servidor. Depende en gran medida de la latencia de red hacia los servidores de iProov.
Motor de decisión	< 500ms	Solo el tiempo de procesamiento en el backend. Opera exclusivamente sobre datos ya recopilados durante los pasos del onboarding. En esta fase no hay llamadas a proveedores externos.
Entrega de PostMessage	< 1ms	Interno del navegador, en el mismo dispositivo. No es una operación de red.
Primer intento de entrega del webhook	< 5s	Tiempo desde la decisión hasta la solicitud HTTP al endpoint del integrador. No incluye el tiempo de procesamiento del integrador.

Factores que afectan a la experiencia del usuario final:

• Calidad de la red: la carga de documentos y la verificación biométrica son los pasos que más ancho de banda consumen. En conexiones por debajo de 3 Mbps, los tiempos de captura y de carga aumentan de forma significativa.
• Calidad de la cámara del dispositivo: las cámaras de menor calidad pueden requerir varios intentos de captura para la verificación documental.
• Número de pasos del flujo: cada paso añade tiempo de navegación del usuario. Un flujo KYC de 6 pasos se completa normalmente en 3 a 5 minutos de interacción del usuario.
• Navegador: los navegadores modernos (Chrome 90+, Safari 16+, Firefox 100+) ofrecen el mejor rendimiento para el acceso a la cámara y el renderizado WebGL que usa el SDK biométrico.