> ## 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 검증, 인증 토큰 확인을 다룹니다.

Didit의 공식 Node.js 및 TypeScript 라이브러리입니다. Node.js 18 이상, Bun, Deno, 그리고 `fetch`를 사용하는 엣지 런타임에서 실행되며, ES 모듈과 CommonJS 빌드를 함께 제공하고 런타임 종속성이 없습니다. 모든 SDK가 공유하는 내용은 [서버 SDK 개요](https://docs.didit.me/ko/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/ko/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/ko/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]`를 모두 전달하십시오. 이벤트와 서명 방식은 [웹훅](https://docs.didit.me/ko/integration/webhooks.md)을 참고하십시오.

## 거래 스크리닝

결제, 출금 또는 암호화폐 전송을 [거래 모니터링](https://docs.didit.me/ko/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 토큰 검증

`Authentication`은 백엔드에서 [Authentication](https://docs.didit.me/ko/authentication/overview.md) 발급자가 서명한 액세스 토큰을 검증하며, 요청마다 Didit을 호출하지 않습니다. 또한 코드를 교환하고, 토큰을 갱신하고, 세션을 확인하고 해지하며, 추가 인증을 실행합니다.

> [!NOTE]
>
> 토큰 검증은 애플리케이션의 발급자와 서명 키를 기준으로 [서버에서 토큰 검증하기](https://docs.didit.me/ko/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/ko/api-reference/overview.md)의 서버 엔드포인트 페이지에는 해당 작업의 Node.js 샘플이 있습니다. 다만 1.0.1 릴리스에 아직 포함되지 않은 엔드포인트와 필드는 예외이며, 이는 [개요](https://docs.didit.me/ko/integration/server-sdks/overview.md)에 명시되어 있습니다.


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