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

# Didit Node.js 与 TypeScript SDK：KYC 与 AML 集成

> Didit 官方 Node.js 与 TypeScript SDK 快速入门：为服务端 API 提供类型化调用、Webhook 验证和 Authentication 令牌校验。

官方 Didit 库，适用于 Node.js 和 TypeScript。它支持 Node.js 18 或更高版本、Bun、Deno，以及使用 `fetch` 的边缘运行时，同时提供 ES 模块和 CommonJS 两种构建，且没有运行时依赖。各 SDK 的共同内容请参阅[服务端 SDK 概览](https://docs.didit.me/zh/integration/server-sdks/overview.md)。

## 安装

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

该包在 npm 上名为 [`@didit-protocol/sdk-node`](https://www.npmjs.com/package/@didit-protocol/sdk-node)。其源代码和更新日志位于 GitHub 上的 [didit-protocol/sdk-node](https://github.com/didit-protocol/sdk-node)。

## 配置客户端

在 Node.js、Bun 和 Deno（需要 `--allow-env`）上，`new Didit()` 会从环境变量中读取 `DIDIT_API_KEY`。边缘运行时没有进程环境，因此需要通过选项传入密钥：`new Didit({ apiKey: env.DIDIT_API_KEY })`。您可以传入选项来覆盖默认值，也可以设置组织 ID 和应用 ID，这是应用级调用（案件、网络、监管报告）所必需的。超时时间以毫秒为单位。

```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"));
```

使用 CommonJS 时，请写 `const { Didit } = require("@didit-protocol/sdk-node");`。

## 创建会话

为工作流创建一个[验证会话](https://docs.didit.me/zh/sessions-api/create-session.md)，并将用户引导至该会话的 URL。请求字段保留 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);
```

## 读取决策结果

用户完成操作后（或 Webhook 到达时），[读取决策结果](https://docs.didit.me/zh/sessions-api/retrieve-session.md)。每个功能结果都是一个列表，每个工作流节点对应一个条目，日期时间均为 `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);
}
```

## 验证 Webhook

请传入原始请求体（而非解析后的 JSON）以及请求头：可以是 Node.js 或 Express 的 `req.headers` 对象、Fetch 的 `Headers` 对象，或 `[name, value]` 键值对（`WebhookHeaders` 类型）。`verify` 返回一个 Promise，对于任何不是有效且未过期的投递，都会以 `WebhookVerificationError` 拒绝。

```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;
  }
}
```

在 Express 中，使用 `express.raw({ type: "application/json" })` 读取请求体，并调用 `handleWebhook(req.body, req.headers)`。轮换密钥期间，请同时传入两个密钥：`[newSecret, oldSecret]`。有关事件和签名方案，请参阅 [Webhook](https://docs.didit.me/zh/integration/webhooks.md)。

## 筛查交易

将支付、提现或加密货币转账提交至[交易监控](https://docs.didit.me/zh/transaction-monitoring/overview.md)，响应中包含其状态和风险评分。

```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);
```

## 验证 Authentication token

`Authentication` 可在您的后端检查您的 [Authentication](https://docs.didit.me/zh/authentication/overview.md) 颁发方签发的访问 token，无需为每个请求调用 Didit。它还可以交换授权码、刷新 token、检查和撤销会话，并执行升级验证。

> [!NOTE]
>
> token 验证会根据您应用的颁发方和签名密钥，执行 [在您的服务器上验证 token](https://docs.didit.me/zh/authentication/tokens-and-jwks.md#在服务器上验证令牌) 中描述的检查。

```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;
  }
}
```

## 错误

```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;
}
```

## 列表与文件

```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);
```

[API 参考](https://docs.didit.me/zh/api-reference/overview.md) 中的服务端 endpoint 页面，均为其操作提供了 Node.js 示例，但 1.0.1 版本尚未提供的 endpoint 和字段除外，这些内容在[概览](https://docs.didit.me/zh/integration/server-sdks/overview.md)中有列明。


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