> ## 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: KYC, KYB, AML e liveness via embed, redirect ou iframe. A partir de $0.33 por KYC completo, $10 grátis/mês, sem contrato.



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 à sua aplicação web, com controle total sobre a experiência do usuário.***## Recursos- **API simples** - Padrão singleton com métodos fáceis de usar
- **Integração flexível** - Use a URL do UniLink diretamente ou crie sessões pelo backend
- **Responsivo** - Funciona em navegadores de desktop e de dispositivos móveis
- **Personalizável** - Opções de configuração para estilo e comportamento
- **Vários formatos** - Builds ESM, CommonJS e UMD
- **Suporte a TypeScript** - Definições de tipos completas incluídas
- **Modos modal e inline** - Escolha entre uma sobreposição modal ou a incorporação inline
- **Callbacks de eventos** - Eventos em tempo real sobre o progresso da verificação (iniciada, etapa concluída, finalizada)
- **Gerenciamento de estado** - Observe o estado do SDK para criar uma UI 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` adicionou `DiditSdk.shared.submitEvent()` (veja [Enviar eventos](#envio-de-eventos)), e a `0.5.1` permite que o fluxo hospedado solicite o documento de identidade do usuário a uma carteira de identidade digital dentro do SDK, além de manter uma inicialização com falha no estado `error`, com sua `errorMessage`.
> A `0.4.0` adicionou as opções de câmera que os SDKs nativos já oferecem, incluindo `defaultLivenessCamera`, que abre a captura facial na câmera traseira (veja [Opções de câmera](#opções-de-câmera)).### Verificar a versão instaladaSeu gerenciador de pacotes continua sendo a fonte definitiva para a versão instalada:```bash theme={null}
npm list @didit-protocol/sdk-web
npm view @didit-protocol/sdk-web version
```Você 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`, essa 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, portanto sempre corresponde à versão instalada.A `0.3.0` e versões anteriores informam `0.2.1` nessa exportação, independentemente da versão instalada. Nessas versões, use `npm list` ou o seu lockfile.***## JavaScript puro### ES Modules / 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 com frameworks> [card] [Exemplos do SDK Web](https://github.com/didit-protocol/sdk-web-examples)
>
> React, Angular, Svelte, Next.js, Nuxt, Vue e outros, com exemplos e documentação para cada framework.***## Métodos de integraçãoHá duas formas de integrar o SDK:### Método 1: URL do UniLink (mais simples)Use a URL do UniLink do seu fluxo de verificação (workflow) diretamente do Didit Console. Nenhum backend é necessário.```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 a URL do UniLink no [Didit Console](https://business.didit.me) → Seu fluxo → Copiar link.**O session\_id gerado será enviado a você por meio de um evento.**
**[Consulte a referência de eventos aqui](#referência-de-eventos)**### Método 2: Sessão pelo backend (recomendado para produção)Seu backend cria uma sessão pela API da Didit e retorna a URL de verificação hospedada. Isso dá a você controle sobre `vendor_data`, o `callback` por sessão e `metadata`, além de permitir criar sessões antes que o usuário chegue ao frontend.Saiba mais na [referência da API Create Session](https://docs.didit.me/pt-br/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 se chama `url` (veja o [esquema OpenAPI de Create Session](https://docs.didit.me/pt-br/sessions-api/create-session.md)). Passe-o diretamente para `startVerification({ url })`.***## Configuração| Opção | Tipo | Padrão | Descrição |
| - | - | - | - |
| `loggingEnabled` | `boolean` | `false` | Ativa os logs do SDK para depuração |
| `containerElement` | `HTMLElement` | `document.body` | Elemento contêiner personalizado onde o modal é montado |
| `zIndex` | `number` | `9999` | Z-index da sobreposição do modal |
| `showCloseButton` | `boolean` | `true` | Exibe o botão de fechar no modal |
| `showExitConfirmation` | `boolean` | `true` | Exibe uma caixa de diálogo de confirmação de saída ao fechar |
| `closeModalOnComplete` | `boolean` | `false` | Fecha o modal automaticamente quando a verificação é concluída |
| `embedded` | `boolean` | `false` | Renderiza a verificação inline em vez de em uma sobreposição modal |
| `embeddedContainerId` | `string` | — | ID do elemento contêiner para o modo incorporado (obrigatório quando `embedded` é `true`) |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Câmera aberta primeiro na captura de documento. Veja [Opções de câmera](#opções-de-câmera) |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Câmera aberta primeiro na captura facial (prova de vida). Veja [Opções de câmera](#opções-de-câmera) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Exibe o seletor de câmera durante a captura na etapa de documento |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Exibe o seletor de câmera durante a captura na etapa de prova de vida |> [!TIP]
>
> Veja abaixo as [definições de tipos TypeScript](#tipos-typescript) completas para a interface `DiditSdkConfiguration` inteira.***## Opções de câmera> [!NOTE]
>
> As opções de câmera exigem `@didit-protocol/sdk-web`**0.4.0** ou posterior.O SDK web oferece as mesmas quatro opções de câmera dos [SDKs nativos](https://docs.didit.me/pt-br/integration/native-sdks/overview.md). Por padrão, a captura do documento abre a câmera traseira e a captura do rosto (prova de vida) abre a câmera frontal (selfie). As duas etapas oferecem um seletor de câmera durante a captura em dispositivos com mais de uma câmera. Defina `defaultLivenessCamera: 'back'` para abrir a captura do rosto na câmera traseira, por exemplo em um quiosque ou quando um operador segura o dispositivo e o aponta para a pessoa que está sendo verificada.| Opção | Tipo | Padrão | Descrição |
| - | - | - | - |
| `defaultDocumentCamera` | `'front' \| 'back'` | `'back'` | Lente usada ao entrar pela primeira vez na tela de captura do documento |
| `defaultLivenessCamera` | `'front' \| 'back'` | `'front'` | Lente usada ao entrar pela primeira vez na tela de captura da prova de vida (rosto, modo passivo) |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | Exibe o seletor de câmera durante a captura na tela do documento; `false` restringe o usuário a `defaultDocumentCamera` |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | Exibe o seletor de câmera durante a captura na tela da prova de vida; `false` restringe o usuário a `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 de lente aceitos são `'front'` e `'back'`. Qualquer outro valor é ignorado, assim como uma flag do seletor que não seja booleana.
- Um dispositivo sem a câmera solicitada usa a câmera disponível: um notebook configurado com `'back'` continua usando a webcam. O seletor fica oculto em dispositivos com uma única câmera, independentemente das flags.
- As opções de prova de vida se aplicam à verificação de prova de vida passiva. A prova de vida ativa não é afetada.
- O SDK repassa as opções à página de verificação como parâmetros de consulta da URL de verificação: `document_camera`, `liveness_camera`, `document_camera_switch` e `liveness_camera_switch`. Se você abrir a URL de verificação diretamente, sem passar pelo SDK, defina-os você mesmo: acrescente `?liveness_camera=back` a uma URL sem query string, `&liveness_camera=back` a uma que já tenha parâmetros, ou defina-os com a API `URL` para tratar 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());
```***## Envio de eventos`DiditSdk.shared.submitEvent()` coloca em fila eventos do usuário final (cadastro, login, falha de login, logout, redefinição de senha, MFA, troca de dispositivo) para o monitoramento de eventos da Didit.
Seu backend gera um token de monitoramento para a pessoa, e o SDK envia os eventos em lotes junto com a impressão digital do dispositivo.
Nunca envie uma chave de API ao navegador.```typescript theme={null}
DiditSdk.shared.submitEvent({
  monitoringToken, // minted by your backend for this person
  event: { category: "auth", actionType: "login", payload: { method: "password" } },
});
```Consulte [Envio de eventos pelo SDK](https://docs.didit.me/pt-br/transaction-monitoring/sdk-event-submission.md) para saber sobre o token, os campos do evento e o comportamento de entrega.***## Dimensionamento e rolagem do modal> [!NOTE]
>
> O comportamento de dimensionamento abaixo exige **0.3.1** ou posterior. As versões **0.3.0** e anteriores podem cortar o fluxo de verificação em viewports de desktop com pouca altura e em modo paisagem.O modo modal usa largura máxima de 500px e altura máxima de 700px. Em viewports de desktop com pouca altura e em modo paisagem, o iframe acompanha 90% da viewport visível. O fluxo de verificação rola dentro do iframe, de modo que todas as etapas continuam acessíveis enquanto a página por trás do modal permanece bloqueada.O SDK usa `dvh` em navegadores compatíveis com unidades de viewport dinâmicas e recorre a `vh` nos navegadores suportados mais antigos. Em larguras de 540px ou menos, o modal ocupa toda a viewport visível. O botão de fechar e a confirmação de saída ficam dentro do modal.### Fluxo de verificação redesenhado> [!NOTE]
>
> Tudo nesta seção se aplica a partir da versão **0.5.0**, que ainda não foi publicada. Até você atualizar, o modal mantém o tamanho descrito acima.A partir da versão 0.5.0, o modal ajusta seu tamanho ao fluxo de verificação redesenhado assim que a página informa seu layout com uma [mensagem `didit:layout`](https://docs.didit.me/pt-br/integration/web-sdks/incontext-iframe#dimensione-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 todas as etapas, no máximo 90% da largura e da altura da janela |
| 541px a 1023px | 500px de largura e altura igual à do conteúdo da página, no máximo 90% da altura da janela |
| 540px ou menos | Tela cheia |- **Tamanho inicial, a partir da versão 0.5.0:** até a página informar seu layout, e para páginas que nunca o fazem, o modal mantém o tamanho máximo atual de 500px por 700px. Ele continua se ajustando a janelas de pouca altura e permanece em tela cheia em 540px ou menos.
- **Botão de fechar, a partir da versão 0.5.0:** um círculo de 44px sobre a barra superior da página. Ele segue o tema claro ou escuro da página e passa para a esquerda em idiomas escritos da direita para a esquerda.
- **Modo incorporado, a partir da versão 0.5.0:** continua ocupando todo o seu elemento hospedeiro, como antes (consulte [Modo incorporado](#modo-incorporado)).
- **URL de verificação, a partir da versão 0.5.0:** o SDK adiciona `sdk_presentation` (`modal` ou `embedded`) e, em um modal, `sdk_close_button` (`true` ou `false`, conforme `showCloseButton`), para que a página saiba como está sendo exibida.
- **Eventos, a partir da versão 0.5.0:** o SDK trata `didit:layout` internamente e não o repassa para `onEvent`.Não há nada para configurar, e todas as opções existentes continuam funcionando.***## Modo incorporadoO modo incorporado não usa o limite de 500px por 700px do modal. O SDK ocupa a caixa de conteúdo do elemento hospedeiro, então dê a esse elemento uma altura explícita ou definida 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 elemento hospedeiro não tiver uma altura definida, o iframe incorporado também não terá uma altura utilizável. Redimensione o elemento hospedeiro quando seu layout mudar; o SDK continua a preenchê-lo automaticamente.***## Resultados da verificaçãoO SDK retorna 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 é repassado do status da sessão do fluxo hospedado, então você também pode receber outros status, como `In Review`. `Pending` é o valor padrão do SDK quando o fluxo não informa nenhum status. Trate `status` como uma indicação e use o [webhook](https://docs.didit.me/pt-br/integration/webhooks.md) como fonte da decisão definitiva.### CanceladoO usuário fechou o modal de verificação. `session` é incluído quando um `sessionId` já era conhecido (pode ser `undefined` se o usuário cancelou antes de o iframe informar um).```typescript theme={null}
{
  type: 'cancelled',
  session: {
    sessionId: 'session-uuid',
    status: 'Pending'
  }
}
```### FalhouOcorreu um erro durante a verificação.```typescript theme={null}
{
  type: 'failed',
  error: {
    type: 'sessionExpired' | 'networkError' | 'cameraAccessDenied' | 'unknown',
    message: 'Your verification session has expired.'
  }
}
```***## Gerenciamento de estadoVocê pode 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 singleton do SDK.### Métodos| Método | Descrição |
| - | - |
| `startVerification(options)` | Inicia o fluxo de verificação |
| `submitEvent(options)` | Coloca na fila um evento do usuário final para monitoramento de eventos com um token de monitoramento |
| `close()` | Fecha o modal de verificação programaticamente |
| `destroy()` | Destrói a instância do SDK e libera 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 andamento) |
| `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 com falha permanece em `error` até você iniciar novamente |### Callbacks| Callback | Parâmetros | Descrição |
| - | - | - |
| `onComplete` | `(result: VerificationResult)` | Chamado quando a verificação termina |
| `onStateChange` | `(state: DiditSdkState, error?: string)` | Chamado a cada mudança de estado |
| `onEvent` | `(event: VerificationEvent)` | Chamado quando ocorrem eventos detalhados 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 | Payload de dados |
| - | - | - |
| `didit:ready` | A página está pronta e o sessionId está disponível | `{ sessionId }` |
| `didit:started` | O usuário iniciou a verificação | `{ sessionId? }` |
| `didit:step_started` | Uma etapa de verificação começou | `{ step, sessionId? }` |
| `didit:step_completed` | Uma etapa foi concluída com sucesso | `{ step, nextStep?, sessionId? }` |
| `didit:step_changed` | A etapa atual mudou | `{ step, previousStep?, sessionId? }` |
| `didit:media_started` | A captura de câmera/mídia começou | `{ step, mediaType }` |
| `didit:media_captured` | Foto/vídeo capturado | `{ step, isAuto }` |
| `didit:document_selected` | O usuário 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 status da sessão mudou | `{ status, previousStep?, sessionId? }` |
| `didit:completed` | Fluxo de verificação concluído | `{ sessionId?, status?, country?, documentType? }` |
| `didit:cancelled` | O usuário cancelou a verificação | `{ sessionId? }` |
| `didit:error` | Ocorreu um erro | `{ error: string, step?, sessionId? }` |
| `didit:close_request` | O usuário solicitou fechar o modal | (sem dados) |### Perda de conexãoSe a conexão do usuário cair, a página de verificação exibe uma tela de "Sem conexão com a internet" sobre o fluxo em vez de deixar uma etapa em carregamento.
Ela continua verificando em segundo plano e fecha a tela sozinha assim que a Didit volta a ficar acessível, e o usuário continua a partir da etapa em que estava.
Dentro do modal do SDK ou de um iframe, a tela também oferece **Exit Verification**: a página então envia `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 ao `onEvent`. Se, em vez disso, você incorporar a página com seu próprio iframe, consulte [Dimensionar o iframe a partir de `didit:layout`](https://docs.didit.me/pt-br/integration/web-sdks/incontext-iframe#dimensione-o-iframe-a-partir-de-diditlayout).### Valores de etapaO 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/prova de vida
- `email` - Verificação de e-mail
- `phone` - Verificação de telefone
- `poa` - Comprovante de endereço
- `questionnaire` - Etapa 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.