> ## 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 Node.js e TypeScript para KYC e AML

> Guia rápido do SDK oficial da Didit para Node.js e TypeScript: chamadas tipadas às APIs, verificação de webhooks e de tokens de autenticação.

A biblioteca oficial da Didit para Node.js e TypeScript. Ela roda em Node.js 18 ou versões posteriores, Bun, Deno e runtimes de borda com `fetch`, inclui builds em ES module e CommonJS e não tem dependências de runtime. Consulte a [visão geral dos SDKs de servidor](https://docs.didit.me/pt-br/integration/server-sdks/overview.md) para saber o que todos os SDKs têm em comum.

## Instalação

```bash theme={null}
npm install @didit-protocol/sdk-node
```

O pacote é o [`@didit-protocol/sdk-node` no npm](https://www.npmjs.com/package/@didit-protocol/sdk-node). O código-fonte e o changelog estão em [didit-protocol/sdk-node](https://github.com/didit-protocol/sdk-node) no GitHub.

## Configurar o cliente

`new Didit()` lê `DIDIT_API_KEY` do ambiente em Node.js, Bun e Deno (com `--allow-env`). Runtimes de edge não têm ambiente de processo, então, nesses casos, passe a chave como opção: `new Didit({ apiKey: env.DIDIT_API_KEY })`. Passe opções para substituí-la ou para definir os IDs de organização e de aplicação exigidos pelas chamadas no escopo da aplicação (casos, redes, relatórios regulatórios). O timeout é em milissegundos.

```typescript theme={null}
import Didit from "@didit-protocol/sdk-node";

const didit = new Didit({
  apiKey: process.env.DIDIT_API_KEY,
  organizationId: process.env.DIDIT_ORGANIZATION_ID,
  applicationId: process.env.DIDIT_APPLICATION_ID,
  timeout: 30_000,
  maxRetries: 2,
});

// Options for a single call.
const fast = didit.withOptions({ timeout: 5_000, maxRetries: 0 });
console.log(await fast.sessions.retrieveDecision("11111111-2222-3333-4444-555555555555"));
```

Com CommonJS, use `const { Didit } = require("@didit-protocol/sdk-node");`.

## Criar uma sessão

Crie uma [sessão de verificação](https://docs.didit.me/pt-br/sessions-api/create-session.md) para um workflow e envie seu usuário para a URL dela. Os campos da requisição mantêm os nomes da própria API.

```typescript theme={null}
import Didit from "@didit-protocol/sdk-node";

const didit = new Didit();

const session = await didit.sessions.create({
  workflow_id: "11111111-2222-3333-4444-555555555555",
  vendor_data: "user-123",
  callback: "https://example.com/verification/done",
});
console.log(session.url);
```

## Ler a decisão

Quando o usuário terminar a verificação (ou quando o webhook chegar), [leia a decisão](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md). Cada resultado de recurso de verificação é uma lista com uma entrada por nó do fluxo, e as datas e horas são objetos `Date`.

```typescript theme={null}
import Didit from "@didit-protocol/sdk-node";

const didit = new Didit();

const decision = await didit.sessions.retrieveDecision("11111111-2222-3333-4444-555555555555");
console.log(decision.status);
for (const verification of decision.id_verifications ?? []) {
  console.log(verification.first_name, verification.last_name);
}
```

## Verificar um webhook

Passe o corpo bruto (não o JSON já interpretado) e os cabeçalhos da requisição: um objeto `req.headers` do Node.js ou do Express, um objeto `Headers` da Fetch API ou pares `[name, value]` (o tipo `WebhookHeaders`). `verify` retorna uma promise e é rejeitada com `WebhookVerificationError` para qualquer coisa que não seja uma entrega válida e recente.

```typescript theme={null}
import { webhooks, WebhookVerificationError, type WebhookHeaders } from "@didit-protocol/sdk-node";

const secret = process.env.DIDIT_WEBHOOK_SECRET ?? "";

export async function handleWebhook(rawBody: Buffer, headers: WebhookHeaders): Promise<number> {
  try {
    const event = await webhooks.verify(rawBody, headers, secret);
    if (event.webhook_type === "status.updated") {
      console.log(event.session_id, event.status);
    }
    return 200;
  } catch (error) {
    if (error instanceof WebhookVerificationError) return 400;
    throw error;
  }
}
```

Com Express, leia o corpo com `express.raw({ type: "application/json" })` e chame `handleWebhook(req.body, req.headers)`. Enquanto você faz a rotação do segredo, passe os dois: `[newSecret, oldSecret]`. Consulte [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md) para ver os eventos e o esquema de assinatura.

## Analisar uma transação

Envie um pagamento, saque ou transferência de cripto para o [monitoramento de transações](https://docs.didit.me/pt-br/transaction-monitoring/overview.md); a resposta traz o status e a pontuação de risco.

```typescript theme={null}
import Didit from "@didit-protocol/sdk-node";

const didit = new Didit();

const transaction = await didit.transactions.create({
  transaction_id: "txn-1001",
  transaction_category: "finance",
  transaction_details: { direction: "outbound", amount: 1500, currency: "EUR" },
  subject: { entity_type: "individual", vendor_data: "user-123", full_name: "Maria Garcia" },
});
console.log(transaction.status, transaction.score);
```

## Verificar tokens de Authentication

`Authentication` verifica, no seu backend, os tokens de acesso assinados pelo seu emissor de [Authentication](https://docs.didit.me/pt-br/authentication/overview.md), sem chamar a Didit a cada requisição. Ele também troca códigos, renova tokens, verifica e revoga sessões e executa step-ups.

> [!NOTE]
>
> A verificação de tokens faz as checagens descritas em [Verificar um token no seu servidor](https://docs.didit.me/pt-br/authentication/tokens-and-jwks.md#verificar-um-token-no-seu-servidor), usando o emissor e as chaves de assinatura da sua aplicação.

```typescript theme={null}
import { Authentication, TokenVerificationError } from "@didit-protocol/sdk-node";

// The publishable key (pk_live_... or pk_test_...) carries your issuer URL.
const auth = Authentication.fromPublishableKey("pk_live_...", { clientId: "your-application-id" });

export async function currentUser(accessToken: string): Promise<string | null> {
  try {
    const claims = await auth.verifyAccessToken(accessToken);
    return claims.sub;
  } catch (error) {
    if (error instanceof TokenVerificationError) return null;
    throw error;
  }
}
```

## Erros

```typescript theme={null}
import Didit, { APIStatusError, NotFoundError, RateLimitError } from "@didit-protocol/sdk-node";

const didit = new Didit();

try {
  await didit.sessions.retrieveDecision("11111111-2222-3333-4444-555555555555");
} catch (error) {
  if (error instanceof NotFoundError) console.log("no such session");
  else if (error instanceof RateLimitError) console.log("slow down, request", error.requestId);
  else if (error instanceof APIStatusError) console.log(error.status, error.body);
  else throw error;
}
```

## Listas e arquivos

```typescript theme={null}
import Didit, { fileFromPath } from "@didit-protocol/sdk-node";

const didit = new Didit();

// Lists page through every result.
for await (const session of didit.sessions.list({ status: "Approved" })) {
  console.log(session.session_id);
}

// Uploads take a Blob, a Buffer, a stream or fileFromPath.
const result = await didit.idVerification.verify({
  front_image: await fileFromPath("id-front.jpg"),
  back_image: await fileFromPath("id-back.jpg"),
});
console.log(result.id_verification);
```

As páginas de endpoints de servidor da [referência da API](https://docs.didit.me/pt-br/api-reference/overview.md) têm um exemplo em Node.js para a operação correspondente, exceto para os endpoints e campos que ainda não existem em nenhuma versão 1.0.1 lançada, listados na [visão geral](https://docs.didit.me/pt-br/integration/server-sdks/overview.md).


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