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

# Esempi MCP di Didit: prompt e conversazioni con agenti

> Esempi di prompt e conversazioni con agenti tramite il MCP di Didit: workflow KYC, ricerca KYB, coda di revisione, back-test delle regole e webhook.

Una serie di esempi che mostrano cosa sa fare bene l'MCP di Didit. Formula le richieste in linguaggio naturale: l'agente sceglie gli strumenti. Ogni strumento citato sotto esiste nel [riferimento degli strumenti](https://docs.didit.me/it/integration/mcp/tools.md).

***

## Prompt rapidi

**Operazioni e monitoraggio (tra tutte le app)**

* *"Mostrami le ultime 5 sessioni in revisione di tutte le mie app."* → `didit_session_search` con `status: "In Review"`, `limit: 5`
* *"Quante persone hanno provato la verifica telefonica ma hanno abbandonato negli ultimi 15 giorni?"* → `didit_analytics` con `last_n_days: 15` (una sola chiamata; legge il funnel delle funzionalità)
* *"Trova il cliente con vendor\_data `user_8842` e dimmi quale app e quale stato ha."* → `didit_vendor_user_search`
* *"Qual è il mio saldo crediti e il tasso di conversione di questo mese?"* → `didit_org_get_balance` + `didit_analytics`

**Configurazione**

* *"Crea un workflow KYC con scansione del documento d'identità + rilevamento della vitalità e dammi un link di verifica."* → `didit_workflow_create` → `didit_session_create`
* *"Crea un workflow di verifica dell'identità che accetti solo passaporti, seguito da un rilevamento della vitalità con selfie."* → `didit_workflow_create`: indica semplicemente `documents_allowed: ["PASSPORT"]`; l'MCP lo espande in modo da accettare solo passaporti in ogni paese (vedi [Avanzate → configurazioni delle funzionalità](https://docs.didit.me/it/integration/mcp/advanced.md#configurazioni-delle-funzionalità-e-liste-di-valori-consentiti)).
* *"Nuovo workflow: scansiona un passaporto; se il documento viene rifiutato, rifiuta la sessione; se la professione dichiarata è ≈ 'Software Engineer' (≥60%), esegui un rilevamento della vitalità; altrimenti chiedi una prova di residenza in spagnolo; poi decidi automaticamente."* → `didit_workflow_get_field_definitions` → `didit_workflow_validate_graph` → `didit_workflow_set_graph`
* *"Nel workflow `26d33c04…`, dopo la verifica dell'identità: se viene rifiutata, rifiuta la sessione; se la professione è simile al 'Software Engineer' per almeno l'80%, aggiungi un passaggio Document AI per la prova dei fondi; poi continua."* → `didit_workflow_search` → `didit_workflow_get_graph` → `didit_workflow_edit_graph` (piccole modifiche, salvate come bozza da rivedere)
* *"In quali paesi posso offrire l'accesso con BankID o MitID al posto della scansione di un documento?"* → `didit_workflow_get_id_verification_methods_catalog`
* *"Registra una destinazione webhook per gli aggiornamenti di stato su `https://myapp.com/webhooks/didit`."* → `didit_webhook_create`

**Conformità**

* *"Esegui lo Screening AML di questo wallet e aggiungilo alla blocklist se risulta un riscontro."* → `didit_transaction_screen_wallet` → `didit_blocklist_add`
* *"Apri un caso per la sessione `…` e assegnalo a me."* → `didit_case_create` → `didit_case_manage`
* *"Acme Ltd è un'azienda registrata nel Regno Unito e, in tal caso, chi sono i suoi azionisti?"* → `didit_verify_kyb_search` → `didit_verify_kyb_select`

***

## 1. Configurare la verifica

> **Tu:** "Configura la verifica dell'identità di Didit per la mia app con scansione del documento e rilevamento della vitalità, e dammi un link con cui provarla."
>
> **Agente:** Creo prima il workflow. *(chiama `didit_workflow_create` con `workflow_label: "Standard KYC"`, `features: [{ "feature": "OCR" }, { "feature": "LIVENESS" }]`)* — Pubblicato **"Standard KYC"**, `workflow_id = 6f2c…`. Ora una sessione per provarlo. *(chiama `didit_session_create` con `workflow_id: "6f2c…"`, `vendor_data: "test-user-1"`)* — Ecco il tuo link: `https://verify.didit.me/session/…`. Aprilo sul tuo telefono per eseguire il flusso. In produzione il tuo backend crea le sessioni con la REST API:
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
>   -H "x-api-key: $DIDIT_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{ "workflow_id": "6f2c...", "vendor_data": "internal-user-id", "callback": "https://myapp.com/done" }'
> ```
>
> Quella `x-api-key` è la **chiave API REST** della tua applicazione per il tuo backend; è separata da come hai effettuato l'accesso a questo MCP, che usa *Accedi con Didit*. Vuoi che registri anche la destinazione webhook?
>
> **Tu:** "Sì, il mio endpoint è `https://myapp.com/webhooks/didit`."
>
> **Agente:** *(chiama `didit_webhook_create` con `label: "Production"`, `url: "https://myapp.com/webhooks/didit"`, `webhook_version: "v3"`, `subscribed_events: ["status.updated"]`)* — Fatto. Il segreto di firma è oscurato nella risposta che ricevo, quindi copialo da **Webhooks** nella console e conservalo come `DIDIT_WEBHOOK_SECRET`. Verifica l'intestazione `X-Signature-V2` su ogni consegna prima di fidartene.

***

## 2. KYB: verifica un'azienda nel registro delle imprese

> **Tu:** "Acme Trading Ltd è davvero un'azienda del Regno Unito? Il numero di registrazione è 12345678."
>
> **Agente:** *(chiama `didit_verify_kyb_search` con `country_code: "GB"`, `name: "Acme Trading Ltd"`, `registration_number: "12345678"`)* — Un solo candidato: **ACME TRADING LTD**, costituita nel 2019, stato *attivo*, sede legale a Manchester. Vuoi la scheda completa con amministratori e azionisti?
>
> **Tu:** "Sì, e dimmi chi sono i titolari effettivi."
>
> **Agente:** *(chiama `didit_verify_kyb_select` con il `kyb_response_id` del candidato)* — Scheda completa recuperata: due amministratori e una persona con controllo significativo che detiene il 75%+ delle azioni e dei diritti di voto. La scheda include lo storico delle pratiche depositate e la sede legale. Questa è stata una consultazione del registro a pagamento (due chiamate che consumano crediti). Se vuoi che questo avvenga automaticamente per ogni cliente aziendale, posso aggiungere `KYB_REGISTRY` a un workflow KYB con `didit_workflow_create`; `didit_workflow_get_kyb_registry_catalog` indica quali livelli di dati vende il registro del Regno Unito.

***

## 3. Gestisci la coda delle revisioni

> **Tu:** "Cosa attende la mia revisione e cosa non va in ciascuna?"
>
> **Agente:** *(chiama `didit_session_search` con `status: "In Review"`, `limit: 10`)* — Quattro sessioni in due applicazioni sono in revisione. Lettura della decisione per ciascuna. *(chiama `didit_session_get_decision` per ogni `session_id`)*
>
> | Sessione | Applicazione | Motivo della sospensione |
> | - | - | - |
> | `a1f3…` | Onboarding | Punteggio di confronto facciale 71 (soglia 80), rilevamento della vitalità superato |
> | `b7c2…` | Onboarding | Documento scaduto due mesi fa |
> | `c904…` | Marketplace | AML: una corrispondenza PEP, corrispondenza del nome 92%, data di nascita diversa |
> | `d215…` | Marketplace | Prova di residenza più vecchia di 90 giorni |
>
> **Tu:** "Approva `a1f3`: ho guardato il selfie ed è la stessa persona. Rifiuta `b7c2`, documento scaduto."
>
> **Agente:** *(chiama `didit_session_update_status` con `session_id: "a1f3…"`, `new_status: "Approved"`, poi con `session_id: "b7c2…"`, `new_status: "Declined"`, `comment: "Expired document"`)* — Entrambe aggiornate. *(chiama `didit_session_add_review` su `a1f3…` con la nota "Revisione manuale del selfie: stessa persona")* — Nota di revisione aggiunta, così il registro di audit mostra perché il punteggio è stato sovrascritto. I due casi AML e di prova di residenza restano aperti; dimmelo e aprirò un caso per la corrispondenza PEP con `didit_case_create`.

***

## 4. Simula una regola sulle transazioni prima che entri in produzione

> **Tu:** "Voglio segnalare chiunque effettui più di 3 trasferimenti superiori a \$1,000 in un'ora. Quanti falsi positivi genererebbe questa regola?"
>
> **Agente:** *(chiama `didit_transaction_rule_backtest` con `conditions` su `amount > 1000`, un `aggregation` di conteggio ≥ 3 su una finestra di 1 ora, `period_days: 90`)* — Negli ultimi 90 giorni la regola sarebbe scattata su 14 transazioni di 6 soggetti; 2 di questi soggetti sono già segnalati. Vuoi che la crei in modalità `TEST`, così registra le corrispondenze senza eseguire alcuna azione?
>
> **Tu:** "Sì, modalità TEST."
>
> **Agente:** *(chiama `didit_transaction_rule_create` con `title: "Velocity: 3+ transfers over $1,000 per hour"`, `category: "aml_ctf"`, `mode: "TEST"`, gli stessi `conditions` e `aggregation`, e una lista `actions` che segnala il soggetto)* — Creata. Osservala con `didit_transaction_rule_get` dopo qualche giorno; quando sei soddisfatto, `didit_transaction_rule_update` cambia `mode` in `ACTIVE`. `didit_transaction_rule_library_list` contiene anche regole predefinite di frequenza di Didit, se preferisci installarne una.

***

## I risultati della sessione sono asincroni

`didit_session_create` restituisce un `session_id`, un `session_token` e un `url` ospitato, ma la verifica non è ancora avvenuta. L'utente apre `url` e completa il flusso. La decisione finale arriva tramite:

1. Un **webhook** `status.updated` (consigliato), oppure
2. `didit_session_get_decision` (polling, come soluzione di ripiego).

Entrambi hanno la stessa struttura: **sempre array al plurale** con un `node_id` per ogni voce:

```json theme={null}
{
  "session_id": "uuid",
  "status": "Approved",
  "session_kind": "user",
  "id_verifications":  [ { "node_id": "first_id", "status": "Approved", "first_name": "Jane" } ],
  "liveness_checks":   [ { "node_id": "first_liveness", "status": "Approved", "score": 95.4 } ],
  "face_matches":      [ { "node_id": "first_face_match", "status": "Approved", "score": 96.1 } ],
  "aml_screenings":    [ { "node_id": "first_aml", "status": "Approved", "total_hits": 0, "hits": [] } ],
  "reviews": []
}
```

Non leggere mai le chiavi singolari della V2 (`id_verification`, `liveness`): compaiono solo quando una destinazione è esplicitamente impostata su `webhook_version: "V2"`. Per il riferimento ai campi di ciascuna funzionalità, vedi [Modelli dei dati](https://docs.didit.me/it/reference/data-models.md), e per le regole di verifica e nuovo tentativo vedi [Avanzate → Webhook](https://docs.didit.me/it/integration/mcp/advanced.md#gestione-dei-webhook).

***

## Abbinalo all'integrazione con un solo prompt

L'MCP è ideale per *far funzionare* Didit. Per far scrivere a un agente un'integrazione completa (route backend + SDK frontend + gestore webhook + schema del database), passagli il [Prompt di integrazione](https://docs.didit.me/it/integration/integration-prompt.md): segue i sette passaggi e chiama gli strumenti MCP per creare in tempo reale il workflow, la sessione e il webhook.

***

> [card] [Riferimento degli strumenti](https://docs.didit.me/it/integration/mcp/tools.md)
>
> Tutto ciò che l'agente può chiamare.

> [card] [Funzionalità avanzate e risoluzione dei problemi](https://docs.didit.me/it/integration/mcp/advanced.md)
>
> Ruoli, comportamento tra applicazioni, webhook, hosting autonomo.


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