> ## 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 Verificação de Identidade: KYC Web

> SDK JavaScript da Didit para KYC, KYB, AML e prova de vida. Incorporado, redirecionamento ou iframe. Desde $0.33 por KYC completo, $10 grátis/mês.



Prompt de integração do SDK JavaScript
        Copiar o prompt para a área de transferência



      
      

\<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>



      
      

Colar em

O SDK JavaScript da Didit oferece uma forma programática de integrar a verificação na sua aplicação web, com controlo total sobre a experiência do utilizador.***## Funcionalidades- **API simples** - Padrão singleton com métodos fáceis de usar
- **Integração flexível** - Use o URL UniLink diretamente ou crie sessões através do backend
- **Responsivo** - Funciona em navegadores de computador e de dispositivos móveis
- **Personalizável** - Opções de configuração para estilo e comportamento
- **Vários formatos** - Compilações ESM, CommonJS e UMD
- **Suporte TypeScript** - Definições de tipos completas incluídas
- **Modo modal e em linha** - Escolha entre sobreposição modal ou integração em linha
- **Callbacks de eventos** - Eventos em tempo real sobre o progresso da verificação (iniciada, passo concluído, terminada)
- **Gestão de estado** - Observe o estado do SDK para criar uma interface personalizada***## Instalação### 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]
>
> A versão mais recente publicada no npm é a `0.5.1`.
> A `0.5.0` acrescentou `DiditSdk.shared.submitEvent()` (ver [Enviar eventos](#enviar-eventos)), e a `0.5.1` permite que o fluxo alojado peça à carteira de identidade digital o ID do utilizador dentro do SDK, e mantém uma inicialização falhada no estado `error` com o respetivo `errorMessage`.
> A `0.4.0` acrescentou as opções de câmara que os SDK nativos já oferecem, incluindo `defaultLivenessCamera`, que abre a captura facial na câmara traseira (ver [Opções de câmara](#opções-de-câmara)).### Verificar a versão instaladaO seu gestor de pacotes continua a ser a referência para a versão instalada:```bash theme={null}
npm list @didit-protocol/sdk-web
npm view @didit-protocol/sdk-web version
```Também pode inspecionar a exportação em tempo de execução:```typescript theme={null}
const { SDK_VERSION } = await import('@didit-protocol/sdk-web');

console.log(SDK_VERSION);
```A partir da `0.3.1`, esta exportação é gerada a partir da versão do pacote em todos os formatos JavaScript (ESM, CommonJS, UMD, UMD minificado) e na declaração TypeScript, por isso corresponde sempre à versão instalada.As versões `0.3.0` e anteriores devolvem `0.2.1` nesta exportação, independentemente da versão instalada. Nessas versões, use `npm list` ou o seu ficheiro de lock.***## 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'
});
```### Tag 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>
```***## Exemplos de frameworks> [card] [Exemplos Web do SDK](https://github.com/didit-protocol/sdk-web-examples)
>
> React, Angular, Svelte, Next.js, Nuxt, Vue e mais, com exemplos e documentação para cada framework.***## Métodos de integraçãoExistem duas formas de integrar o SDK:### Método 1: URL UniLink (o mais simples)Use o URL UniLink do seu fluxo diretamente a partir da Consola Didit. Não é necessário 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'
});
```Obtenha o seu URL UniLink na [Consola Didit](https://business.didit.me) → O seu fluxo → Copiar link.**O session\_id gerado ser-lhe-á enviado através de um evento.**
**[Consulte aqui a referência de eventos](#referência-de-eventos)**### Método 2: sessão no backend (recomendado para produção)O seu backend cria uma sessão através da API da Didit e devolve o URL de verificação alojado. Isto dá-lhe controlo sobre `vendor_data`, `callback` por sessão e `metadata`, e permite criar sessões antes de o utilizador chegar ao frontend.Saiba mais na [referência da API Create Session](https://docs.didit.me/pt/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]
>
> O campo da resposta de criação de sessão chama-se `url` (ver o [schema OpenAPI de Create Session](https://docs.didit.me/pt/sessions-api/create-session.md)). Passe-o diretamente a `startVerification({ url })`.***## Configuração| Opção | Tipo | Predefinição | Descrição |
| - | - | - | - |
| `loggingEnabled` | `boolean` | `false` | Ativar o registo do SDK para depuração |
| `containerElement` | `HTMLElement` | `document.body` | Elemento contentor personalizado onde montar o modal |
| `zIndex` | `number` | `9999` | Índice z da sobreposição modal |
| `showCloseButton` | `boolean` | `true` | Mostrar o botão de fechar no modal |
| `showExitConfirmation` | `boolean` | `true` | Mostrar a caixa de confirmação de saída ao fechar |
| `closeModalOnComplete` | `boolean` | `false` | Fechar automaticamente o modal quando a verificação for concluída |
| `embedded` | `boolean` | `false` | Mostrar a verificação em linha em vez da sobreposição modal |
| `embeddedContainerId` | `string` | — | ID do elemento contentor para o modo incorporado (obrigatório quando `embedded` é `true`) |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Câmara que a captura do documento abre primeiro. Ver [Opções de câmara](#opções-de-câmara) |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Câmara que a captura facial (prova de vida) abre primeiro. Ver [Opções de câmara](#opções-de-câmara) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Mostrar o seletor de câmara durante a captura no passo do documento |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Mostrar o seletor de câmara durante a captura no passo de prova de vida |> [!TIP]
>
> Consulte abaixo as [definições completas de tipos TypeScript](#tipos-typescript) da interface `DiditSdkConfiguration`.***## Opções de câmara> [!NOTE]
>
> As opções de câmara requerem `@didit-protocol/sdk-web`**0.4.0** ou posterior.O SDK web expõe as mesmas quatro opções de câmara que os [SDK nativos](https://docs.didit.me/pt/integration/native-sdks/overview.md). Por predefinição, a captura do documento abre a câmara traseira e a captura facial (prova de vida) abre a câmara frontal (selfie). Nos dois passos, em dispositivos com mais do que uma câmara, é apresentado um seletor de câmara durante a captura. Defina `defaultLivenessCamera: 'back'` para abrir a captura facial na câmara traseira, por exemplo num quiosque ou quando um operador segura no dispositivo e o aponta para a pessoa a verificar.| Opção | Tipo | Predefinição | Descrição |
| - | - | - | - |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Objetiva usada ao entrar pela primeira vez no ecrã de captura do documento |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Objetiva usada ao entrar pela primeira vez no ecrã de captura de prova de vida (facial passiva) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Mostra o seletor de câmara durante a captura no ecrã do documento; `false` fixa a câmara em `defaultDocumentCamera` |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Mostra o seletor de câmara durante a captura no ecrã de prova de vida; `false` fixa a câmara em `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
  }
});
```- Os valores aceites para a objetiva são `'front'` e `'back'`. Qualquer outro valor é ignorado, o mesmo acontecendo com um sinalizador do seletor que não seja booleano.
- Um dispositivo sem a câmara pedida mantém a que tem: um portátil que peça `'back'` continua a usar a webcam. O seletor fica oculto em dispositivos com uma única câmara, independentemente das opções.
- As opções de prova de vida aplicam-se à verificação de prova de vida passiva. A prova de vida ativa não é afetada.
- O SDK transmite as opções à página de verificação como parâmetros de consulta do URL de verificação: `document_camera`, `liveness_camera`, `document_camera_switch` e `liveness_camera_switch`. Se abrir o URL de verificação diretamente, em vez de através do SDK, defina-os você mesmo: acrescente `?liveness_camera=back` a um URL sem cadeia de consulta, `&liveness_camera=back` a um URL que já tenha parâmetros, ou defina-os com a API `URL`, que trata os dois 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()` coloca em fila os eventos do utilizador final (registo, início de sessão, falha no início de sessão, terminar sessão, redefinição de palavra-passe, MFA, alteração de dispositivo) para a monitorização de eventos da Didit.
O seu back-end cria um token de monitorização para a pessoa, e o SDK envia os eventos em lotes juntamente com a impressão digital do dispositivo.
Nunca envie uma chave de API para o navegador.```typescript theme={null}
DiditSdk.shared.submitEvent({
  monitoringToken, // minted by your backend for this person
  event: { category: "auth", actionType: "login", payload: { method: "password" } },
});
```Consulte [Submissão de eventos do SDK](https://docs.didit.me/pt/transaction-monitoring/sdk-event-submission.md) para o token, os campos dos eventos e o comportamento de entrega.***## Dimensionamento e deslocamento do modal> [!NOTE]
>
> O comportamento de dimensionamento descrito abaixo requer a versão **0.3.1** ou posterior. As versões **0.3.0** e anteriores podem cortar o fluxo de verificação em áreas de visualização de computadores com pouca altura e em orientação paisagem.O modo modal usa uma largura máxima de 500px e uma altura máxima de 700px. Em áreas de visualização de computadores e em orientação paisagem com menor altura, o iframe ocupa 90% da área de visualização visível. O fluxo de verificação desloca-se dentro do iframe, pelo que todos os passos continuam acessíveis, enquanto a página por trás do modal fica bloqueada.O SDK usa `dvh` nos navegadores que suportam unidades de área de visualização dinâmicas e recorre a `vh` nos navegadores antigos suportados. Com larguras de 540px ou menos, o modal ocupa toda a área de visualização visível. O botão de fecho e a confirmação de saída mantêm-se dentro do modal.### Fluxo de verificação redesenhado> [!NOTE]
>
> Tudo o que está nesta secção se aplica a partir da versão **0.5.0**, que ainda não está publicada. Até atualizar, o modal mantém o tamanho descrito acima.A partir da versão 0.5.0, o modal ajusta o seu tamanho ao fluxo de verificação redesenhado, depois de a página comunicar o respetivo layout através de uma [mensagem `didit:layout`](https://docs.didit.me/pt/integration/web-sdks/incontext-iframe#dimensionar-o-iframe-a-partir-de-diditlayout):| Largura da janela | Modal (a partir da versão 0.5.0) |
| - | - |
| 1024px ou mais | 960px por 660px em todos os passos, no máximo 90% da largura e da altura da janela |
| 541px a 1023px | 500px de largura e tão alto quanto o conteúdo da página, no máximo 90% da altura da janela |
| 540px ou menos | Ecrã inteiro |- **Tamanho inicial, a partir da versão 0.5.0:** até a página comunicar o respetivo layout, e para as páginas que nunca o fazem, o modal mantém o tamanho máximo existente de 500px por 700px. Continua a caber em janelas curtas e ocupa o ecrã inteiro com 540px ou menos.
- **Botão de fecho, a partir da versão 0.5.0:** um círculo de 44px sobre a barra superior da página. Segue o tema claro ou escuro da página e passa para a esquerda em idiomas da direita para a esquerda.
- **Modo incorporado, a partir da versão 0.5.0:** continua a preencher o respetivo elemento anfitrião, como antes (ver [Modo incorporado](#modo-incorporado)).
- **URL de verificação, a partir da versão 0.5.0:** o SDK acrescenta `sdk_presentation` (`modal` ou `embedded`) e, num modal, `sdk_close_button` (`true` ou `false`, conforme `showCloseButton`), para que a página saiba como é apresentada.
- **Eventos, a partir da versão 0.5.0:** o SDK trata de `didit:layout` por si próprio e não o transmite a `onEvent`.Não há nada para configurar, e todas as opções existentes continuam a funcionar.***## Modo incorporadoO modo incorporado não usa o limite de 500px por 700px do modal. O SDK preenche a área de conteúdo do elemento anfitrião, pelo que deve dar a esse elemento uma altura explícita ou resolvida de outra forma:```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'
  }
});
```Se o anfitrião não tiver uma altura resolvida, o iframe incorporado também não terá uma altura utilizável. Redimensione o anfitrião sempre que o seu layout mudar; o SDK continua a preenchê-lo automaticamente.***## Resultados da verificaçãoO SDK devolve três tipos de resultados:### ConcluídoO fluxo de verificação terminou (aprovado, pendente ou recusado).```typescript theme={null}
{
  type: 'completed',
  session: {
    sessionId: 'session-uuid',
    status: 'Approved' | 'Pending' | 'Declined'
  }
}
```> [!NOTE]
>
> O tipo TypeScript declara `'Approved' | 'Pending' | 'Declined'`, mas o valor é transmitido a partir do estado da sessão do fluxo alojado. Também pode receber outros estados, como `In Review`. `Pending` é o valor de reserva do SDK quando o fluxo não indicou nenhum estado. Trate `status` apenas como uma indicação e baseie-se no [webhook](https://docs.didit.me/pt/integration/webhooks.md) para a decisão canónica.### CanceladoO utilizador fechou o modal de verificação. `session` é incluído quando um `sessionId` já era conhecido (pode ser `undefined` se o utilizador cancelou antes de o iframe o ter indicado).```typescript theme={null}
{
  type: 'cancelled',
  session: {
    sessionId: 'session-uuid',
    status: 'Pending'
  }
}
```### FalhadoOcorreu um erro durante a verificação.```typescript theme={null}
{
  type: 'failed',
  error: {
    type: 'sessionExpired' | 'networkError' | 'cameraAccessDenied' | 'unknown',
    message: 'Your verification session has expired.'
  }
}
```***## Gestão do estadoPode observar o estado do SDK para criar uma interface 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);
```***## Referência da API### DiditSdk.sharedA instância única do SDK.### Métodos| Método | Descrição |
| - | - |
| `startVerification(options)` | Inicia o fluxo de verificação |
| `submitEvent(options)` | Coloca na fila um evento do utilizador final para monitorização de eventos, com um token de monitorização |
| `close()` | Fecha programaticamente o modal de verificação |
| `destroy()` | Destrói a instância do SDK e limpa os recursos |### Propriedades| Propriedade | Tipo | Descrição |
| - | - | - |
| `state` | `DiditSdkState` | Estado atual do SDK |
| `configuration` | `DiditSdkConfiguration \| undefined` | Configuração ativa (definida enquanto uma verificação está em curso) |
| `isPresented` | `boolean` | Indica se o modal de verificação está aberto |
| `errorMessage` | `string \| undefined` | Mensagem de erro (definida quando o estado é `error`); uma inicialização falhada permanece em `error` até iniciar novamente |### Callbacks| Callback | Parâmetros | Descrição |
| - | - | - |
| `onComplete` | `(result: VerificationResult)` | Chamado quando a verificação termina |
| `onStateChange` | `(state: DiditSdkState, error?: string)` | Chamado quando o estado muda |
| `onEvent` | `(event: VerificationEvent)` | Chamado para eventos granulares de verificação |***## Eventos granularesAcompanhe o progresso da verificação com o callback `onEvent`:```typescript theme={null}
DiditSdk.shared.onEvent = (event) => {
  console.log('Event:', event.type, event.data);
};
```### Referência de eventos| Evento | Descrição | Dados do payload |
| - | - | - |
| `didit:ready` | A página está pronta e o sessionId está disponível | `{ sessionId }` |
| `didit:started` | O utilizador iniciou a verificação | `{ sessionId? }` |
| `didit:step_started` | Um passo de verificação começou | `{ step, sessionId? }` |
| `didit:step_completed` | Um passo foi concluído com êxito | `{ step, nextStep?, sessionId? }` |
| `didit:step_changed` | O passo atual mudou | `{ step, previousStep?, sessionId? }` |
| `didit:media_started` | Captura de câmara ou multimédia iniciada | `{ step, mediaType }` |
| `didit:media_captured` | Foto ou vídeo capturado | `{ step, isAuto }` |
| `didit:document_selected` | O utilizador selecionou o tipo de documento e o país | `{ documentType, country }` |
| `didit:verification_submitted` | Dados enviados para processamento | `{ step, sessionId? }` |
| `didit:code_sent` | Código OTP enviado | `{ step, channel?, codeSize?, sessionId? }` |
| `didit:code_verified` | Código OTP verificado | `{ step, sessionId? }` |
| `didit:status_updated` | O estado da sessão mudou | `{ status, previousStep?, sessionId? }` |
| `didit:completed` | Fluxo de verificação concluído | `{ sessionId?, status?, country?, documentType? }` |
| `didit:cancelled` | O utilizador cancelou a verificação | `{ sessionId? }` |
| `didit:error` | Ocorreu um erro | `{ error: string, step?, sessionId? }` |
| `didit:close_request` | O utilizador pediu para fechar o modal | (sem dados) |### Ligação perdidaSe a ligação do utilizador for interrompida, a página de verificação sobrepõe um ecrã "Sem ligação à Internet" ao fluxo, em vez de deixar um passo a carregar.
A página continua a verificar em segundo plano e fecha o ecrã automaticamente assim que a Didit voltar a ser contactável, e o utilizador prossegue a partir do passo em que estava.
Dentro do modal do SDK ou de um iframe, o ecrã oferece também **Exit Verification**: a página envia então `didit:error` com `error: "network_error"`, seguido de `didit:cancelled`, e o SDK fecha o modal e chama `onComplete` com `type: "cancelled"`.A partir da versão 0.5.0, a mensagem `didit:layout` da página dimensiona o modal e não chega a `onEvent`. Se, em vez disso, incorporar a página com o seu próprio iframe, consulte [Dimensionar o iframe a partir de `didit:layout`](https://docs.didit.me/pt/integration/web-sdks/incontext-iframe#dimensionar-o-iframe-a-partir-de-diditlayout).### Valores de passoO campo `step` pode ser um dos seguintes:- `document_selection` - Seleção do tipo de documento
- `document_front` - Frente do documento
- `document_back` - Verso do documento
- `face` - Verificação facial e prova de vida
- `email` - Verificação de e-mail
- `phone` - Verificação de telefone
- `poa` - Comprovativo de morada
- `questionnaire` - Passo de questionário### Valores de canalO campo `channel` em `code_sent` pode ser:- `email` - Código enviado por e-mail
- `sms` - Código enviado por SMS
- `whatsapp` - Código enviado por WhatsApp### Tamanho do códigoO campo `codeSize` em `code_sent` indica o comprimento do código OTP (por exemplo, 4 ou 6 dígitos).***## Tipos 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.