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:

  1. 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.

  2. 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-key que 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

INVALID_SESSION_ID

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

Missing API key

No hay encabezado de x-api-key , o la clave es desconocida / corresponde al medio ambiente incorrecto

403

No company associated with API key

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:resumed se 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:

  1. La función Guardar progreso está habilitada para tu cuenta.

  2. La sesión realmente tiene progreso guardado (no es la primera apertura).

  3. 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ó.