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

# Verifica aziendale (KYB): guida rapida in 10 minuti

> Con Didit verifica un'azienda in meno di 10 minuti: registro, UBO, amministratori, AML e webhook. Da $2.00 per controllo, senza contratti.

This guide walks you through a complete KYB verification in under 10 minutes. You'll create a workflow, start a session, deliver the hosted verification link to your business contact, wait for the webhook, and fetch the final decision.

## Prerequisiti

* Un'applicazione Didit con KYB abilitato. Creane una su [business.didit.me](https://business.didit.me), se necessario.
* Una chiave API da *Developer Settings → API Keys*.
* Un endpoint webhook raggiungibile da internet (per il webhook della decisione).

## Passaggi

**1. Crea un workflow KYB nella console**

Vai a *Workflows → Create workflow*. Scegli **Verifica aziendale** come tipo di workflow.

Attiva le funzionalità che ti servono:

* **Ricerca nel registro delle imprese** (obbligatoria)
* **AML aziendale** (consigliata)
* **persone chiave** (obbligatoria per la maggior parte dei settori regolamentati)
* **Documenti** (facoltativo: scegli i tipi di documento che richiederai)

Salva e copia il `workflow_id`: ti servirà nel passaggio successivo.

**2. Crea una sessione di Verifica aziendale (KYB) tramite l'API**

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "YOUR_KYB_WORKFLOW_ID",
    "vendor_data": "biz-acme-001"
  }'
```

La risposta contiene `session_id`, `session_number` e `url`, cioè il link di verifica alla pagina di verifica ospitata che consegni al referente dell'azienda. Il tipo di workflow (KYB) contrassegna automaticamente la sessione come sessione aziendale.

**3. Invia il link al referente dell'azienda**

Invia il `url` all'amministratore dell'azienda tramite la tua email o chat. Apre il link, compila i dati del registro, aggiunge persone chiave e UBO e carica i documenti.

Puoi personalizzare l'esperienza della pagina ospitata con branding, logo e dominio: vedi [White label](https://docs.didit.me/it/console/white-label.md).

**4. Ricevi il webhook dello stato**

Quando l'azienda completa il flusso e l'elaborazione KYB raggiunge uno stato finale, Didit invia una richiesta POST con un evento `status.updated` al tuo endpoint webhook. Gli eventi delle sessioni aziendali contengono `session_kind: "business"` all'interno di `data`: filtra su questo valore per indirizzare l'evento al tuo gestore KYB.

Verifica la firma HMAC `X-Signature-V2` prima di considerare attendibile l'evento (vedi [webhook](https://docs.didit.me/it/integration/webhooks.md)), poi avvia la logica a valle. Salva il `secret_shared_key` della destinazione webhook (restituito quando registri il webhook) come `DIDIT_WEBHOOK_SECRET` nel tuo `.env`.

Esempio di payload:

```json theme={null}
{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "vendor_data": "biz-acme-001",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "decision": { "...": "full KYB decision" }
}
```

**5. Recupera la decisione (facoltativo)**

> [!NOTE]
>
> Il payload del webhook `status.updated` contiene già la decisione completa. Devi chiamare questo endpoint solo se non ti sei iscritto ai webhook, oppure se vuoi recuperare la decisione su richiesta in un secondo momento.

```bash theme={null}
curl https://verification.didit.me/v3/session/bs_01H.../decision/ \
  -H "x-api-key: YOUR_API_KEY"
```

La decisione include i dati del registro, le persone chiave (UBO, azionisti, amministratori e rappresentanti), i riscontri AML, i documenti e i risultati per ciascuna funzionalità. Consulta lo [schema della risposta](https://docs.didit.me/it/business-verification/response-schema.md) per il riferimento completo del payload.

**6. Agisci in base alla decisione**

In base a `status`:

* `"Approved"`: avvia l'onboarding dell'azienda.
* `"Declined"`: rifiuta l'azienda e registra i tag `warnings[]` della decisione.
* `"In Review"`: attendi la decisione dell'analista; riceverai un altro webhook quando sarà risolta.

## Esempio Node.js

```typescript theme={null}
import fetch from 'node-fetch';

const API_KEY = process.env.DIDIT_API_KEY!;
const WORKFLOW_ID = process.env.DIDIT_KYB_WORKFLOW_ID!;
const BASE_URL = 'https://verification.didit.me';

async function startKybVerification(vendorData: string) {
  const res = await fetch(`${BASE_URL}/v3/session/`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ workflow_id: WORKFLOW_ID, vendor_data: vendorData }),
  });
  if (!res.ok) throw new Error(`Session create failed: ${res.status}`);
  return res.json();
}

async function getDecision(sessionId: string) {
  const res = await fetch(`${BASE_URL}/v3/session/${sessionId}/decision/`, {
    headers: { 'x-api-key': API_KEY },
  });
  return res.json();
}

// Kick off the flow
const { session_id, url } = await startKybVerification('biz-acme-001');
console.log('Deliver this URL to your contact:', url);

// ... later, after the webhook confirms completion:
const decision = await getDecision(session_id);
console.log('KYB status:', decision.status);
```

## Cosa succede automaticamente

* Ricerca nel registro delle imprese in 190+ giurisdizioni.
* Estrazione di UBO e amministratori dai dati del registro.
* Screening AML a livello aziendale (sanzioni, PEP, notizie negative).
* AML a livello di persona per ogni soggetto identificato.
* OCR dei documenti e incrocio dei dati.
* Creazione e aggregazione dei [profili aziendali](https://docs.didit.me/it/business-verification/business-profiles.md) basate su `vendor_data`.

## Prossimi passi

> [card] [Guida all'integrazione](https://docs.didit.me/it/business-verification/integration-guide.md)
>
> Architettura end-to-end, polling rispetto all'uso dei webhook, logica di retry.

> [card] [Webhook KYB](https://docs.didit.me/it/business-verification/webhooks.md)
>
> Ogni evento KYB e la struttura del relativo payload.

> [card] [Stati](https://docs.didit.me/it/business-verification/statuses.md)
>
> Riferimento per gli stati di sessione, funzionalità e registro.

> [card] [Schema della risposta](https://docs.didit.me/it/business-verification/response-schema.md)
>
> Il payload completo della decisione KYB.

> [card] [Entità aziendali](https://docs.didit.me/it/entities/businesses/overview.md)
>
> Come i profili si aggregano tra le sessioni.


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