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

# Integrazione del Monitoraggio delle transazioni: API KYT

> Architettura e best practice KYT: tempo reale vs batch, parti, idempotenza, importazione storica, webhook. 1,000 al mese inclusi, poi $0.001 ciascuno.

Questa guida copre l'intero ambito di integrazione del Monitoraggio delle transazioni. La [guida rapida](https://docs.didit.me/it/transaction-monitoring/quickstart.md) ti permette di iniziare; questa pagina ti accompagna fino all'ambiente di produzione.

## Architettura

```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Rules as Rule engine
    participant AML as AML providers
    participant Webhook as Your webhook

    You->>Didit: POST /v3/transactions/ (txn_id, parties, amount)
    Didit->>Didit: IP enrichment (inline)
    Didit->>AML: Screen wallet or transaction hash + address
    AML-->>Didit: Hits / clean
    Didit->>Rules: Evaluate all active rules
    Rules-->>Didit: Score + matched rules + actions
    Didit-->>You: Transaction record with status
    Didit->>Webhook: transaction.created
    Didit->>Webhook: transaction.status.updated (if async rules)
```

## Autenticazione

Intestazione standard `x-api-key`. Le stesse chiavi sono usate per sessioni ed entità. Vedi [autenticazione API](https://docs.didit.me/it/getting-started/api-authentication.md).

## Invio di una transazione

Endpoint unico: `POST /v3/transactions/`. Vedi [invio delle transazioni](https://docs.didit.me/it/transaction-monitoring/transactions.md) per lo schema completo.

**Payload minimo:**

```json theme={null}
{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}
```

**Payload più ricco con metodi di pagamento, contesto del dispositivo e proprietà personalizzate:**

```json theme={null}
{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}
```

Gli alias in camelCase sono accettati per ogni campo di primo livello (`txnId`, `txnDate`, `type`, `info`, `applicant`, `props`, `travelRule`, `includeCryptoScreening`): il formato wire dell'SDK e il formato snake\_case vengono interpretati allo stesso modo.

## Modellazione delle parti

Ogni transazione ha un `subject` obbligatorio (il tuo cliente, cioè la parte che monitori) e un `counterparty` facoltativo (l'altra parte). Ciascuno ha il proprio `payment_method` e un contesto `device` facoltativo.

Nella risposta, le parti arrivano nell'array `parties` con i ruoli `APPLICANT` e `COUNTERPARTY`; una parte senza `vendor_data` viene memorizzata come snapshot esterno (`kind: EXTERNAL`), senza entità collegata.

Vedi [payload delle transazioni](https://docs.didit.me/it/transaction-monitoring/transactions.md) per i campi delle parti.

## Idempotenza

`txn_id` (il `transaction_id` che invii) è univoco per applicazione.
Reinviare un `transaction_id` già esistente restituisce `400` con `A transaction with this transaction_id already exists.` nel campo `transaction_id`; quando due richieste identiche arrivano in concorrenza, la seconda riceve `409`.
Nessuna delle due risposte restituisce la transazione esistente.
In caso di `400` o `409` per un `transaction_id` duplicato, cerca la transazione esistente invece di reinviarla: leggila con [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/it/management-api/transactions/get) usando l'`uuid` della prima risposta, oppure usa il `transaction_id` (l'uuid Didit) che il webhook `transaction.created` riporta accanto al tuo `txn_id`.

**Genera sempre `txn_id` dal tuo lato** prima dell'invio; non fare affidamento su un ID generato da Didit per l'idempotenza. Usa l'ID del tuo database, un UUID o un hash dei campi della transazione.

## Tempo reale vs batch

* **Tempo reale**: consigliato per la maggior parte dei casi d'uso. Invia la transazione nel momento in cui avviene nel tuo sistema. Le regole vengono valutate in modo sincrono e restituiscono la decisione.
* **Batch / backfill**: per l'importazione dello storico, passa `txn_date` nel passato. Le regole vengono comunque eseguite e possono attivare webhook. Per evitare che le regole si attivino durante il backfill, usa l'importazione CSV della console con il flag "dry ingest".

## Importazione dello storico

Quando stai migrando da un altro sistema di monitoraggio delle transazioni:

1. Esporta le transazioni storiche in un CSV.
2. Usa *Transactions → Import history* nella console (oppure invia tramite API in un ciclo) con `txn_date` nel passato.
3. Attiva le regole solo dopo il termine dell'importazione, oppure usa dry ingest per saltare la valutazione delle regole.

> [!WARNING]
>
> Fai attenzione alla valutazione storica delle regole. Far passare 6 mesi di storico attraverso una regola "20 trasferimenti in 30 giorni" genererà migliaia di alert in una sola volta.

## Webhook

Iscriviti a:

* `transaction.created`: ogni transazione inviata.
* `transaction.status.updated`: cambi di stato (ad esempio l'analista passa da `IN_REVIEW` ad `APPROVED`, oppure un controllo AML asincrono aggiorna il punteggio).

Dettagli completi: [webhook TM](https://docs.didit.me/it/transaction-monitoring/webhooks.md).

```typescript theme={null}
app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});
```

## Gestione degli stati

| Stato | Cosa fare |
| - | - |
| `APPROVED` | Elabora la transazione normalmente. |
| `IN_REVIEW` | Trattieni la transazione finché la revisione dell'analista o il nuovo controllo automatico non si conclude. |
| `DECLINED` | Rifiuta la transazione. Mostra all'utente un errore generico. |
| `AWAITING_USER` | L'utente deve agire prima che la transazione possa essere regolata: leggi il blocco `action_required` e invia il suo `url` all'utente (gli SDK possono [gestire questo passaggio automaticamente](https://docs.didit.me/it/transaction-monitoring/sdk-transaction-submission.md#azioni-richieste-all’utente)). |

Vedi [stati TM](https://docs.didit.me/it/transaction-monitoring/statuses.md).

## Collegamento delle transazioni alle entità

Passa `vendor_data` su ogni parte. Vantaggi:

* Ogni transazione confluisce nel profilo Utente o Azienda.
* Le regole di frequenza e quelle comportamentali hanno a disposizione la cronologia completa su cui basare la valutazione.
* Il blocco di un'entità si propaga automaticamente alle transazioni future.

L'assenza di `vendor_data` non è un errore bloccante: la transazione viene memorizzata come snapshot esterno, ma perdi l'aggregazione a livello di entità.

## Sessioni di rimedio

Quando un'azione di una regola sposta una transazione in `AWAITING_USER`, Didit crea automaticamente una **sessione di rimedio**, ovvero una normale sessione di verifica ospitata per lo stesso `vendor_data`.
Le regole personalizzate indicano sempre il workflow direttamente nell'azione; per le regole della libreria integrata, viene utilizzato il [workflow di rimedio nelle impostazioni delle transazioni](https://docs.didit.me/it/transaction-monitoring/settings.md#workflow-di-remediation), poi il workflow di Autenticazione biometrica della tua applicazione (quando il soggetto ha un volto di riferimento memorizzato), e infine il workflow predefinito della tua applicazione.
Le transazioni Travel Rule sono escluse da questo ricorso automatico: la loro azione in sospeso è la prova di titolarità del wallet.
La transazione (la risposta, ogni lettura successiva e ogni webhook) riporta la sessione nel blocco canonico `action_required`:

```json theme={null}
{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}
```

`remediation` è mantenuto per compatibilità con le versioni precedenti; `action_required` è il blocco canonico (include anche le azioni `wallet_ownership` per i trasferimenti [Travel Rule](https://docs.didit.me/it/transaction-monitoring/travel-rule.md)).
Un'azione `wallet_ownership` non modifica da sola lo stato della transazione: la transazione mantiene lo stato assegnato dalle tue regole, spesso `APPROVED`, quindi controlla `action_required` in ogni risposta, non solo quando lo stato è `AWAITING_USER`.

L'utente completa la verifica: per un workflow di **Autenticazione biometrica**, un selfie con controllo di vitalità confrontato con il volto acquisito durante l'onboarding KYC originale, il livello di autenticazione rafforzata più elevato per le [transazioni di alto valore](https://docs.didit.me/it/transaction-monitoring/sdk-transaction-submission.md#esempio-verifica-biometrica-rafforzata-per-un-prelievo-di-alto-valore).
Quando la sessione raggiunge una decisione, la transazione la segue automaticamente: `APPROVED` (`decision_reason_code: user_action_approved`), `DECLINED` (`user_action_declined`) o `IN_REVIEW` (`user_action_in_review`), e viene inviato un webhook `transaction.status.updated`.

> [!NOTE]
>
> È possibile selezionare qualsiasi tipo di workflow tranne KYB.
> I workflow di Autenticazione biometrica (e i workflow in cui il confronto facciale viene eseguito prima della verifica del documento d'identità) richiedono che il soggetto abbia già un volto di riferimento memorizzato da una verifica approvata; gli utenti che non ne hanno uno vengono indirizzati al workflow predefinito della tua applicazione, con una nota sulla transazione che registra la sostituzione.

## Best practice

| Pratica | Perché |
| - | - |
| Passa sempre `vendor_data` | Consente l'aggregazione. |
| Usa il tuo `txn_id` | Idempotenza. |
| Iscriviti sia a `transaction.created` sia a `transaction.status.updated` | Intercetta i cambiamenti di stato asincroni (ad esempio, gli esiti delle revisioni degli analisti). |
| Imposta le soglie delle regole in modo deliberato | Soglie basse = più alert; soglie alte = più rischi non rilevati. Vedi [punteggio di rischio](https://docs.didit.me/it/transaction-monitoring/risk-scoring.md). |
| Monitora nella console il numero di esecuzioni delle regole | Individua le regole che non si attivano mai (configurate in modo errato) o che si attivano su tutto (troppo permissive). |
| Testa le regole in modalità TEST prima di andare in produzione | Vedi [regole](https://docs.didit.me/it/transaction-monitoring/rules.md). |

## Limiti di frequenza

Vedi [limitazione della frequenza](https://docs.didit.me/it/integration/rate-limiting.md). La creazione di transazioni è uno degli endpoint con il più alto throughput; i limiti tipici si attestano nell'ordine delle centinaia di richieste al secondo. Gestisci con cautela i picchi di richieste.

## Prossimi passi

> [card] [Transazioni](https://docs.didit.me/it/transaction-monitoring/transactions.md)
>
> Riferimento completo del payload.

> [card] [Regole](https://docs.didit.me/it/transaction-monitoring/rules.md)
>
> Come vengono valutate le regole.

> [card] [Webhook](https://docs.didit.me/it/transaction-monitoring/webhooks.md)
>
> Catalogo degli eventi.

> [card] [Risoluzione dei problemi](https://docs.didit.me/it/transaction-monitoring/troubleshooting.md)
>
> Problemi comuni di integrazione.


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