> ## 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 per KYC e AML

> SDK ufficiale Didit per Node.js e TypeScript: chiamate tipizzate alle API, verifica dei webhook e controllo dei token di autenticazione.

La libreria ufficiale di Didit per Node.js e TypeScript. Funziona con Node.js 18 o versioni successive, Bun, Deno e runtime edge con `fetch`, distribuisce build di moduli ES e CommonJS e non ha dipendenze di runtime. Per ciò che tutti gli SDK server condividono, consulta la [panoramica degli SDK server](https://docs.didit.me/it/integration/server-sdks/overview.md).

## Installazione

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

Il pacchetto è [`@didit-protocol/sdk-node` su npm](https://www.npmjs.com/package/@didit-protocol/sdk-node). Il codice sorgente e il registro delle modifiche si trovano in [didit-protocol/sdk-node](https://github.com/didit-protocol/sdk-node) su GitHub.

## Configurare il client

`new Didit()` legge `DIDIT_API_KEY` dalle variabili d'ambiente su Node.js, Bun e Deno (con `--allow-env`). I runtime edge non hanno un ambiente di processo, quindi lì passa la chiave come opzione: `new Didit({ apiKey: env.DIDIT_API_KEY })`. Passa delle opzioni per sovrascrivere questo valore, oppure per impostare gli ID di organizzazione e applicazione che le chiamate con ambito applicativo (casi, reti, report normativi) richiedono. Il timeout è espresso in millisecondi.

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

## Creare una sessione

Crea una [sessione di verifica](https://docs.didit.me/it/sessions-api/create-session.md) per un workflow e invia il tuo utente al relativo URL. I campi della richiesta mantengono i nomi propri dell'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);
```

## Leggere la decisione

Quando l'utente completa il processo (oppure quando arriva il webhook), [leggi la decisione](https://docs.didit.me/it/sessions-api/retrieve-session.md). Ogni risultato delle funzionalità è una lista con una voce per ogni nodo del workflow, e le date e gli orari sono oggetti `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);
}
```

## Verificare un webhook

Passa il corpo grezzo (non il JSON analizzato) e le intestazioni della richiesta: un oggetto `req.headers` di Node.js o Express, un oggetto `Headers` di Fetch oppure coppie `[name, value]` (il tipo `WebhookHeaders`). `verify` restituisce una promise e rifiuta con `WebhookVerificationError` qualsiasi consegna che non sia valida 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;
  }
}
```

Con Express, leggi il corpo con `express.raw({ type: "application/json" })` e chiama `handleWebhook(req.body, req.headers)`. Mentre ruoti il segreto, passa entrambi: `[newSecret, oldSecret]`. Per gli eventi e lo schema di firma, consulta [Webhook](https://docs.didit.me/it/integration/webhooks.md).

## Sottoporre una transazione a screening

Invia un pagamento, un prelievo o un trasferimento di criptovalute al [monitoraggio delle transazioni](https://docs.didit.me/it/transaction-monitoring/overview.md); la risposta riporta il relativo stato e il punteggio di rischio.

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

## Verificare i token di Authentication

`Authentication` verifica i token di accesso firmati dal tuo emittente [Authentication](https://docs.didit.me/it/authentication/overview.md), nel tuo backend, senza chiamare Didit per ogni richiesta. Inoltre scambia i codici, rinnova i token, verifica e revoca le sessioni ed esegue i flussi di step-up.

> [!NOTE]
>
> La verifica dei token esegue i controlli descritti in [Verifica un token sul tuo server](https://docs.didit.me/it/authentication/tokens-and-jwks.md#verifica-un-token-sul-tuo-server), con l'emittente e le chiavi di firma della tua applicazione.

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

## Errori

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

## Liste e file

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

Le pagine degli endpoint server del [riferimento API](https://docs.didit.me/it/api-reference/overview.md) includono un esempio Node.js per la rispettiva operazione, ad eccezione degli endpoint e dei campi che non sono ancora presenti in alcuna release 1.0.1, indicati nella [panoramica](https://docs.didit.me/it/integration/server-sdks/overview.md).


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