Cómo reanudar las sesiones de incorporación de KYB con un token SDK
Last updated: September 15, 2026
Guía de integración de AiPrise — incorporación empresarial (KYB)
Descripción general
Cuando un solicitante abandona a mitad del proceso de incorporación empresarial (KYB) y vuelve más tarde, hay dos formas de restaurar su progreso guardado:
OTP por correo electrónico: el solicitante vuelve a introducir su correo electrónico, recibe un código de un solo uso y sus datos guardados se restauran después de verificarlo.
Token del SDK de incorporación: tu backend genera un token de corta duración para la sesión y lo pasa al SDK. Los datos guardados del solicitante se restauran automáticamente — sin paso de OTP.
La vía del token es una mejora fluida sobre la vía de OTP, no un reemplazo. Si falta el token, ha caducado o no es válido, el solicitante simplemente vuelve al flujo de OTP — nunca se trata como un error.
Requisitos previos
La función Guardar progreso debe estar habilitada para tu cuenta. Contacta con AiPrise para activarla (esto también controla si aparece el botón "Guardar progreso" en la interfaz de incorporación).
Necesitas tu clave de API de AiPrise (la misma
x-api-keyque usas para otras llamadas de servidor a servidor).La sesión de verificación debe pertenecer a tu cuenta.
Si utilizas el SDK web de AiPrise, necesitas aiprise-web-sdk v2.1.5 o posterior (la versión que añadió el onboarding-session-token atributo).
Paso 1 — Generar el token (solo del lado del servidor)
Llama a esto desde tu backend, nunca desde el navegador — requiere tu clave de API.
GET /v1/verify/get_onboarding_sdk_token/<verification_session_id>
Header: x-api-key: <your API key>
Éxito (200):
{
"onboarding_sdk_token": "<JWT>",
"success": true
}
Errores:
Estado | Mensaje | Significado |
|---|---|---|
400 |
| La sesión no existe o pertenece a otra cuenta (la respuesta es deliberadamente idéntica en ambos casos, por lo que no se pueden sondear los ID de sesión) |
401 |
| No hay encabezado de |
403 |
| La clave es válida, pero no está asociada a una cuenta |
Límites de frecuencia: 60/minuto, 600/hora, 3.000/día por clave.
Paso 2 — Pasar el token al SDK web de AiPrise
Requiere aiprise-web-sdk v2.1.5 o posterior.
Tanto <aiprise-frame> como <aiprise-button> aceptan el token mediante el atributo onboarding-session-token . El token solo se utiliza al reanudar una sesión existente, así que establécelo siempre junto con session-id (la sesión de verificación para la que generaste el token en el paso 1).
HTML / marco incrustado:
<aiprise-frame
mode="PRODUCTION"
template-id="YOUR_TEMPLATE_ID"
session-id="VERIFICATION_SESSION_ID"
onboarding-session-token="TOKEN_FROM_STEP_1"
></aiprise-frame>
Botón + modal:
<aiprise-button
mode="PRODUCTION"
template-id="YOUR_TEMPLATE_ID"
session-id="VERIFICATION_SESSION_ID"
onboarding-session-token="TOKEN_FROM_STEP_1"
></aiprise-button>
JavaScript simple (dinámico):
// 1. Fetch a fresh token from YOUR backend (which calls
// /v1/verify/get_onboarding_sdk_token with your API key)
const { onboarding_sdk_token } = await fetch("/your-backend/onboarding-token/" + sessionId)
.then((res) => res.json());
// 2. Render the frame with both session-id and the token
const frame = document.createElement("aiprise-frame");
frame.setAttribute("mode", "PRODUCTION");
frame.setAttribute("template-id", "YOUR_TEMPLATE_ID");
frame.setAttribute("session-id", sessionId);
frame.setAttribute("onboarding-session-token", onboarding_sdk_token);
document.getElementById("container").appendChild(frame);
En React/Vue, establece los mismos atributos en el elemento personalizado (consulta los ejemplos de frameworks en docs.aiprise.com para la configuración general del SDK).
Información útil:
Como el token caduca después de 5 minutos, obténlo de tu backend justo antes de representar el componente — no al iniciar la aplicación.
El SDK pasa el token al formulario de verificación alojado en el fragmento de la URL (
#session_token=...), por lo que nunca aparece en cadenas de consulta, registros del servidor ni encabezados de referencia. A continuación, el formulario lo presenta a AiPrise como un token portador.Si se omite el token, caduca o no es válido, el componente sigue funcionando — el solicitante simplemente realiza el flujo de reanudación mediante OTP por correo electrónico.
El evento
aiprise:resumedse activa en el componente cuando se vuelve a abrir una sesión existente.
Paso 3 — Lo que ve el solicitante
No se requiere nada más por tu parte. Cuando el formulario se abre con un token válido, AiPrise restaura automáticamente el progreso guardado del solicitante — vuelve al punto en el que lo dejó, sin paso de OTP.
La reanudación automática ocurre cuando se cumplen todas estas condiciones:
La función Guardar progreso está habilitada para tu cuenta.
La sesión realmente tiene progreso guardado (no es la primera apertura).
El token es válido, no ha caducado y se generó para esta sesión — un token generado para una sesión nunca puede desbloquear otra.
Si alguna de estas condiciones falla, el solicitante simplemente ve la pantalla de reanudación por correo electrónico/OTP. Sus datos guardados nunca se pierden — solo se omite el acceso directo.
Propiedades y reglas del token
Formato: JWT (HS256) con las declaraciones
company_id,verification_session_id,type,iat,exp.Duración: 5 minutos. El token solo debe sobrevivir a la transferencia de tu backend → frontend → inicio del SDK, no a todo el flujo de incorporación. Genera un token nuevo en cada carga de página; no lo almacenes en caché ni lo guardes.
Ámbito: acceso de lectura al progreso guardado de exactamente una sesión. Intencionadamente, no es intercambiable con ningún otro tipo de token de AiPrise.
Nunca expongas tu clave de API al navegador. Solo el token generado llega al frontend.
Solución de problemas: el solicitante sigue viendo la pantalla de OTP
Causa | Explicación |
|---|---|
Primera apertura de la sesión | Todavía no hay nada que reanudar — es lo esperado |
Token caducado | Pasaron más de 5 minutos entre la generación del token y su envío por el SDK. Genéralo al cargar la página, no con antelación |
El ID de sesión no coincide | El token se generó para una sesión distinta de aquella que abrió el formulario |
Función no habilitada | Guardar progreso no está habilitado para tu cuenta — contacta con AiPrise para activarlo |
No hay progreso guardado | El solicitante nunca guardó nada para esta sesión |
En todos estos casos, el solicitante aún puede reanudar mediante el flujo de OTP por correo electrónico. Si la pantalla de OTP sigue apareciendo incluso con un token nuevo y correctamente limitado, contacta con el soporte de AiPrise e indica el ID de sesión de verificación; podremos decirte qué comprobación falló.