> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK JavaScript de verificación de identidad: KYC web

> SDK JavaScript de Didit para KYC, KYB, AML y liveness: integrado, redirección o iframe. Desde $0.33 por KYC completo, $10 gratis/mes, sin contratos.



Prompt de integración del SDK de JavaScript
        Copiar el prompt al portapapeles



      
      

\<pre>

\`Integrate Didit identity verification into my web application using the JavaScript SDK.

\## Setup
Install: npm install @didit-protocol/sdk-web
Or CDN: <script src="https://unpkg.com/@didit-protocol/sdk-web/dist/didit-sdk.umd.min.js"></script>

\## Integration Flow
1\. (Option A — UniLink) Use a fixed UniLink URL from the Didit Console (no backend needed)
2\. (Option B — API session) Backend creates a session via POST /v3/session/ → 201 response includes "url"
3\. Frontend calls DiditSdk.shared.startVerification({ url }) — the SDK opens a modal (or inline if embedded mode)
4\. On completion, the SDK invokes DiditSdk.shared.onComplete(result) with type "completed" | "cancelled" | "failed"
5\. Backend receives full signed decision via webhook (status.updated)

\## Frontend Code — Vanilla JS / TypeScript
import { DiditSdk } from '@didit-protocol/sdk-web';

DiditSdk.shared.onComplete = (result) => {
switch (result.type) {
case 'completed':
  // result.session.status: "Approved" | "Pending" | "Declined"
  console.log('Done:', result.session.sessionId, result.session.status);
  break;
case 'cancelled':
  console.log('User cancelled');
  break;
case 'failed':
  console.error('Failed:', result.error.type, result.error.message);
  break;
}
};

// Modal mode (default)
DiditSdk.shared.startVerification({
url: 'https://verify.didit.me/session/SESSION_TOKEN' // from backend OR UniLink
});

// Inline / embedded mode
DiditSdk.shared.startVerification({
url: 'https://verify.didit.me/session/SESSION_TOKEN',
configuration: { embedded: true, embeddedContainerId: 'didit-container' }
});

\## Frontend Code — React
function VerifyButton({ userId }) {
const [loading, setLoading] = useState(false);

async function handleVerify() {
setLoading(true);
const res = await fetch('/api/create-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ user_id: userId })
});
const { url } = await res.json(); // OpenAPI field is named "url"

const { DiditSdk } = await import('@didit-protocol/sdk-web');
DiditSdk.shared.onComplete = (result) => {
  if (result.type === 'completed') {
    // update UI; final, signed result arrives on backend via webhook
  }
  setLoading(false);
};
DiditSdk.shared.startVerification({ url });
}

return <button onClick={handleVerify} disabled={loading}>Verify Identity</button>;
}

\## Backend: Create Session
POST https://verification.didit.me/v3/session/
Headers: { "x-api-key": DIDIT_API_KEY, "Content-Type": "application/json" }
Body: { "workflow_id": DIDIT_WORKFLOW_ID, "callback": "https://myapp.com/done", "vendor_data": userId }
Returns 201 (all 10 fields, per OpenAPI):
\{
"session_id": "uuid",
"session_number": 43762,
"session_token": "3FaJ9wLqX2Mz",   // 12-char URL-safe token; valid until the session expires
"url": "https://verify.didit.me/session/3FaJ9wLqX2Mz",
"vendor_data": "userId",
"metadata": null,
"status": "Not Started",
"workflow_id": "uuid",
"workflow_version": 3,
"callback": "https://myapp.com/done"
}
Pass the "url" field to DiditSdk.shared.startVerification({ url }) — never build the URL by hand.
(If the request sets "language", the URL gains a language segment: https://verify.didit.me/es/session/...)

\## SDK Surface (singleton — DiditSdk.shared)
Methods:  startVerification(options), close(), destroy()
Callbacks: onComplete(result), onStateChange(state, error?), onEvent(event)
State enum: 'idle' | 'loading' | 'ready' | 'error'

\## Rate Limits
600 session-create requests per minute per API key (falls back to bearer token, then client IP), plus a shared budget of 300 write (POST/PATCH/DELETE) requests per minute across all endpoints — the 300/min budget is exhausted first. Exceeding either returns HTTP 429 with Retry-After.

\## Environment Variables
\- DIDIT_API_KEY — backend only (Didit Console > API & Webhooks)
\- DIDIT_WORKFLOW_ID — backend only (Didit Console > Workflows)
\- Never expose the API key on the frontend — the session_token embedded in "url" is the only credential the SDK needs. It grants access to that one session's flow (valid until the session expires), so don't log or share it either.

\## Docs
\- JavaScript SDK: https://docs.didit.me/integration/web-sdks/javascript-sdk
\- Create Session API: https://docs.didit.me/sessions-api/create-session
\- Webhooks: https://docs.didit.me/integration/webhooks`

\</pre>



      
      

Pegar en

El SDK de JavaScript de Didit te permite integrar la verificación en tu aplicación web mediante código, con control total sobre la experiencia del usuario.***## Funciones- **API sencilla**: patrón singleton con métodos fáciles de usar
- **Integración flexible**: usa directamente la URL de UniLink o crea sesiones desde el backend
- **Adaptable**: funciona en navegadores de escritorio y móviles
- **Personalizable**: opciones de configuración para el estilo y el comportamiento
- **Varios formatos**: builds ESM, CommonJS y UMD
- **Compatibilidad con TypeScript**: incluye definiciones de tipos completas
- **Modos modal e integrado**: elige entre una superposición modal o la inserción integrada en la página
- **Callbacks de eventos**: eventos en tiempo real sobre el progreso de la verificación (iniciada, paso completado, finalizada)
- **Gestión del estado**: observa el estado del SDK para crear una interfaz personalizada***## Instalación### NPM/Yarn```bash theme={null}
npm install @didit-protocol/sdk-web
# or
yarn add @didit-protocol/sdk-web
```### CDN (UMD)```html theme={null}
<script src="https://unpkg.com/@didit-protocol/sdk-web/dist/didit-sdk.umd.min.js"></script>
```> [!NOTE]
>
> La última versión publicada en npm es `0.5.1`.
> `0.5.0` añadió `DiditSdk.shared.submitEvent()` (consulta [Enviar eventos](#enviar-eventos)), y `0.5.1` permite que el flujo alojado solicite el ID del usuario a una wallet de identidad digital dentro del SDK y mantiene un lanzamiento fallido en el estado `error` con su `errorMessage`.
> `0.4.0` añadió las opciones de cámara que ya ofrecen los SDK nativos, incluida `defaultLivenessCamera`, que abre la captura facial con la cámara trasera (consulta [Opciones de cámara](#opciones-de-cámara)).### Comprobar la versión instaladaTu gestor de paquetes sigue siendo la fuente de referencia para la versión instalada:```bash theme={null}
npm list @didit-protocol/sdk-web
npm view @didit-protocol/sdk-web version
```También puedes consultar la exportación en tiempo de ejecución:```typescript theme={null}
const { SDK_VERSION } = await import('@didit-protocol/sdk-web');

console.log(SDK_VERSION);
```A partir de `0.3.1`, esta exportación se genera a partir de la versión del paquete en todos los formatos de JavaScript (ESM, CommonJS, UMD, UMD minificado) y en la declaración de TypeScript, por lo que siempre coincide con la versión instalada.`0.3.0` y las versiones anteriores indican `0.2.1` en esta exportación, sea cual sea la versión instalada. En esas versiones, usa `npm list` o tu archivo de bloqueo (lockfile).***## JavaScript puro### Módulos ES / TypeScript```typescript theme={null}
import { DiditSdk } from '@didit-protocol/sdk-web';

// Set up completion callback
DiditSdk.shared.onComplete = (result) => {
  switch (result.type) {
    case 'completed':
      console.log('Verification completed!');
      console.log('Session ID:', result.session?.sessionId);
      console.log('Status:', result.session?.status);
      break;
    case 'cancelled':
      console.log('User cancelled verification');
      break;
    case 'failed':
      console.error('Verification failed:', result.error?.message);
      break;
  }
};

// Start verification with the `url` returned by POST /v3/session/ (or your UniLink)
DiditSdk.shared.startVerification({
  url: 'https://verify.didit.me/session/3FaJ9wLqX2Mz'
});
```### Etiqueta de script (UMD)```html theme={null}
<script src="https://unpkg.com/@didit-protocol/sdk-web/dist/didit-sdk.umd.min.js"></script>
<script>
  const { DiditSdk } = DiditSDK;

  DiditSdk.shared.onComplete = (result) => {
    if (result.type === 'completed') {
      alert('Verification completed: ' + result.session.status);
    }
  };

  function startVerification() {
    DiditSdk.shared.startVerification({
      // You can get this link by clicking on "copy link" in the workflows view
      url: 'https://verify.didit.me/u/WORKFLOW_ID_IN_BASE_64'
    });
  }
</script>

<button onclick="startVerification()">Verify Identity</button>
```***## Ejemplos por framework> [card] [Ejemplos del SDK web](https://github.com/didit-protocol/sdk-web-examples)
>
> React, Angular, Svelte, Next.js, Nuxt, Vue y más, con ejemplos y documentación para cada framework.***## Métodos de integraciónHay dos formas de integrar el SDK:### Método 1: URL de UniLink (la más sencilla)Usa directamente la URL de UniLink de tu flujo de verificación (workflow) desde Didit Console. No necesitas backend.```typescript theme={null}
DiditSdk.shared.startVerification({
  // You can get this link by clicking on "copy link" in the workflows view
  url: 'https://verify.didit.me/u/WORKFLOW_ID_IN_BASE_64'
});
```Obtén tu URL de UniLink en la [Didit Console](https://business.didit.me) → tu flujo → Copy Link.**El session\_id generado se te enviará mediante un evento.**
**[Consulta aquí la referencia de eventos](#referencia-de-eventos)**### Método 2: sesión desde el backend (recomendado para producción)Tu backend crea una sesión mediante la API de Didit y devuelve la URL de la página de verificación alojada. Así controlas `vendor_data`, el `callback` por sesión y `metadata`, y puedes crear sesiones antes de que el usuario llegue al frontend.Más información en la [referencia de la API Create Session](https://docs.didit.me/es/sessions-api/create-session.md).**Backend (Node.js / Express)**```javascript theme={null}
import express from 'express';
const app = express();
app.use(express.json());

app.post('/api/create-session', async (req, res) => {
  const response = await fetch('https://verification.didit.me/v3/session/', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DIDIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: req.body.userId,             // links the session to your user
      callback: 'https://yourapp.com/verified', // optional — overrides workflow default
    }),
  });

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  // 201 response fields (per OpenAPI): session_id, session_number, session_token, url,
  // vendor_data, metadata, status, workflow_id, workflow_version, callback
  const session = await response.json();
  res.json({ session_id: session.session_id, url: session.url });
});
```**Frontend**```typescript theme={null}
import { DiditSdk } from '@didit-protocol/sdk-web';

const res = await fetch('/api/create-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId: 'user-123' }),
});
const { url } = await res.json();

DiditSdk.shared.startVerification({
  url,
  configuration: {
    loggingEnabled: true,
  },
});
```> [!NOTE]
>
> El campo de la respuesta de creación de sesión se llama `url` (consulta el [esquema OpenAPI de Create Session](https://docs.didit.me/es/sessions-api/create-session.md)). Pásalo directamente a `startVerification({ url })`.***## Configuración| Opción | Tipo | Valor predeterminado | Descripción |
| - | - | - | - |
| `loggingEnabled` | `boolean` | `false` | Activa el registro del SDK para depuración |
| `containerElement` | `HTMLElement` | `document.body` | Elemento contenedor personalizado donde se monta el modal |
| `zIndex` | `number` | `9999` | Z-index de la superposición modal |
| `showCloseButton` | `boolean` | `true` | Muestra el botón de cierre en el modal |
| `showExitConfirmation` | `boolean` | `true` | Muestra un diálogo de confirmación de salida al cerrar |
| `closeModalOnComplete` | `boolean` | `false` | Cierra automáticamente el modal cuando se completa la verificación |
| `embedded` | `boolean` | `false` | Muestra la verificación integrada en la página en lugar de en una superposición modal |
| `embeddedContainerId` | `string` | — | ID del elemento contenedor para el modo integrado (obligatorio cuando `embedded` es `true`) |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Cámara con la que se abre primero la captura del documento. Consulta [Opciones de cámara](#opciones-de-cámara) |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Cámara con la que se abre primero la captura facial (prueba de vida). Consulta [Opciones de cámara](#opciones-de-cámara) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Muestra el selector de cámara durante la captura en el paso del documento |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Muestra el selector de cámara durante la captura en el paso de prueba de vida |> [!TIP]
>
> Consulta más abajo las [definiciones de tipos de TypeScript](#tipos-de-typescript) para ver la interfaz `DiditSdkConfiguration` completa.***## Opciones de cámara> [!NOTE]
>
> Las opciones de cámara requieren `@didit-protocol/sdk-web`**0.4.0** o posterior.El SDK web ofrece las mismas cuatro opciones de cámara que los [SDK nativos](https://docs.didit.me/es/integration/native-sdks/overview.md). De forma predeterminada, la captura del documento abre la cámara trasera y la captura facial (prueba de vida) abre la cámara frontal (de selfie), y ambos pasos incluyen un selector de cámara dentro de la captura en los dispositivos con más de una cámara. Define `defaultLivenessCamera: 'back'` para abrir la captura facial con la cámara trasera, por ejemplo en un quiosco o cuando un operador sostiene el dispositivo y lo apunta hacia la persona que se está verificando.| Opción | Tipo | Valor predeterminado | Descripción |
| - | - | - | - |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Cámara que se usa al entrar por primera vez en la pantalla de captura del documento |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Cámara que se usa al entrar por primera vez en la pantalla de captura de la prueba de vida (facial pasiva) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Muestra el selector de cámara dentro de la captura en la pantalla del documento; `false` fija al usuario en `defaultDocumentCamera` |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Muestra el selector de cámara dentro de la captura en la pantalla de la prueba de vida; `false` fija al usuario en `defaultLivenessCamera` |```typescript theme={null}
// A kiosk: the operator points the device at the person, on the rear camera, with no way to switch
DiditSdk.shared.startVerification({
  url,
  configuration: {
    defaultLivenessCamera: 'back',
    showLivenessCameraSwitchButton: false
  }
});
```- Los valores de lente aceptados son `'front'` y `'back'`. Cualquier otro valor se ignora, al igual que un indicador del selector que no sea booleano.
- Un dispositivo que no tiene la cámara solicitada mantiene la que tiene: un portátil al que se le pide `'back'` sigue usando su webcam. El selector se oculta en los dispositivos con una sola cámara, independientemente de lo que indiquen los indicadores.
- Las opciones de la prueba de vida se aplican a la comprobación de prueba de vida pasiva. La prueba de vida activa no se ve afectada.
- El SDK reenvía las opciones a la página de verificación como parámetros de consulta de la URL de verificación: `document_camera`, `liveness_camera`, `document_camera_switch` y `liveness_camera_switch`. Si abres la URL de verificación directamente en lugar de hacerlo a través del SDK, defínelos tú mismo: añade `?liveness_camera=back` a una URL sin cadena de consulta, `&liveness_camera=back` a una que ya tiene parámetros, o defínelos con la API `URL` para cubrir ambos casos:```typescript theme={null}
const verificationUrl = new URL(url);
verificationUrl.searchParams.set('liveness_camera', 'back');
verificationUrl.searchParams.set('liveness_camera_switch', 'false');
window.location.assign(verificationUrl.toString());
```***## Enviar eventos`DiditSdk.shared.submitEvent()` pone en cola eventos del usuario final (registro, inicio de sesión, inicio de sesión fallido, cierre de sesión, restablecimiento de contraseña, MFA, cambio de dispositivo) para la monitorización de eventos de Didit.
Tu backend genera un token de monitorización para la persona, y el SDK envía los eventos en lotes junto con la huella digital del dispositivo.
Nunca envíes una clave de API al navegador.```typescript theme={null}
DiditSdk.shared.submitEvent({
  monitoringToken, // minted by your backend for this person
  event: { category: "auth", actionType: "login", payload: { method: "password" } },
});
```Consulta [Envío de eventos desde el SDK](https://docs.didit.me/es/transaction-monitoring/sdk-event-submission.md) para conocer el token, los campos del evento y el comportamiento de entrega.***## Tamaño y desplazamiento del modal> [!NOTE]
>
> El comportamiento de tamaño que se describe a continuación requiere **0.3.1** o posterior. Las versiones **0.3.0** y anteriores pueden recortar el flujo de verificación en ventanas de escritorio de poca altura y en orientación horizontal.El modo modal usa un ancho máximo de 500px y una altura máxima de 700px. En ventanas de escritorio de poca altura y en orientación horizontal, el iframe se ajusta al 90% del área visible de la ventana. El flujo de verificación se desplaza dentro del iframe, de modo que todos los pasos siguen siendo accesibles mientras la página detrás del modal permanece bloqueada.El SDK usa `dvh` en los navegadores que admiten unidades dinámicas de viewport y recurre a `vh` en navegadores compatibles más antiguos. Con anchos de 540px o menos, el modal ocupa toda el área visible de la ventana. El botón de cierre y la confirmación de salida permanecen dentro del modal.### Flujo de verificación rediseñado> [!NOTE]
>
> Todo lo que se describe en esta sección se aplica a partir de la versión **0.5.0**, que aún no se ha publicado. Hasta que actualices, el modal mantiene el tamaño descrito arriba.A partir de la versión 0.5.0, el modal ajusta su tamaño al flujo de verificación rediseñado en cuanto la página informa de su diseño con un [mensaje `didit:layout`](https://docs.didit.me/es/integration/web-sdks/incontext-iframe#dimensionar-el-iframe-con-diditlayout):| Ancho de la ventana | Modal (a partir de la versión 0.5.0) |
| - | - |
| 1024px o más | 960px por 660px en todos los pasos, como máximo el 90% del ancho y de la altura de la ventana |
| De 541px a 1023px | 500px de ancho y tan alto como el contenido de la página, como máximo el 90% de la altura de la ventana |
| 540px o menos | Pantalla completa |- **Tamaño inicial, a partir de la versión 0.5.0:** hasta que la página informa de su diseño, y en las páginas que nunca lo hacen, el modal mantiene el tamaño máximo actual de 500px por 700px. Sigue adaptándose a ventanas de poca altura y se muestra a pantalla completa con 540px o menos.
- **Botón de cierre, a partir de la versión 0.5.0:** un círculo de 44px sobre la barra superior de la página. Sigue el tema claro u oscuro de la página y se desplaza a la izquierda en los idiomas de derecha a izquierda.
- **Modo incrustado, a partir de la versión 0.5.0:** sigue ocupando su elemento contenedor, como antes (consulta [Modo incrustado](#modo-incrustado)).
- **URL de verificación, a partir de la versión 0.5.0:** el SDK añade `sdk_presentation` (`modal` o `embedded`) y, en un modal, `sdk_close_button` (`true` o `false`, según `showCloseButton`), para que la página sepa cómo se muestra.
- **Eventos, a partir de la versión 0.5.0:** el SDK gestiona `didit:layout` por sí mismo y no lo pasa a `onEvent`.No hay nada que configurar y todas las opciones existentes siguen funcionando.***## Modo incrustadoEl modo incrustado no usa el límite de 500px por 700px del modal. El SDK ocupa la caja de contenido del elemento contenedor, así que asigna a ese elemento una altura explícita o definida de otro modo:```html theme={null}
<div id="verification-container" style="width: 500px; height: 700px;"></div>
``````typescript theme={null}
DiditSdk.shared.startVerification({
  url: 'https://verify.didit.me/u/...',
  configuration: {
    embedded: true,
    embeddedContainerId: 'verification-container'
  }
});
```Si el contenedor no tiene una altura definida, el iframe incrustado tampoco tiene una altura utilizable. Cambia el tamaño del contenedor cuando cambie tu diseño; el SDK sigue ocupándolo automáticamente.***## Resultados de la verificaciónEl SDK devuelve tres tipos de resultados:### CompletedEl flujo de verificación terminó (aprobado, pendiente o rechazado).```typescript theme={null}
{
  type: 'completed',
  session: {
    sessionId: 'session-uuid',
    status: 'Approved' | 'Pending' | 'Declined'
  }
}
```> [!NOTE]
>
> El tipo de TypeScript declara `'Approved' | 'Pending' | 'Declined'`, pero el valor se transmite tal cual desde el estado de la sesión del flujo alojado, así que también puedes recibir otros estados, como `In Review`. `Pending` es el valor por defecto del SDK cuando el flujo no informó ningún estado. Trata `status` como una indicación y usa el [webhook](https://docs.didit.me/es/integration/webhooks.md) como fuente de la decisión definitiva.### CancelledEl usuario cerró el modal de verificación. `session` se incluye cuando ya se conocía un `sessionId` (puede ser `undefined` si el usuario canceló antes de que el iframe informara uno).```typescript theme={null}
{
  type: 'cancelled',
  session: {
    sessionId: 'session-uuid',
    status: 'Pending'
  }
}
```### FailedSe produjo un error durante la verificación.```typescript theme={null}
{
  type: 'failed',
  error: {
    type: 'sessionExpired' | 'networkError' | 'cameraAccessDenied' | 'unknown',
    message: 'Your verification session has expired.'
  }
}
```***## Gestión del estadoPuedes observar el estado del SDK para crear una interfaz personalizada:```typescript theme={null}
DiditSdk.shared.onStateChange = (state, error) => {
  switch (state) {
    case 'idle':
      // Ready to start
      break;
    case 'loading':
      // Loading verification iframe
      showLoadingSpinner();
      break;
    case 'ready':
      // Verification in progress
      hideLoadingSpinner();
      break;
    case 'error':
      // Error occurred
      showError(error);
      break;
  }
};

// Check current state
console.log(DiditSdk.shared.state);

// Check if verification is presented
console.log(DiditSdk.shared.isPresented);
```***## Referencia de la API### DiditSdk.sharedLa instancia singleton del SDK.### Métodos| Método | Descripción |
| - | - |
| `startVerification(options)` | Inicia el flujo de verificación |
| `submitEvent(options)` | Pone en cola un evento del usuario final para la monitorización de eventos con un token de monitorización |
| `close()` | Cierra el modal de verificación de forma programática |
| `destroy()` | Destruye la instancia del SDK y libera sus recursos |### Propiedades| Propiedad | Tipo | Descripción |
| - | - | - |
| `state` | `DiditSdkState` | Estado actual del SDK |
| `configuration` | `DiditSdkConfiguration \| undefined` | Configuración activa (se establece mientras hay una verificación en curso) |
| `isPresented` | `boolean` | Indica si el modal de verificación está abierto |
| `errorMessage` | `string \| undefined` | Mensaje de error (se establece cuando el estado es `error`); un inicio fallido permanece en `error` hasta que vuelvas a iniciar |### Callbacks| Callback | Parámetros | Descripción |
| - | - | - |
| `onComplete` | `(result: VerificationResult)` | Se invoca cuando termina la verificación |
| `onStateChange` | `(state: DiditSdkState, error?: string)` | Se invoca cuando cambia el estado |
| `onEvent` | `(event: VerificationEvent)` | Se invoca cuando se producen eventos de verificación detallados |***## Eventos detalladosSigue el progreso de la verificación con el callback `onEvent`:```typescript theme={null}
DiditSdk.shared.onEvent = (event) => {
  console.log('Event:', event.type, event.data);
};
```### Referencia de eventos| Evento | Descripción | Payload de datos |
| - | - | - |
| `didit:ready` | La página está lista y el sessionId está disponible | `{ sessionId }` |
| `didit:started` | El usuario inició la verificación | `{ sessionId? }` |
| `didit:step_started` | Comenzó un paso de la verificación | `{ step, sessionId? }` |
| `didit:step_completed` | Un paso terminó correctamente | `{ step, nextStep?, sessionId? }` |
| `didit:step_changed` | Cambió el paso actual | `{ step, previousStep?, sessionId? }` |
| `didit:media_started` | Comenzó la captura con la cámara o de contenido multimedia | `{ step, mediaType }` |
| `didit:media_captured` | Se capturó una foto o un video | `{ step, isAuto }` |
| `didit:document_selected` | El usuario seleccionó el tipo de documento y el país | `{ documentType, country }` |
| `didit:verification_submitted` | Se enviaron los datos para su procesamiento | `{ step, sessionId? }` |
| `didit:code_sent` | Se envió el código OTP | `{ step, channel?, codeSize?, sessionId? }` |
| `didit:code_verified` | Se verificó el código OTP | `{ step, sessionId? }` |
| `didit:status_updated` | Cambió el estado de la sesión | `{ status, previousStep?, sessionId? }` |
| `didit:completed` | Se completó el flujo de verificación | `{ sessionId?, status?, country?, documentType? }` |
| `didit:cancelled` | El usuario canceló la verificación | `{ sessionId? }` |
| `didit:error` | Se produjo un error | `{ error: string, step?, sessionId? }` |
| `didit:close_request` | El usuario solicitó cerrar el modal | (sin datos) |### Pérdida de conexiónSi se cae la conexión del usuario, la página de verificación muestra una pantalla de "Sin conexión a internet" en lugar de que un paso quede cargando.
Sigue comprobando la conexión en segundo plano y cierra la pantalla por sí sola en cuanto vuelve a poder conectarse con Didit, y el usuario continúa desde el paso en el que estaba.
Dentro del modal del SDK o de un iframe, la pantalla también ofrece **Salir de la verificación**: la página envía entonces `didit:error` con `error: "network_error"`, seguido de `didit:cancelled`, y el SDK cierra el modal y llama a `onComplete` con `type: "cancelled"`.A partir de la versión 0.5.0, el mensaje `didit:layout` de la página ajusta el tamaño del modal y no llega a `onEvent`. Si en cambio incrustas la página con tu propio iframe, consulta [Ajustar el tamaño del iframe a partir de `didit:layout`](https://docs.didit.me/es/integration/web-sdks/incontext-iframe#dimensionar-el-iframe-con-diditlayout).### Valores de pasoEl campo `step` puede tomar uno de estos valores:- `document_selection` - Selección del tipo de documento
- `document_front` - Anverso del documento
- `document_back` - Reverso del documento
- `face` - Verificación facial o prueba de vida
- `email` - Verificación de correo electrónico
- `phone` - Verificación de teléfono
- `poa` - Prueba de domicilio
- `questionnaire` - Paso de cuestionario### Valores de canalEl campo `channel` de `code_sent` puede ser:- `email` - Código enviado por correo electrónico
- `sms` - Código enviado por SMS
- `whatsapp` - Código enviado por WhatsApp### Longitud del códigoEl campo `codeSize` de `code_sent` indica la longitud del código OTP (por ejemplo, 4 o 6 dígitos).***## Tipos de TypeScript```typescript theme={null}
// Configuration types
interface DiditSdkConfiguration {
  /**
   * Enable SDK logging for debugging
   * @default false
   */
  loggingEnabled?: boolean;

  /**
   * Custom container element to mount the modal
   * @default document.body
   */
  containerElement?: HTMLElement;

  /**
   * Z-index for the modal overlay
   * @default 9999
   */
  zIndex?: number;

  /**
   * Show close button on modal
   * @default true
   */
  showCloseButton?: boolean;

  /**
   * Show exit confirmation dialog when closing
   * @default true
   */
  showExitConfirmation?: boolean;

  /**
   * Automatically close modal when verification completes
   * @default false
   */
  closeModalOnComplete?: boolean;

  /**
   * Render verification inline instead of modal overlay
   * @default false
   */
  embedded?: boolean;

  /**
   * Container element ID for embedded mode
   * Required when embedded is true
   */
  embeddedContainerId?: string;

  /**
   * Camera the document capture opens first.
   * @default 'back'
   */
  defaultDocumentCamera?: CameraLens;

  /**
   * Camera the face (liveness) capture opens first.
   * Applies to passive liveness; devices without a rear camera keep the front one.
   * @default 'front'
   */
  defaultLivenessCamera?: CameraLens;

  /**
   * Show the in-capture camera switcher on the document step.
   * false locks the user to defaultDocumentCamera.
   * @default true
   */
  showDocumentCameraSwitchButton?: boolean;

  /**
   * Show the in-capture camera switcher on the liveness step.
   * false locks the user to defaultLivenessCamera.
   * @default true
   */
  showLivenessCameraSwitchButton?: boolean;
}

type CameraLens = 'front' | 'back';

// Session + error types
type VerificationStatus = 'Approved' | 'Pending' | 'Declined';

interface SessionData {
  sessionId: string;
  status: VerificationStatus;
}

type VerificationErrorType =
  | 'sessionExpired'
  | 'networkError'
  | 'cameraAccessDenied'
  | 'unknown';

interface VerificationError {
  type: VerificationErrorType;
  message: string;
}

// Verification result — `session` and `error` are both optional fields
// on every result; which one is populated depends on `type`.
type VerificationResultType = 'completed' | 'cancelled' | 'failed';

interface VerificationResult {
  type: VerificationResultType;
  session?: SessionData;
  error?: VerificationError;
}

// State types
type DiditSdkState = 'idle' | 'loading' | 'ready' | 'error';

// Event types
type VerificationEventType =
  | 'didit:ready'
  | 'didit:started'
  | 'didit:step_started'
  | 'didit:step_completed'
  | 'didit:step_changed'
  | 'didit:media_started'
  | 'didit:media_captured'
  | 'didit:document_selected'
  | 'didit:verification_submitted'
  | 'didit:code_sent'
  | 'didit:code_verified'
  | 'didit:status_updated'
  | 'didit:completed'
  | 'didit:cancelled'
  | 'didit:error'
  | 'didit:close_request';

interface VerificationEventData {
  sessionId?: string;
  status?: string;
  step?: string;
  nextStep?: string;
  previousStep?: string;
  error?: string;
  country?: string;
  documentType?: string;
  isAuto?: boolean;
  mediaType?: string;
  channel?: string;
  codeSize?: number;
  [key: string]: unknown;
}

interface VerificationEvent {
  type: VerificationEventType;
  data?: VerificationEventData;
  timestamp?: number;
}

// Start verification options
interface StartVerificationOptions {
  url: string;
  configuration?: DiditSdkConfiguration;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.