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

> SDK oficial de Didit para Node.js y TypeScript: llamadas tipadas a las API de servidor, verificación de webhooks y tokens de autenticación.

La biblioteca oficial de Didit para Node.js y TypeScript. Funciona en Node.js 18 o posterior, Bun, Deno y entornos de ejecución edge con `fetch`, incluye versiones para módulos ES y CommonJS, y no tiene dependencias en tiempo de ejecución. Consulta la [visión general de los SDK de servidor](https://docs.didit.me/es/integration/server-sdks/overview.md) para ver lo que comparten todos los SDK.

## Instalación

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

El paquete es [`@didit-protocol/sdk-node` en npm](https://www.npmjs.com/package/@didit-protocol/sdk-node). Su código fuente y su registro de cambios están en [didit-protocol/sdk-node](https://github.com/didit-protocol/sdk-node) en GitHub.

## Configurar el cliente

`new Didit()` lee `DIDIT_API_KEY` del entorno en Node.js, Bun y Deno (con `--allow-env`). Los entornos de ejecución edge no tienen entorno de proceso, así que ahí pasa la clave como opción: `new Didit({ apiKey: env.DIDIT_API_KEY })`. Pasa opciones para sobrescribirla o para definir los ID de organización y de aplicación que necesitan las llamadas con ámbito de aplicación (casos, redes, informes regulatorios). El tiempo de espera se indica en milisegundos.

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

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

## Crear una sesión

Crea una [sesión de verificación](https://docs.didit.me/es/sessions-api/create-session.md) para un workflow y envía a tu usuario a su URL. Los campos de la solicitud conservan los nombres propios de la 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);
```

## Leer la decisión

Cuando el usuario termine (o cuando llegue el webhook), [lee la decisión](https://docs.didit.me/es/sessions-api/retrieve-session.md). Cada resultado de función es una lista con una entrada por cada nodo del flujo, y las fechas y horas son 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 un webhook

Pasa el cuerpo sin procesar (no el JSON ya parseado) y los encabezados de la solicitud: un objeto `req.headers` de Node.js o Express, un objeto `Headers` de Fetch o pares `[name, value]` (el tipo `WebhookHeaders`). `verify` devuelve una promesa que se rechaza con `WebhookVerificationError` ante cualquier cosa que no sea una entrega válida y reciente.

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

Con Express, lee el cuerpo con `express.raw({ type: "application/json" })` y llama a `handleWebhook(req.body, req.headers)`. Mientras rotas el secreto, pasa ambos: `[newSecret, oldSecret]`. Consulta [Webhooks](https://docs.didit.me/es/integration/webhooks.md) para conocer los eventos y el esquema de firma.

## Analizar una transacción

Envía un pago, un retiro o una transferencia de criptomonedas a la [monitorización de transacciones](https://docs.didit.me/es/transaction-monitoring/overview.md); la respuesta incluye su estado y su puntuación de riesgo.

```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` comprueba los tokens de acceso que firma tu emisor de [Authentication](https://docs.didit.me/es/authentication/overview.md), en tu backend, sin realizar una solicitud a Didit en cada solicitud. También intercambia códigos, renueva tokens, comprueba y revoca sesiones, y ejecuta verificaciones adicionales (step-ups).

> [!NOTE]
>
> La verificación de tokens realiza las comprobaciones descritas en [Verificar un token en tu servidor](https://docs.didit.me/es/authentication/tokens-and-jwks.md#verificar-un-token-en-tu-servidor), contra el emisor y las claves de firma de tu aplicación.

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

## Errores

```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 y archivos

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

Las páginas de endpoints de servidor de la [referencia de la API](https://docs.didit.me/es/api-reference/overview.md) incluyen un ejemplo en Node.js para utilizarlos, salvo los endpoints y campos que todavía no tiene ninguna versión 1.0.1, indicados en la [visión general](https://docs.didit.me/es/integration/server-sdks/overview.md).


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