> ## 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. # Configurazione funzionalità workflow: riferimento API > Riferimento di tutti i campi di configurazione accettati da POST e PATCH /v3/workflows/ per creare workflow lineari con l'array features di Didit. Usa questi campi `config` all'interno di ogni elemento dell'array `features` per [`POST /v3/workflows/`](https://docs.didit.me/it/management-api/workflows/create) e [`PATCH /v3/workflows/{settings_uuid}/`](https://docs.didit.me/it/management-api/workflows/update). ```json theme={null} { "workflow_label": "Standard KYC", "features": [ { "feature": "OCR", "config": { "documents_allowed": { "USA": { "DL": { "enabled": 1, "sides": 2 } } } } } ] } ``` L'API dei workflow v3 costruisce un workflow lineare basato su nodi a partire dall'array ordinato `features`. Invia le funzionalità nell'esatto ordine di esecuzione. > [!NOTE] > > Il motore che esegue una funzionalità, quello di Didit o quello di un provider di terze parti, non è uno dei campi config qui sotto. Viene gestito tramite il [Marketplace](https://docs.didit.me/it/console/marketplace.md) della console, che imposta per te `provider_key` e `fallback_to_native` nell'oggetto `config` della funzionalità. ## Regole di validazione * `OCR` usa tutti i paesi e tutti i tipi di documento supportati quando `config.documents_allowed` è omesso, `null` o `{}`. Se invii un oggetto `documents_allowed` personalizzato, deve contenere almeno un paese valido e un tipo di documento abilitato. Ogni configurazione del documento può impostare `sides` a `1` per l'acquisizione solo del fronte o a `2` per l'acquisizione di fronte e retro. * `QUESTIONNAIRE` richiede `config.questionnaire_uuid`. * `KYB_DOCUMENTS` richiede `config.kyb_required_document_groups`. * `SIGNATURE` rifiuta `signature_level: "qes"` con `qes_not_available` finché le firme qualificate non saranno disponibili, e un nuovo passaggio con `signature_level: "aes"` con `aes_not_available` finché `signature_availability.aes` è `false` sul workflow. I suoi documenti devono esistere al momento della creazione di una sessione: con `signature_documents_source` impostato su `workflow`, il passaggio richiede documenti caricati nella console, e un passaggio senza documenti può restare in bozza ma non può essere attivato; con `session`, ogni chiamata di creazione deve inviare `sign.documents`. * `FACE_MATCH` deve venire dopo `OCR` nelle richieste di workflow semplici. * `NFC` e `DATABASE_VALIDATION` richiedono `OCR` quando compaiono nello stesso workflow. `AML` richiede uno tra `OCR`, `KYB_REGISTRY` o `DOCUMENT_AI` prima di sé; se davanti ha solo `DOCUMENT_AI`, il `full_name` da sottoporre a screening deve poter essere compilato, o da un campo Document AI a monte già associato a `full_name`, che viene mappato automaticamente, oppure da una voce esplicita `config.aml_field_sources` (vedi [AML](#aml)). * Le sottofunzionalità KYB, come `KYB_DOCUMENTS` e `KYB_KEY_PEOPLE`, richiedono `KYB_REGISTRY` più in alto nel workflow. * Un workflow è un workflow per persone (KYC) oppure un workflow per aziende (KYB), mai entrambi. Un workflow che usa una funzionalità KYB (`KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`) può combinarla solo con `AML`, `DOCUMENT_AI`, `QUESTIONNAIRE`, `PHONE_VERIFICATION`, `EMAIL_VERIFICATION`, `IP_ANALYSIS` e `SIGNATURE`. Non può includere funzionalità riservate alle persone come `OCR`, `LIVENESS`, `FACE_MATCH`, `NFC`, `PROOF_OF_ADDRESS`, `DATABASE_VALIDATION` o `AGE_ESTIMATION`, e un workflow per persone non può includere funzionalità KYB. In un workflow per aziende `DOCUMENT_AI` confronta qualsiasi campo contrassegnato con `is_full_name` con l'azienda verificata, non con una persona. Per verificare le persone dietro un'azienda, crea un workflow KYC separato e fai riferimento ad esso dal nodo `KYB_KEY_PEOPLE` usando `kyb_ubo_verification_workflow`, `kyb_officer_verification_workflow` o `kyb_shareholder_verification_workflow`. * I campi di azione usano `DECLINE`, `REVIEW` o `NO_ACTION`, a meno che il campo qui sotto non indichi una restrizione. * I campi di punteggio e di soglia sono numeri da `0` a `100`, a meno che non sia indicato un intervallo più ristretto. ## Regole comuni sullo stato Ogni funzionalità supporta un array facoltativo `status_rules`. Usalo per sovrascrivere lo stato della funzionalità quando una condizione su un campo è soddisfatta. ```json theme={null} { "status_rules": [ { "field": "kyc.issuing_state", "operator": "in", "value": ["VEN", "IRN"], "status": "In Review", "value_type": "literal" }, { "field": "kyc.extra_fields.profession", "operator": "fuzzy_match", "value": "Soft. Engineer", "score": 80, "status": "Declined", "value_type": "literal" }, { "field": "kyc.extra_fields.dl_class_code_b_to", "operator": "less_than", "value": "2030-01-01", "status": "In Review", "value_type": "literal" }, { "field": "kyc.extra_fields.dl_class_code_b_from", "operator": "less_than", "value": { "direction": "past", "amount": 3, "unit": "years" }, "status": "Declined", "value_type": "relative_date" } ] } ``` | Campo | Tipo | Descrizione | | - | - | - | | `field` | string | Percorso del campo da controllare, ad esempio `kyc.issuing_state` o `kyc.document_type`. | | `operator` | string | Uno tra `equals`, `not_equals`, `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals`, `contains`, `not_contains`, `in`, `not_in`, `is_empty`, `is_not_empty`, `regex` o `fuzzy_match`. | | `value` | any | Valore di confronto. Ometti o invia `null` per gli operatori che non richiedono un valore. | | `status` | string | Uno tra `Approved`, `Declined`, `In Review` o `No Action`. | | `value_type` | string | Facoltativo. Il valore predefinito è `literal`. Usa `field` per confrontare con un altro campo, `list` per risolvere a runtime un UUID di lista Didit, oppure `relative_date` per confrontare un campo data con oggi più o meno una durata. | | `score` | number | Obbligatorio per `fuzzy_match`. Punteggio minimo di somiglianza da `0` a `100`. La regola corrisponde quando la somiglianza calcolata è maggiore o uguale a questo valore (`similarity >= score`). Ad esempio, `Software Engineer` può corrispondere a `Soft. Engineer` quando la somiglianza è almeno `80`. | Leggi l'esempio sopra così: `kyc.extra_fields.profession` corrisponde in modo fuzzy a `Soft. Engineer` con un punteggio minimo di `80` → imposta lo stato della funzionalità su `Declined`. Per la Verifica dell'identità, punta ai valori estratti in `extra_fields`, come `kyc.extra_fields.profession`, alle date di validità della classe della patente di guida, come `kyc.extra_fields.dl_class_code_b_from` e `kyc.extra_fields.dl_class_code_b_to`, oppure ai codici di restrizione o informazione per classe, come `kyc.extra_fields.dl_class_code_b_notes` (colonna 12 delle patenti britanniche). Questi valori provengono dall'oggetto `extra_fields` del risultato OCR; non fanno parte di `expected_details`. > [!NOTE] > > I campi `dl_class_code_*_from` e `dl_class_code_*_to` sono sempre una data ISO valida oppure sono assenti da `extra_fields`: Didit non restituisce mai testo OCR illeggibile in un campo data. Se la cella della tabella delle classi non può essere letta, il campo viene omesso invece di essere inviato come stringa grezza. Usa quindi l'operatore `is_empty` per instradare le date di classe illeggibili, invece di presumere che il campo sia sempre presente. Per i campi data, usa `value_type: "relative_date"` con un oggetto per il valore nella forma `{ "direction": "past" | "future", "amount": number, "unit": "days" | "months" | "years" }`. Ad esempio, `operator: "less_than"` con `{ "direction": "past", "amount": 3, "unit": "years" }` corrisponde alle date più vecchie di tre anni da oggi. ### Confronto con un passaggio specifico Un workflow basato su un grafo può eseguire la stessa funzionalità più di una volta, ad esempio tre passaggi di Verifica dell'identità. Con `value_type: "field"`, aggiungi `@` al valore per leggerlo da un passaggio specifico. Il nodo di riferimento deve essere un passaggio di una funzionalità che viene sempre eseguito prima del passaggio della regola, su ogni percorso che vi arriva, oppure il passaggio della regola stesso. Un valore senza il suffisso viene letto dal passaggio della regola. ```json theme={null} { "status_rules": [ { "field": "kyc.full_name", "operator": "fuzzy_match", "value": "kyc.full_name@ocr_1", "value_type": "field", "score": 80, "status": "Declined" } ] } ``` Leggi questa regola, impostata sul terzo passaggio di Verifica dell'identità, così: il `kyc.full_name` di questo passaggio corrisponde in modo fuzzy al nome completo letto dal passaggio `ocr_1` con un punteggio minimo di `80` → imposta lo stato della funzionalità su `Declined`. Nella console, il selettore delle variabili elenca ogni passaggio idoneo con il suo numero sul canvas e salva il suffisso per te. ## OCR / Verifica dell'identità Valore della funzionalità: `OCR`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `documents_allowed` | oggetto | Facoltativo. Ometti il campo, invia `null` oppure `{}` per consentire ogni paese e tipo di documento supportato. Invia un codice paese ISO3 nella configurazione del tipo di documento solo se vuoi limitare i documenti consentiti. Almeno un documento personalizzato deve avere `enabled: 1`. Le configurazioni dei documenti possono includere `sides: 1` per l'acquisizione solo del fronte oppure `sides: 2` per l'acquisizione di fronte e retro. I tipi di documento includono `P`, `ID`, `DL`, `RP`, `HIC`, `TC`, `SSC` e altri valori supportati dal paese. | | `methods` | oggetto | Quali dei tre [metodi di Verifica dell'identità](https://docs.didit.me/it/core-technology/id-verification/verification-methods.md) può usare ciascun paese: acquisizione del documento, ricerca senza documento presso una fonte governativa o altra fonte autorevole, e wallet di identità digitale. Se ometti la chiave, un paese o un metodo all'interno di un paese, quel paese usa solo l'acquisizione del documento. Ogni metodo e wallet deve essere contrassegnato come disponibile per il paese nel catalogo delle funzionalità, altrimenti il salvataggio viene rifiutato. Vedi [Metodi per paese](#metodi-per-paese) più sotto. | | `document_blur_fields_by_country` | oggetto | Dal codice paese ISO3 ai nomi dei campi da offuscare sulle immagini dei documenti. | | `image_capture_methods_allowed` | string\[] | Metodi di acquisizione consentiti. I valori includono `CAMERA_SCAN` e `UPLOAD`. | | `duplicated_user_action` | azione | Azione per un utente duplicato. | | `is_age_restrictions_enabled` | booleano | Attiva i controlli sull'età minima e massima. | | `age_restrictions_by_country` | oggetto | Dal codice paese ISO3 a una configurazione dell'età con `minimum_age`, `maximum_age` facoltativo e `states` facoltativo. | | `minimum_age` | intero | Età minima globale, da `1` a `120`. | | `minimum_age_action` | azione | Azione quando l'utente ha un'età inferiore a `minimum_age`. | | `maximum_age` | intero | Età massima globale, da `1` a `120`. | | `maximum_age_action` | azione | Azione quando l'utente ha un'età superiore a `maximum_age`. | | `expiration_date_not_detected_action` | azione | Azione quando manca la data di scadenza del documento. | | `invalid_code_action` | azione | Azione quando un codice a barre o un codice leggibile dalla macchina non è valido. | | `invalid_mrz_action` | azione | Azione quando la MRZ non è valida. | | `inconsistent_data_action` | azione | Azione quando i campi estratti dal documento sono in conflitto. | | `invalid_validation_action` | azione | Azione quando la validazione del documento non riesce. | | `expected_details_mismatch_action` | azione | Azione quando i dati attesi dell'utente non corrispondono al documento. | | `image_too_blurry_action` | azione | Azione per le immagini del documento sfocate. | | `image_too_dark_action` | azione | Azione per le immagini del documento scure. | | `image_too_bright_action` | azione | Azione per le immagini del documento sovraesposte. | | `unparsed_address_action` | azione | Azione quando non è possibile analizzare l'indirizzo del documento. | | `address_validation_enabled` | booleano | Valida l'indirizzo letto da questo passaggio (stampato sul documento di identità) rispetto ai dati di riferimento postali: conferma che l'indirizzo esiste e lo normalizza, senza mai collegarlo a una persona. Il risultato è l'oggetto `address_validation` del passaggio nella decisione. **Costo: \$0.10 per indirizzo validato**; una validazione che non ha potuto essere eseguita (`unavailable`) è gratuita. Disattivato per impostazione predefinita. | | `address_not_verified_action` | azione | Azione quando la validazione dell'indirizzo non riesce a confermare l'indirizzo fino al numero civico (`ADDRESS_NOT_VERIFIED`: `partially_verified` oppure `not_verified`). Si applica solo se `address_validation_enabled` è attivo. Il valore predefinito è `NO_ACTION`, che si limita a registrare l'avviso. | | `document_or_personal_number_format_mismatch_action` | azione | Azione quando il formato del numero del documento o del numero personale non corrisponde al modello atteso. | | `critical_field_occlusion_action` | azione | Azione quando il controllo di occlusione rileva che un campo critico stampato - un numero di identità, un nome, la data di nascita o la data di scadenza - è coperto fisicamente sul documento acquisito. Coprire un numero di identità è un segnale di manomissione e non di qualità dell'acquisizione, quindi il valore predefinito è `REVIEW`; il valore letto da un campo coperto viene comunque escluso dall'estrazione. Impostalo su `DECLINE` quando un documento oscurato non deve mai arrivare a un revisore. | | `document_without_portrait_action` | azione | Azione quando il tipo di documento riconosciuto non riporta mai una foto ritratto su nessun lato (alcuni permessi di soggiorno, tessere sanitarie, certificati di registrazione e altre famiglie di documenti senza ritratto note nel catalogo). Il valore predefinito è `REVIEW`. Valuta `DECLINE` quando il Confronto facciale costituisce il controllo di identità del workflow. | | `is_document_selfie_portrait_match_enabled` | booleano | Attiva il confronto tra il ritratto del documento e il selfie. | | `document_selfie_portrait_match_decline_threshold` | intero | Soglia di rifiuto per il confronto tra il ritratto del documento e il selfie. | | `document_selfie_portrait_match_review_threshold` | intero | Soglia di revisione per il confronto tra il ritratto del documento e il selfie. | | `document_selfie_face_search_enabled` | booleano | Esegue la [Ricerca facciale 1:N](https://docs.didit.me/it/core-technology/face-search/overview.md#il-selfie-scattato-durante-l’acquisizione-del-documento) sul selfie scattato durante l'acquisizione del documento (richiede `is_document_selfie_portrait_match_enabled`): lo confronta con la blocklist dei volti e con gli utenti verificati in precedenza. Il selfie viene solo confrontato, e il suo modello non viene mai memorizzato. Attivo per impostazione predefinita. `false` salta la ricerca e lascia senza effetto le azioni sui volti duplicati del selfie del documento; anche `face_search_enabled: false` nel passaggio Rilevamento della vitalità la salta, perché questa disattivazione vale per ogni selfie della sessione. | | `document_selfie_duplicated_face_action` | azione | Esito quando il selfie dell'acquisizione del documento corrisponde, o potenzialmente corrisponde, al volto di un utente già verificato in questa applicazione. Il valore predefinito è `NO_ACTION`. | | `document_selfie_duplicated_face_name_mismatch_action` | azione | Esito quando il selfie dell'acquisizione del documento corrisponde a un utente già verificato con un nome diverso. Può solo aumentare la gravità di `document_selfie_duplicated_face_action`. Il valore predefinito è `REVIEW`. | | `document_selfie_duplicated_face_document_mismatch_action` | azione | Esito quando il selfie dell'acquisizione del documento corrisponde a un utente già verificato con una data di nascita diversa sul suo documento di identità. La stessa persona con un documento diverso o rinnovato non viene segnalata. Può solo aumentare la gravità di `document_selfie_duplicated_face_action`. Il valore predefinito è `REVIEW`. | | `id_verification_name_match_score_threshold` | integer | Soglia di corrispondenza del nome tra più verifiche dell'identità. | | `id_verification_max_retry_attempts` | integer | Limite di nuovi tentativi per la verifica dell'identità, da `2` a `5`. | | `id_document_quality_threshold` | integer | Punteggio minimo di qualità dell'acquisizione (da `0` a `100`) che l'immagine del documento deve raggiungere per essere accettata. Il controllo di qualità viene sempre eseguito; solo questa soglia è configurabile. Il valore predefinito è `20`, calibrato in modo che le acquisizioni degradate e al limite (sfocatura, movimento, testo illeggibile) vengano rifiutate mentre i documenti leggibili passano; alzala per requisiti di acquisizione più severi. La console mostra questo valore su un cursore percettivo, dove il valore predefinito di `20` appare come un valore bilanciato del 50%. | | `cross_org_fraud_document_action` | action | Esito quando questo documento è stato segnalato come fraudolento da un'altra organizzazione della rete. | | `document_audio_recording_enabled` | boolean | Registra il microfono durante l'acquisizione del documento, così un revisore può ascoltare la sessione. Disattivato per impostazione predefinita. | | `document_liveness_portrait_replace_decline_threshold` | integer | Punteggio di sostituzione del ritratto (da `0` a `100`, più alto = più probabilmente autentico) al di sotto del quale la sessione viene rifiutata. Il valore predefinito è `35`. Vedi [soglie di vitalità del documento](https://docs.didit.me/it/core-technology/id-verification/warnings-id-verification.md#configurazione-delle-soglie-di-rilevamento-della-vitalità-del-documento). | | `document_liveness_portrait_replace_review_threshold` | integer | Punteggio di sostituzione del ritratto al di sotto del quale la sessione passa in revisione, quando non è già rifiutata. A `100`, quasi tutte le sessioni vengono trattenute. Il valore predefinito è `70`. Vedi [soglie di vitalità del documento](https://docs.didit.me/it/core-technology/id-verification/warnings-id-verification.md#configurazione-delle-soglie-di-rilevamento-della-vitalità-del-documento). | | `document_liveness_printed_copy_decline_threshold` | integer | Punteggio della copia stampata (da `0` a `100`, più alto = più probabilmente autentico) al di sotto del quale la sessione viene rifiutata. Il valore predefinito è `35`. Vedi [soglie di vitalità del documento](https://docs.didit.me/it/core-technology/id-verification/warnings-id-verification.md#configurazione-delle-soglie-di-rilevamento-della-vitalità-del-documento). | | `document_liveness_printed_copy_review_threshold` | integer | Punteggio della copia stampata al di sotto del quale la sessione passa in revisione, quando non è già rifiutata. A `100`, quasi tutte le sessioni vengono trattenute. Il valore predefinito è `77`. Vedi [soglie di vitalità del documento](https://docs.didit.me/it/core-technology/id-verification/warnings-id-verification.md#configurazione-delle-soglie-di-rilevamento-della-vitalità-del-documento). | | `document_liveness_screen_replay_decline_threshold` | integer | Punteggio della cattura dello schermo (da `0` a `100`, più alto = più probabilmente autentico) al di sotto del quale la sessione viene rifiutata. Il valore predefinito è `30`. Vedi [soglie di vitalità del documento](https://docs.didit.me/it/core-technology/id-verification/warnings-id-verification.md#configurazione-delle-soglie-di-rilevamento-della-vitalità-del-documento). | | `document_liveness_screen_replay_review_threshold` | integer | Punteggio della cattura dello schermo al di sotto del quale la sessione passa in revisione, quando non è già rifiutata. A `100`, quasi tutte le sessioni vengono trattenute. Il valore predefinito è `70`. Vedi [soglie di vitalità del documento](https://docs.didit.me/it/core-technology/id-verification/warnings-id-verification.md#configurazione-delle-soglie-di-rilevamento-della-vitalità-del-documento). | | `id_verification_injection_attack_action` | action | Esito quando il documento, o il selfie scattato per una ricerca ID, è stato iniettato anziché acquisito dalla fotocamera del dispositivo (`INJECTION_ATTACK_DETECTED`): una fotocamera virtuale via software, un flusso video generato dalla pagina o dall'automazione del browser, una fotocamera agganciata o uno strumento di instrumentazione collegato all'app. Valori: `DECLINE`, `REVIEW`, `NO_ACTION`. Il valore predefinito è `DECLINE`. I segnali che una persona autentica può produrre non lo attivano mai. Per la vitalità e il confronto facciale il rischio segue invece `frame_injection_action`. | | `image_quality_too_low_action` | action | Esito quando la qualità complessiva dell'immagine del documento è al di sotto della soglia. | | `is_image_capture_review_screen_enabled` | boolean | Mostra all'utente una schermata di revisione dopo ogni acquisizione del documento, permettendogli di rifare la foto prima dell'invio. Disattivato per impostazione predefinita. | | `is_ocr_id_verification_data_review_enabled` | boolean | Permette all'utente di rivedere e correggere i dati identificativi estratti prima che il passaggio sia completato. Disattivato per impostazione predefinita. Una correzione viene confrontata con `ocr_id_verification_data_review_critical_fields`, e un disaccordo attiva l'azione critica o quella minore in base al caso. La revisione viene comunque eseguita quando il workflow include NFC: una successiva lettura del chip sostituisce semplicemente il risultato. | | `ocr_id_verification_data_review_critical_fields` | string\[] | Quali campi identificativi estratti contano come critici quando l'utente modifica il risultato OCR, così una mancata corrispondenza attiva l'azione critica anziché quella minore. Formato: `["first_name" \| "last_name" \| "date_of_birth" \| ...]`. | | `ocr_id_verification_data_review_critical_mismatch_action` | restricted action | Esito quando la modifica dell'utente non concorda con l'OCR su un campo critico. | | `ocr_id_verification_data_review_minor_mismatch_action` | action | Esito quando la modifica dell'utente non concorda con l'OCR su un campo non critico. | | `status_rules` | array | Regole di stato personalizzate facoltative. | > [!NOTE] > > La vitalità del documento si configura con le sei soglie `document_liveness_*` indicate sopra, non con > campi di azione per segnale. `portrait_replacement_action`, `printed_copy_action` e > `screen_capture_action` sono impostazioni a livello di account e **non** sono accettate in una configurazione > di funzionalità del workflow: l'API rimuove le chiavi di configurazione sconosciute al salvataggio, quindi inviarle > non ha alcun effetto. Ogni segnale ha una soglia di rifiuto e una soglia di revisione su una scala da `0` > a `100`, dove un punteggio più alto indica che il documento è più probabilmente autentico. Esempio: ```json theme={null} { "feature": "OCR", "config": { "documents_allowed": { "USA": { "DL": { "enabled": 1, "sides": 2 } } }, "duplicated_user_action": "REVIEW", "image_capture_methods_allowed": ["CAMERA_SCAN", "UPLOAD"] } } ``` ### Metodi per paese `methods` è indicizzato per codice paese [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). Ogni paese prevede fino a tre oggetti metodo; ciò che si omette assume il valore predefinito. ```json theme={null} { "feature": "OCR", "config": { "methods": { "ZAF": { "document": { "enabled": true }, "id_lookup": { "enabled": true, "max_attempts": 2, "skip_liveness_and_face_match": true, "on_partial_match": "fallback_to_document", "on_no_match": "fallback_to_document", "on_provider_error": "fallback_to_document" }, "wallet": { "enabled": false, "providers": [], "on_failure": "fallback_to_document" } }, "DNK": { "document": { "enabled": true }, "id_lookup": { "enabled": true, "on_no_match": "decline" } } } } } ``` `wallet.on_failure` può essere `fallback_to_document`, `decline` o `retry`. `retry` (solo per wallet, con acquisizione del documento disattivata per il paese) permette a un utente il cui accesso non è stato completato nel passaggio del wallet di riprovare; la sessione non viene mai rifiutata per questo motivo e resta aperta finché l'utente non completa il processo o finché non scade. Gli interruttori id\_lookup accettano solo `fallback_to_document` o `decline`. Per tenere i documenti fuori dalla prima schermata e proporli solo quando un wallet o una ricerca non va a buon fine, imposta `document.fallback_only`. L'esempio usa la Finlandia, dove la Finnish Trust Network viene per prima e l'acquisizione del documento è il ripiego. La Finlandia richiede inoltre che i suoi tipi di documento siano abilitati in `documents_allowed` (ad esempio passaporto e carta d'identità), così il ripiego ha documenti da proporre. ```json theme={null} { "FIN": { "document": { "enabled": true, "fallback_only": true }, "wallet": { "enabled": true, "providers": ["ftn"], "on_failure": "fallback_to_document" } } } ``` Entrambe le ricerche sopra risultano `available` nel catalogo attuale, quindi questa configurazione viene salvata così come scritta. Il blocco del wallet è stato escluso da questo esempio di proposito: la configurazione di un wallet viene salvata solo in un paese in cui il catalogo lo indica come `available`, e `wallet.enabled: true` in qualsiasi altro paese viene rifiutato e fa fallire l'intero salvataggio, configurazione delle ricerche compresa. Dove il catalogo indica un wallet come `available`, aggiungilo a quel paese: ```json theme={null} { "DNK": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" } } } ``` | Key | Type | Default | Descrizione | | - | - | - | - | | `.document.enabled` | boolean | `true` | Indica se in questo paese viene accettato un documento fotografato. Quali documenti sono accettati continua a essere definito in `documents_allowed`. | | `.document.fallback_only` | boolean | `false` | Mantiene attiva l'acquisizione del documento, ma non la propone nella prima schermata. Gli utenti iniziano con il wallet o la ricerca dell'identità previsti dal paese. Vengono indirizzati all'acquisizione del documento solo gli utenti per cui l'accesso con wallet non va a buon fine, viene annullato o scade, oppure la cui ricerca non corrisponde (secondo gli switch `on_failure`, `on_partial_match`, `on_no_match` e `on_provider_error` impostati su `fallback_to_document`). Con un solo wallet, l'utente viene portato direttamente su quel wallet. Altrimenti, un wallet o una ricerca viene mostrato affiancato all'acquisizione del documento. Viene rifiutato con HTTP 400, a meno che `document.enabled` non sia `true` e almeno un wallet o una ricerca dell'identità nel paese ricada sull'acquisizione del documento. | | `.id_lookup.enabled` | boolean | `false` | Propone la ricerca non documentale presso la fonte governativa o altra fonte autorevole del paese. Viene rifiutato quando il catalogo non indica la fonte del paese come `available`. | | `.id_lookup.max_attempts` | integer | `1` | Da `1` a `5`. Quante ricerche **con risposta** riceve l'utente prima che scatti lo switch di fallback. Un numero che non supera il controllo di formato lato client non arriva mai al registro, quindi non viene conteggiato né fatturato. | | `.id_lookup.skip_liveness_and_face_match` | boolean | `true` | Dopo una corrispondenza con un registro che restituisce un ritratto, salta i passaggi di Rilevamento della vitalità e Confronto facciale del workflow. La ricerca ha già eseguito il liveness passivo sul selfie e lo ha confrontato con quel ritratto. Al salvataggio viene impostato su `false` per una fonte che non restituisce alcun ritratto, dove lo switch non avrebbe alcun effetto. | | `.id_lookup.on_partial_match` | `fallback_to_document` \| `decline` | `fallback_to_document` | Cosa succede quando il registro ha risposto ma alcuni campi non corrispondono. | | `.id_lookup.on_no_match` | `fallback_to_document` \| `decline` | `fallback_to_document` | Cosa succede quando il registro ha risposto e non contiene alcun record corrispondente. | | `.id_lookup.on_provider_error` | `fallback_to_document` \| `decline` | `fallback_to_document` | Cosa succede quando non è possibile raggiungere il registro. Mai fatturato. | | `.id_lookup.response_fields` | string\[] \| null | `null` | Sottoinsieme facoltativo delle chiavi dei campi di risposta della fonte. Le chiavi sconosciute vengono rifiutate e i campi obbligatori della fonte vengono sempre riaggiunti, quindi il valore salvato è sempre una selezione valida. L'attuale implementazione di staging applica questa selezione all'output di confronto, al genere facoltativo e ai ritratti del registro conservati. I campi di identità obbligatori restano. Vedi la nota su rilascio e conservazione qui sotto. | | `.wallet.enabled` | boolean | `false` | Propone l'accesso con wallet di identità digitale in questo paese. | | `.wallet.providers` | string\[] | `[]` | Gli ID dei wallet del catalogo che questo paese accetta: una lista di accettazione, mai una classifica. L'ordine inviato viene normalizzato secondo l'ordine del catalogo. Almeno un wallet è obbligatorio quando `enabled` è `true`. Un wallet non offerto nel paese, oppure ancora in arrivo, viene rifiutato. | | `.wallet.on_failure` | `fallback_to_document` \| `decline` \| `retry` | `fallback_to_document` | Cosa succede quando l'accesso viene annullato, scade o non riesce. `retry` mantiene l'utente nel passaggio del wallet per riprovare (solo wallet); viene rifiutato insieme a `document.fallback_only`. | Validazione applicata dall'API al salvataggio: * Un codice paese sconosciuto, una chiave sconosciuta all'interno di un paese o una chiave sconosciuta all'interno di un metodo vengono rifiutati: nulla viene eliminato in silenzio. * Un paese in cui non è attivato alcun metodo viene rifiutato: nessuno in quel paese potrebbe completare la verifica. * Un wallet o una ricerca possono ricadere sull'acquisizione del documento solo se l'acquisizione del documento è attiva per quel paese. `fallback_to_document` in un paese in cui `document.enabled` è `false` porta al rifiuto a runtime, perché non c'è un'alternativa a cui ricorrere. * `document.fallback_only: true` viene rifiutato con HTTP 400, a meno che `document.enabled` non sia `true` e almeno un wallet o una ricerca dell'identità in quel paese ricada sull'acquisizione del documento. > [!WARNING] > > L'attuale implementazione di staging applica `id_lookup.response_fields` all'output di confronto, al genere facoltativo e ai ritratti del registro conservati. I campi di identità obbligatori restano parte del record della verifica. Non è una garanzia che ogni payload intermedio del provider venga escluso dal trattamento. Il rilascio in produzione di questa modifica non è stato verificato: prima di affidarti alla selezione dei campi per i requisiti di conservazione, verifica il comportamento nel tuo ambiente di destinazione. Leggi il catalogo delle funzionalità prima di scrivere `methods`, nella scheda **Paesi** della console oppure con lo strumento MCP [`didit_workflow_get_id_verification_methods_catalog`](https://docs.didit.me/it/integration/mcp/tools). Comportamento, copertura e fatturazione sono descritti in [Metodi di verifica dell'identità](https://docs.didit.me/it/core-technology/id-verification/verification-methods.md). ## NFC / ePassport Valore della funzionalità: `NFC`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `allow_nfc_skip` | boolean | Consente agli utenti di saltare la lettura NFC quando il loro documento supporta la lettura del chip. | | `skip_nfc_action` | azione | Azione quando l'utente salta la NFC. | | `unverified_chip_action` | azione | Azione quando la verifica del chip non va a buon fine. | | `trust_anchor_missing_action` | azione | Verdetto quando gli hash dei gruppi di dati del chip sono integri ma la catena dei certificati non può essere verificata, perché l'ancora di attendibilità CSCA del paese di emissione non è caricata. | | `jpki_request_attributes` | boolean | Per la My Number Card giapponese ([JPKI](https://docs.didit.me/it/core-technology/nfc-verification/overview.md#japan-my-number-card-jpki), solo SDK nativi): legge anche il certificato di firma, che richiede il PIN di firma della carta e contiene nome, data di nascita, sesso e indirizzo del titolare, confrontati con i dati della verifica dell'identità. Predefinito `true`. `false` legge solo il certificato di autenticazione utente (PIN a 4 cifre), che prova la carta e il PIN ma non contiene dati del titolare. | | `jpki_certificate_invalid_action` | azione | Verdetto quando un certificato della My Number Card non forma una catena fino all'autorità di certificazione JPKI, è al di fuori del periodo di validità o non è un certificato della carta del tipo richiesto (`JPKI_CERTIFICATE_INVALID`). Predefinito `DECLINE`. | | `jpki_signature_invalid_action` | azione | Verdetto quando la firma della My Number Card sulla richiesta di autenticazione monouso non viene verificata, quindi il possesso della carta e la conoscenza del PIN non sono provati (`JPKI_SIGNATURE_INVALID`). Predefinito `DECLINE`. | | `jpki_certificate_revoked_action` | azione | Verdetto quando il controllo di revoca segnala un certificato della My Number Card come revocato (`JPKI_CERTIFICATE_REVOKED`). Predefinito `DECLINE`. | | `jpki_revocation_unchecked_action` | azione | Verdetto quando la My Number Card è stata verificata ma non era disponibile alcuna risposta sulla revoca, quindi non si può escludere che la carta sia revocata (`JPKI_REVOCATION_UNCHECKED`). Predefinito `REVIEW`. | | `jpki_inconsistent_data_action` | azione | Verdetto quando nome, data di nascita, sesso o indirizzo nel certificato di firma della My Number Card differiscono dai dati della verifica dell'identità della stessa carta (`JPKI_AND_OCR_DATA_NOT_SAME`). Predefinito `REVIEW`. | | `status_rules` | array | Regole di stato personalizzate facoltative. | ## Rilevamento della vitalità Valore della funzionalità: `LIVENESS`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `face_liveness_method` | stringa | Uno tra `ACTIVE_3D`, `FLASHING` o `PASSIVE`. | | `face_liveness_mode` | stringa | Override della modalità di vitalità. | | `face_liveness_flash_mode` | stringa | Modalità flash per i metodi `ACTIVE_3D` e `FLASHING`. `"0"` (non rigorosa, predefinita) verifica che i colori mostrati sullo schermo si riflettano sul volto dell'utente; `"1"` (rigorosa) richiede inoltre che i riflessi corrispondano esattamente alla sequenza di colori mostrata, offrendo una protezione maggiore contro gli attacchi di replay e di iniezione video, ma con più falsi rifiuti. | | `face_liveness_score_decline_threshold` | intero | Soglia di rifiuto. | | `face_liveness_score_review_threshold` | intero | Soglia di revisione. | | `face_liveness_possible_duplicated_face_action` | azione | Azione quando il volto potrebbe essere duplicato. | | `face_liveness_multiple_faces_action` | azione | Azione quando vengono rilevati più volti. | | `face_liveness_video_anomaly_action` | azione | Azione quando la registrazione memorizzata contiene una sequenza ripetuta di movimenti. Predefinita `NO_ACTION`; `REVIEW` e `DECLINE` possono rendere più severo in modo asincrono l'esito di una verifica già decisa. Fotogrammi fissi diradati o ripetuti da soli non attivano questa regola. | | `face_liveness_attack_face_match_action` | azione | Azione quando il volto della prova di vitalità corrisponde a un volto di una sessione precedente di questa applicazione, appartenente a un altro utente la cui acquisizione è stata giudicata un attacco di vitalità con alta affidabilità (avviso `FACE_MATCHES_LIVENESS_ATTACK`). Accetta `NO_ACTION` o `REVIEW`; `DECLINE` è accettato ma applicato come `REVIEW`, perché un utente legittimo può essere rifiutato per errore una volta e poi superare la verifica. Predefinita `NO_ACTION`. | | `race_map_similarity_thresholds` | oggetto | Soglie di somiglianza per ciascun gruppo demografico. | | `face_privacy_mode_enabled` | booleano | Attiva la modalità privacy per i dati facciali. | | `face_quality_review_threshold` | intero | Soglia di revisione per la qualità dell'immagine del volto. | | `face_quality_decline_threshold` | intero | Soglia di rifiuto per la qualità dell'immagine del volto. Deve essere minore o uguale alla soglia di revisione. | | `face_luminance_min_threshold` | intero | Soglia minima di luminanza. Deve essere inferiore a `face_luminance_max_threshold`. | | `face_luminance_min_action` | azione | Azione quando la luminanza è troppo bassa. | | `face_luminance_max_threshold` | intero | Soglia massima di luminanza. | | `face_luminance_max_action` | azione | Azione quando la luminanza è troppo alta. | | `face_liveness_max_attempts` | intero | Numero totale di invii di vitalità per sessione, da `1` a `3`. Il valore predefinito `3` significa un tentativo iniziale più due nuovi tentativi. Impostare `1` non disattiva i nuovi tentativi per gli errori di qualità dell'acquisizione: quando tutti gli avvisi del tentativo sono ambientali (`LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `NO_FACE_DETECTED`), l'utente ottiene sempre un secondo tentativo con indicazioni utili. | | `cross_org_fraud_face_action` | azione | **Deprecato e non più applicato.** Trattava un volto come se avesse un esito di frode, cosa che un'identità biometrica stabile non può avere. Resta accettato, così i flussi di lavoro esistenti continuano a validare. Usa `cross_org_identity_claim_pattern_action`. | | `cross_org_identity_claim_pattern_action` | azione | Esito quando altre organizzazioni della rete hanno registrato eventi di dichiarazione di identità per la stessa persona in cui l'identità dichiarata non corrispondeva. Solo Revisione o Nessuna azione: un Rifiuto impostato qui viene declassato a Revisione. Vedi [Dichiarazioni di identità tra organizzazioni](https://docs.didit.me/it/core-technology/liveness/cross-organization-identity-claims.md). | | `external_capture_device_action` | azione | Esito quando viene rilevato un dispositivo di acquisizione esterno. | | `face_audio_recording_enabled` | booleano | Registra il microfono durante l'acquisizione del selfie, così un revisore può ascoltare la sessione. Disattivato per impostazione predefinita. | | `face_search_enabled` | booleano | Esegue la [Ricerca facciale 1:N](https://docs.didit.me/it/core-technology/face-search/overview.md#disattivazione-della-ricerca-facciale-automatica) automatica sul selfie: lo confronta con gli utenti già verificati, con la blocklist e l'allowlist dei volti, e memorizza il suo modello biometrico per i confronti successivi. Attivo per impostazione predefinita. `false` salta la ricerca, non conserva alcun modello facciale per questo passaggio e lascia senza effetto le azioni sui volti duplicati. | | `face_liveness_uncertain_retry_enabled` | booleano | Solo per la vitalità attiva nativa dell'SDK. Se attivo, un'acquisizione il cui punteggio di vitalità cade strettamente tra `face_liveness_score_decline_threshold` e `face_liveness_score_review_threshold` non viene mai decisa, qualunque esito le abbia assegnato il motore: alla persona viene comunicato che il risultato non era chiaro e le viene chiesto di acquisire di nuovo, ogni volta, al di fuori del budget di `face_liveness_max_attempts` (che continua ad applicarsi alle acquisizioni che il motore non è riuscito a valutare). Disattivato per impostazione predefinita; il flusso web lo ignora. | | `face_liveness_duplicated_face_name_mismatch_action` | azione | Esito quando un volto duplicato viene trovato con un nome diverso. | | `face_liveness_duplicated_face_document_mismatch_action` | azione | Esito quando un volto duplicato viene trovato e il documento d'identità dell'utente corrispondente riporta una data di nascita diversa. La stessa persona con un documento diverso o rinnovato non viene segnalata. Predefinita `REVIEW`. | | `frame_injection_action` | azione | Esito quando vengono rilevati fotogrammi video iniettati. | | `screen_capture_action` | azione | Esito quando il selfie è una foto di uno schermo. | | `virtual_camera_action` | azione | Esito quando viene rilevato un flusso di una videocamera virtuale. | | `status_rules` | array | Regole di stato personalizzate facoltative. | ## Confronto facciale Valore della funzionalità: `FACE_MATCH`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `face_match_score_decline_threshold` | intero | Soglia di rifiuto. | | `face_match_score_review_threshold` | intero | Soglia di revisione. | | `face_match_max_attempts` | intero | Numero totale di invii per il confronto facciale in una sessione, da `1` a `3`. Il valore predefinito `3` corrisponde a un tentativo iniziale e a due nuovi tentativi. | | `face_match_not_computed_action` | azione soggetta a restrizioni | Esito quando non è possibile calcolare alcun punteggio di confronto facciale (ritratto o selfie mancante). | | `face_match_eyes_covered_action` | azione | Esito quando la regione degli occhi è coperta nel selfie. Il valore predefinito è `NO_ACTION`, che registra le prove senza modificare il risultato del Confronto facciale. Questo segnale è ancora in fase di calibrazione, quindi resta solo in modalità osservativa finché la regione non risulta calibrata: se imposti ora `REVIEW` o `DECLINE`, l'impostazione avrà effetto da quel momento in poi. | | `face_match_mouth_covered_action` | azione | Esito quando la regione della bocca è coperta nel selfie. Stesso valore predefinito `NO_ACTION` e stessa avvertenza sulla calibrazione di `face_match_eyes_covered_action`. | | `face_match_face_covered_action` | azione | Esito quando il volto nel suo complesso è coperto nel selfie. Stesso valore predefinito `NO_ACTION` e stessa avvertenza sulla calibrazione di `face_match_eyes_covered_action`. | | `status_rules` | array | Regole di stato personalizzate facoltative. | ## Stima dell'età Valore della funzionalità: `AGE_ESTIMATION`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `enable_id_verification_fallback` | boolean | Esegue la Verifica dell'identità quando la stima dell'età cade nell'intervallo di confine. | | `minimum_age_threshold` | integer | Età minima accettata, da `1` a `100`. | | `borderline_minimum_age_threshold` | integer | Limite inferiore dell'intervallo di confine, da `1` a `100`. | | `borderline_maximum_age_threshold` | integer | Limite superiore dell'intervallo di confine, da `1` a `100`. | | `face_liveness_method` | string | Uno tra `ACTIVE_3D`, `FLASHING` o `PASSIVE`. | | `face_liveness_flash_mode` | string | Modalità flash per i metodi `ACTIVE_3D` e `FLASHING`. `"0"` (non rigorosa, predefinita) verifica che i colori mostrati sullo schermo si riflettano sul volto dell'utente; `"1"` (rigorosa) richiede inoltre che i riflessi corrispondano esattamente alla sequenza di colori mostrata. | | `face_liveness_score_decline_threshold` | number | Soglia di rifiuto per il controllo di vitalità usato dalla stima dell'età. | | `face_liveness_score_review_threshold` | number | Soglia di revisione per il controllo di vitalità usato dalla stima dell'età. | | `face_liveness_possible_duplicated_face_action` | action | Azione quando il volto può essere duplicato. | | `face_liveness_multiple_faces_action` | action | Azione quando vengono rilevati più volti. | | `face_liveness_video_anomaly_action` | action | Azione quando la registrazione memorizzata contiene una sequenza ripetuta di movimenti. Predefinita `NO_ACTION`; `REVIEW` e `DECLINE` possono far passare in modo asincrono una verifica già decisa a un esito più severo. Fotogrammi fermi sparsi o ripetuti, da soli, non attivano questa azione. | | `face_liveness_attack_face_match_action` | action | Azione quando il volto del controllo di vitalità corrisponde a un volto di una sessione precedente di questa applicazione, appartenente a un altro utente la cui acquisizione è stata giudicata un attacco di vitalità con alta affidabilità (avviso `FACE_MATCHES_LIVENESS_ATTACK`). Accetta `NO_ACTION` o `REVIEW`; `DECLINE` è accettata ma applicata come `REVIEW`, perché un utente legittimo può essere respinto per errore una volta e poi superare la verifica. Predefinita `NO_ACTION`. | | `face_privacy_mode_enabled` | boolean | Attiva la modalità privacy per i dati del volto. | | `face_quality_review_threshold` | integer | Soglia di revisione per la qualità del volto. | | `face_quality_decline_threshold` | integer | Soglia di rifiuto per la qualità del volto. | | `face_luminance_min_threshold` | integer | Soglia minima di luminanza. | | `face_luminance_min_action` | action | Azione quando la luminanza è troppo bassa. | | `face_luminance_max_threshold` | integer | Soglia massima di luminanza. | | `face_luminance_max_action` | action | Azione quando la luminanza è troppo alta. | | `face_liveness_max_attempts` | integer | Numero totale di invii per il controllo di vitalità per sessione, da `1` a `3`. Il valore predefinito `3` significa un tentativo iniziale più due nuovi tentativi. Impostare `1` non disattiva i nuovi tentativi per gli errori di qualità dell'acquisizione: quando tutti gli avvisi del tentativo sono ambientali (`LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `NO_FACE_DETECTED`), l'utente riceve sempre un secondo tentativo con indicazioni utili. | | `external_capture_device_action` | action | Esito quando viene rilevato un dispositivo di acquisizione esterno. | | `face_audio_recording_enabled` | boolean | Registra il microfono durante l'acquisizione del selfie, così un revisore può ascoltare la sessione. Disattivata per impostazione predefinita. | | `face_search_enabled` | boolean | Esegue la [Ricerca facciale 1:N](https://docs.didit.me/it/core-technology/face-search/overview.md#disattivazione-della-ricerca-facciale-automatica) sul selfie: confronta il volto con gli utenti già verificati, con la blocklist e la lista consentita dei volti, e memorizza il suo modello biometrico per confronti successivi. Attiva per impostazione predefinita. `false` salta la ricerca, non conserva alcun modello facciale per questo passaggio e lascia le azioni sui volti duplicati senza nulla su cui agire. | | `face_liveness_uncertain_retry_enabled` | boolean | Solo per il controllo di vitalità attivo dell'SDK nativo. Se attivo, un'acquisizione il cui punteggio di vitalità cade strettamente tra `face_liveness_score_decline_threshold` e `face_liveness_score_review_threshold` non viene mai decisa, qualunque esito il motore vi abbia associato: alla persona viene comunicato che il risultato non era chiaro e le viene chiesto di acquisire di nuovo, ogni volta, al di fuori del budget di `face_liveness_max_attempts` (che continua ad applicarsi alle acquisizioni che il motore non è riuscito a valutare). Disattivata per impostazione predefinita; il flusso web la ignora. | | `face_liveness_duplicated_face_name_mismatch_action` | action | Esito quando un volto duplicato viene trovato con un nome diverso. | | `face_liveness_duplicated_face_document_mismatch_action` | action | Esito quando viene trovato un volto duplicato e il documento d'identità dell'utente corrispondente riporta una data di nascita diversa. La stessa persona con un documento diverso o rinnovato non viene segnalata. Predefinito `REVIEW`. | | `frame_injection_action` | action | Esito quando vengono rilevati fotogrammi video iniettati. | | `screen_capture_action` | action | Esito quando il selfie è una foto di uno schermo. | | `virtual_camera_action` | action | Esito quando viene rilevato un flusso da una videocamera virtuale. | | `status_rules` | array | Regole di stato personalizzate facoltative. | ## Verifica telefonica Valore della funzionalità: `PHONE_VERIFICATION`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `code_size` | intero | Dimensione dell'OTP, da `4` a `8`. | | `phone_max_retries` | intero | Numero massimo di nuovi invii, da `1` a `5`. | | `phone_max_check_attempts` | intero | Numero massimo di tentativi di verifica dell'OTP, da `1` a `5`. | | `phone_verification_countries` | oggetto | Codice paese ISO2 associato alla configurazione del canale. Esempio: `{ "US": { "sms": { "enabled": true } } }`. | | `disposable_number_action` | azione | Azione per i numeri usa e getta. | | `voip_number_action` | azione | Azione per i numeri VoIP. | | `duplicated_phone_number_action` | azione | Azione per i numeri di telefono duplicati. | | `high_risk_phone_action` | azione | Azione quando il provider di invio blocca l'invio dell'OTP. Solo `DECLINE` o `REVIEW`; predefinito `DECLINE`. Si applica solo quando ogni blocco del passaggio riporta `risk_factors` esattamente uguale a `["device_attribute"]`; qualsiasi altro fattore di rischio, qualsiasi combinazione che lo includa, oppure l'assenza di fattori di rischio comporta il rifiuto indipendentemente da questa impostazione. | | `phone_shared_device_mode` | booleano | Consente la modalità di verifica telefonica su dispositivo condiviso. | | `phone_enrichment_enabled` | booleano | Attiva l'arricchimento con l'intelligence sul telefono (rischio del tipo di linea, indice di affidabilità, operatore, storico di portabilità e scambio SIM, punteggio di rischio di frode). **Addebitato \$0.05 per verifica** oltre al prezzo della verifica telefonica. | | `phone_intelligence_score_action` | azione | Azione quando il punteggio di rischio di frode è pari o superiore a `phone_intelligence_score_threshold`. | | `phone_intelligence_score_threshold` | intero | Punteggio di rischio di frode (`0`–`100`, più alto significa più rischioso) che attiva `phone_intelligence_score_action`. Predefinito `80`. | | `phone_type_risk_action` | azione | Azione quando il numero è segnalato come tipo di telefono ad alto rischio. | | `recent_port_action` | azione | Azione quando il numero è stato portato di recente (segnale di scambio SIM o di portabilità). | | `low_phone_trust_action` | azione | Azione quando l'indice di affidabilità del telefono è pari o inferiore a `phone_trust_index_threshold`. | | `phone_trust_index_threshold` | intero | Indice di affidabilità (`0`–`100`, più basso significa più rischioso) pari o inferiore al quale si applica `low_phone_trust_action`. Predefinito `30`. | | `phone_social_enabled` | booleano | Attiva il controllo della presenza sui social: su quali piattaforme di messaggistica, social, e-commerce e professionali è registrato il numero verificato. **Addebitato \$0.05 per verifica** oltre al prezzo della verifica telefonica, indipendentemente da `phone_enrichment_enabled`. | | `phone_no_social_presence_action` | azione | Azione quando il controllo della presenza sui social non trova il numero registrato su nessuna delle piattaforme coperte - un segnale comune di identità sintetica. Predefinito `NO_ACTION`. | | `cross_org_fraud_phone_action` | azione | Esito quando questo numero è stato segnalato come fraudolento da un'altra organizzazione della rete. | | `status_rules` | array | Regole di stato personalizzate facoltative. | La Verifica telefonica è disattivata finché l'organizzazione non completa la prima ricarica. > [!NOTE] > > L'arricchimento con l'intelligence sul telefono è un componente aggiuntivo facoltativo. Quando `phone_enrichment_enabled` è `true`, ogni verifica telefonica completata viene arricchita con l'intelligence sul telefono ed è **addebitata \$0.05 per richiesta** oltre al costo standard della verifica telefonica. Le azioni basate sul punteggio si attivano solo quando il punteggio di arricchimento è disponibile; le azioni basate sull'indice di affidabilità, sul tipo di telefono e sulla portabilità si applicano non appena l'arricchimento viene eseguito. > > Il controllo della presenza sui social è un secondo componente aggiuntivo, separato dal primo. Quando `phone_social_enabled` è `true`, ogni verifica telefonica completata segnala anche su quali piattaforme online è registrato il numero (messaggistica, social media, e-commerce e servizi professionali) ed è **addebitata \$0.05 per richiesta**. Può essere attivato con o senza `phone_enrichment_enabled`: i due componenti aggiuntivi hanno prezzi e addebiti indipendenti. Una ricerca che non trova il numero su nessuna delle piattaforme coperte è una risposta valida e fatturabile e attiva `phone_no_social_presence_action`. Usa `phone.social_profiles_registered` (il numero di piattaforme su cui il numero è registrato) per ramificare il risultato in un grafo di workflow. ## Verifica email Valore della funzionalità: `EMAIL_VERIFICATION`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `email_code_size` | intero | Dimensione dell'OTP, da `4` a `8`. | | `email_max_retries` | intero | Numero massimo di nuovi tentativi di invio, da `1` a `5`. | | `email_max_check_attempts` | intero | Numero massimo di tentativi di verifica dell'OTP, da `1` a `5`. | | `email_alphanumeric_code` | booleano | Usa codici alfanumerici nelle email. | | `breached_email_action` | azione | Azione per le email coinvolte in violazioni di dati. | | `disposable_email_action` | azione | Azione per le email usa e getta. | | `duplicated_email_action` | azione | Azione per le email duplicate. | | `only_corporate_emails_allowed` | booleano | Rifiuta gli indirizzi email non aziendali. | | `email_enrichment_enabled` | booleano | Attiva l'arricchimento con intelligence delle email (recapitabilità, reputazione del dominio, esposizione a violazioni di dati, punteggio del rischio di frode). **Viene addebitato un costo di \$0.05 per verifica** in aggiunta al prezzo della verifica email. | | `email_intelligence_score_action` | azione | Azione quando il punteggio del rischio di frode dell'email è pari o superiore a `email_intelligence_score_threshold`. | | `email_intelligence_score_threshold` | intero | Punteggio del rischio di frode (`0`–`100`, più alto significa più rischio) che attiva `email_intelligence_score_action`. Predefinito `80`. | | `recent_email_breach_action` | azione | Azione quando l'email compare in una violazione di dati recente e nota. | | `frequent_email_breach_action` | azione | Azione quando l'email compare in molte violazioni di dati note. | | `email_social_enabled` | booleano | Attiva la verifica della presenza sui social: indica su quali piattaforme email, social, professionali, di e-commerce e di intrattenimento è registrato l'indirizzo verificato. **Viene addebitato un costo di \$0.05 per verifica** in aggiunta al prezzo della verifica email, indipendentemente da `email_enrichment_enabled`. | | `email_no_social_presence_action` | azione | Azione quando la verifica della presenza sui social non trova l'indirizzo registrato su nessuna delle piattaforme coperte, un comune segnale di identità sintetica. Predefinito `NO_ACTION`. | | `cross_org_fraud_email_action` | azione | Esito quando questo indirizzo è stato segnalato come fraudolento da un'altra organizzazione della rete. | | `status_rules` | array | Regole di stato personalizzate facoltative. | > [!NOTE] > > L'arricchimento con intelligence delle email è un componente aggiuntivo facoltativo. Quando `email_enrichment_enabled` è `true`, ogni verifica email completata viene arricchita con intelligence delle email e **fatturata \$0.05 per richiesta**, in aggiunta al costo standard della verifica email. L'azione basata sul punteggio ha effetto quando il punteggio di arricchimento è disponibile; le azioni sulle violazioni si applicano non appena l'arricchimento viene eseguito. > > La verifica della presenza sui social è un secondo componente aggiuntivo, separato. Quando `email_social_enabled` è `true`, ogni verifica email completata riporta anche su quali piattaforme online è registrato l'indirizzo (provider di posta elettronica, social media, servizi professionali, di e-commerce e di intrattenimento) ed è **fatturata \$0.05 per richiesta**. Può essere attivata con o senza `email_enrichment_enabled`: i due componenti aggiuntivi hanno prezzi e fatturazione indipendenti. Una ricerca che non trova l'indirizzo su nessuna delle piattaforme coperte è una risposta valida e fatturabile e attiva `email_no_social_presence_action`. Usa `email.social_profiles_registered` (il numero di piattaforme su cui l'indirizzo è registrato) per diramare il risultato in un grafo del workflow. ## Validazione su database Valore della funzionalità: `DATABASE_VALIDATION`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `database_validation_countries` | object | Codice paese ISO3 mappato a `{ "services": ["service_id"] }`. Usa gli ID dei servizi dal catalogo della Validazione su database. | | `database_validation_partial_match_action` | action | Azione da eseguire quando la validazione su database restituisce una corrispondenza parziale. | | `database_validation_no_match_action` | action | Azione da eseguire quando la validazione su database non restituisce alcuna corrispondenza. | | `database_validation_not_applicable_action` | action | Azione da eseguire quando la validazione su database non può essere eseguita perché il documento non contiene l'identificativo richiesto dai servizi configurati (ad esempio un passaporto senza numero di identificazione nazionale). Il valore predefinito è `NO_ACTION`. | | `database_validation_field_sources` | object | Da dove leggere un input della validazione su database che nessun passaggio precedente del grafo è in grado di compilare. `source` indica il produttore e `key` indica il valore al suo interno: una chiave di campo di Document AI per `document_ai`, un ID del nodo del questionario per `questionnaire`, e `expected_details.` oppure `metadata.` per `expected_data`. Le corrispondenze esatte di chiave con un passaggio a monte si risolvono automaticamente e non vengono volutamente salvate, così rinominare un campo di Document AI non inserisce mai in configurazione una mappatura obsoleta. Una voce malformata viene rifiutata con un `400` che indica il campo di input a cui appartiene. Struttura: `{"": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "\|\|expected_details.\|metadata."}}`. | | `status_rules` | array | Regole di stato personalizzate facoltative. | Esempio: ```json theme={null} { "feature": "DATABASE_VALIDATION", "config": { "database_validation_countries": { "BRA": { "services": ["SERVICE_ID_FROM_CATALOG"] } }, "database_validation_field_sources": { "tax_id": { "source": "expected_data", "key": "expected_details.document_number" } }, "database_validation_no_match_action": "REVIEW", "database_validation_partial_match_action": "REVIEW" } } ``` > [!WARNING] > > `database_validation_countries` è ciò che consente a questo passaggio di eseguire controlli. Una funzionalità > `DATABASE_VALIDATION` salvata senza di esso viene accettata e poi non esegue alcun controllo, quindi invia > sempre almeno un paese con almeno un ID di servizio. Un ID di servizio che il passaggio non può eseguire viene rifiutato con un `400` che lo indica e spiega il motivo, e non viene salvato nulla. Questo vale per un ID non presente nel catalogo, un ID appartenente a un altro paese, un servizio non ancora disponibile e un servizio offerto solo tramite l'endpoint autonomo [`POST /v3/database-validation/`](https://docs.didit.me/it/core-technology/database-validation/overview). Un servizio i cui input non sono forniti da nessun passaggio precedente viene rifiutato allo stesso modo, con l'elenco degli input mancanti. Un servizio già presente nel workflow salvato che non può più essere eseguito viene rimosso quando salvi di nuovo. Ad esempio, questo workflow dell'Argentina legge il numero di DNI e il sesso dalla Verifica dell'identità e li confronta con RENAPER senza selfie: ```json theme={null} { "workflow_label": "Argentina DNI check", "features": [ {"feature": "OCR"}, { "feature": "DATABASE_VALIDATION", "config": {"database_validation_countries": {"ARG": {"services": ["arg_renaper_data"]}}} } ] } ``` Usa invece `arg_renaper` dopo un passaggio `LIVENESS` per confrontare anche il selfie con la foto che RENAPER conserva. Per il punteggio di corrispondenza facciale e la soglia, consulta [RENAPER](https://docs.didit.me/it/api-reference/database-validation/argentina/renaper.md). ## Verifica del conto bancario Valore della funzionalità: `BANK_VERIFICATION`. L'utente verifica un conto bancario e il titolare dichiarato dalla banca viene confrontato con l'identità stabilita da un passaggio precedente del workflow. L'utente lo fa con uno di due metodi: l'accesso bancario (`open_banking`), in cui accede alla propria banca, oppure il controllo del conto (`account_lookup`), in cui digita i dati del conto e la banca conferma il nome associato. `bank_method_order` e il `methods` di ciascun paese scelgono quali metodi un paese offre e quale viene per primo; vedi [Metodi di verifica bancaria](https://docs.didit.me/it/core-technology/bank-verification/verification-methods.md). Il passaggio produce delle prove (un punteggio sul nome del titolare, il confronto che lo ha prodotto, i codici delle motivazioni), e le chiavi `bank_*_action` trasformano tali prove in uno stato. Due elementi determinano se il nodo esegue un'operazione. `bank_countries` è una lista di autorizzazioni, quindi una mappa vuota non offre alcuna banca ed esegue nessun controllo. Inoltre il titolare deve avere qualcosa con cui essere confrontato: inserisci prima un passaggio `OCR`, `DATABASE_VALIDATION` o `QUESTIONNAIRE`, invia `expected_details` alla creazione della sessione, oppure mappa tu stesso i campi con `bank_field_sources`. Senza nessuno di questi, la titolarità può essere solo `unknown`, che è ciò che decide `bank_reference_identity_missing_action`. > [!NOTE] > > La verifica del conto bancario è ancora in fase di rilascio, quindi un nodo `BANK_VERIFICATION` viene accettato solo su un account in cui è stato abilitato. Altrove il salvataggio viene rifiutato e lo indica. Anche il percorso che esegue il passaggio non si configura qui: lo impostano per te la coppia `provider_key` e `fallback_to_native`, che il [Marketplace](https://docs.didit.me/it/console/marketplace.md) della console imposta per te. ### Collegamento di un conto | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `bank_countries` | object | In quali paesi un utente può collegare una banca. È una lista di autorizzazioni: una mappa vuota significa che il nodo non offre nulla e non esegue nulla. `institutions` restringe il selettore a specifici ID di istituto, `"all"` offre ogni banca nel paese in grado di verificare l'identità. Un paese che nessun percorso del nodo serve viene mantenuto: offre solo i suoi fallback e Continua senza la tua banca, vedi [Quando la persona non può verificare la propria banca](https://docs.didit.me/it/core-technology/bank-verification/fallbacks.md). Un codice che non indica un paese viene rifiutato al salvataggio. `methods` imposta quali tra accesso bancario (`open_banking`) e controllo del conto (`account_lookup`) il paese offre, in ordine, al posto di `bank_method_order`: l'utente parte dal primo e gli viene offerto il secondo come alternativa. Un paese abilitato il cui `methods` nomina un metodo che nessun percorso del nodo serve lì viene rifiutato al salvataggio, e lo stesso vale per un paese servito da un percorso che `methods` lascia senza alcun metodo. Forma: `{"": {"enabled": true\|false, "institutions": ["", ...]\|"all", "methods"?: ["open_banking"\|"account_lookup", ...]}}`. | | `bank_method_order` | string\[] | Quali dei due metodi il passaggio offre, e in quale ordine, in ogni paese che non imposta un proprio `methods`: `open_banking` (accesso bancario: l'utente accede alla propria banca, e solo questo metodo legge saldi, transazioni e redditi) e `account_lookup` (controllo del conto: nessun accesso, solo la titolarità). In ogni paese l'utente parte dal primo metodo che un percorso serve lì e gli viene offerto l'altro come alternativa; un metodo che nessun percorso serve in un paese viene escluso lì. Almeno un metodo. Un salvataggio che non ne invia nessuno ottiene `["open_banking", "account_lookup"]`, a meno che non invii `bank_open_banking_enabled` o `bank_account_lookup_enabled`, che allora lo impostano. | | `bank_scopes` | object | A quali dati viene chiesto all'utente di acconsentire alla condivisione. `ownership` è ciò che il prodotto verifica e non può essere disattivato. `identifiers` mostra l'IBAN o il numero di conto senza maschera; `balances`, `transactions` e `income` leggono dati finanziari reali, vengono fatturati separatamente e vengono rifiutati al salvataggio se la tua applicazione non dispone dell'autorizzazione ai dati finanziari. Solo l'accesso bancario legge dati: un paese che offre il controllo del conto non viene rifiutato, e un utente che verifica tramite controllo del conto supera il passaggio senza i dati, che il risultato elenca in `financial_data.not_collected`. Un ambito disattivato non viene mai richiesto, quindi la banca non lo mostra mai nella sua schermata di consenso. Predefinito: solo `ownership`. Forma: `{"ownership": true, "identifiers": true\|false, "balances": true\|false, "transactions": true\|false, "income": true\|false}`. | | `bank_eligible_account_types` | string\[] | Quali tipi di conto l'utente può scegliere: `checking`, `current`, `savings`, `business` o `other`. Carte di credito, prestiti e conti di investimento non sono mai idonei, perché non stabiliscono la titolarità di un conto di pagamento. Predefinito: current e checking. | | `bank_account_selection` | string | `user` lascia che l'utente scelga quale dei conti collegati verificare; `auto` prende il primo idoneo. | | `bank_require_oauth_only` | boolean | Offre solo istituti raggiungibili tramite OAuth o da app a app, mai una schermata legacy di acquisizione delle credenziali. Nei mercati in cui l'open banking rende già OAuth l'unico percorso, questo non cambia nulla. | | `bank_max_attempts` | integer | Quanti tentativi di accesso bancario ha l'utente, da `1` a `5`; anche un micro-deposito o il caricamento di un estratto conto ne consuma uno. Il controllo del conto ha il proprio `bank_account_check_max_attempts`. Una volta che tutti i modi ancora disponibili per verificare l'utente, incluso il caricamento di un estratto conto, hanno esaurito i tentativi senza un collegamento riuscito, decide `bank_attempts_exhausted_action`. | | `bank_connection_timeout_minutes` | integer | Per quanto tempo resta aperto un collegamento avviato prima che il tentativo venga abbandonato, da `5` a `60` minuti. | | `bank_allow_skip` | boolean | Ritirato da `bank_continue_without_bank`: ora l'utente può sempre continuare senza una banca. Per una versione viene letto da un salvataggio che non invia `bank_continue_without_bank`: `true` imposta `from_start`, qualsiasi altro valore `when_needed`. Ogni salvataggio lo riscrive: `true` per `from_start`, `false` per `when_needed`. | ### Quando l'utente non può verificare L'utente può sempre continuare senza una banca, e il passaggio non lo lascia mai bloccato. Vedi [Quando la persona non può verificare la propria banca](https://docs.didit.me/it/core-technology/bank-verification/fallbacks.md). | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `bank_continue_without_bank` | string | Quando il passaggio mostra **Continue without your bank**. `when_needed`, il valore predefinito, lo mostra una volta che nessun metodo funziona per il paese o la banca dell'utente, quando la sua banca non è raggiungibile e nessun altro metodo avrebbe potuto verificarlo, per esempio perché anche il controllo del conto non è riuscito a raggiungere la banca, oppure quando dichiara di non avere l'home banking. `from_start` lo mostra anche nella prima schermata. Non può essere disattivato. Un salvataggio che non invia né questa chiave né `bank_allow_skip` ottiene `when_needed`. | | `bank_statement_standalone_enabled` | boolean | Insieme a `bank_statement_enabled`, offre anche il caricamento dell'estratto conto quando non è avvenuto alcun tentativo bancario, in qualsiasi paese, incluso uno non servito da nessun percorso di accesso bancario o verifica del conto. Viene quindi fatturato autonomamente, come `bank_statement_upload`, a USD 0.20 per estratto valutato, prima della tariffa del tuo contratto o del prezzo speciale: vedi [Prezzi](https://docs.didit.me/it/core-technology/bank-verification/fallbacks.md#prezzi). Le sessioni sandbox possono testarlo senza fatturazione. Attivo per impostazione predefinita. | Ciò che accade alla sessione quando l'utente prosegue è determinato da `bank_unsupported_action`, `bank_attempts_exhausted_action` o `bank_skipped_action`, a seconda del motivo per cui ha proseguito, a meno che un tentativo valutato in precedenza non abbia già deciso il passaggio: vedi [Azioni del verdetto](#azioni-di-esito). ### Confronto del titolare | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `bank_reference_identity` | string | Quale passaggio precedente fornisce l'identità con cui viene confrontato il titolare: `kyc` (Verifica dell'identità), `database_validation`, `expected_details` (ciò che hai inviato alla creazione della sessione), `questionnaire`, oppure `auto` per usare quella prodotta dal workflow. Il passaggio che l'ha effettivamente fornita viene restituito nel risultato come `reference_identity_source`. | | `bank_field_sources` | object | Dove leggere un campo dell'identità di riferimento quando nessun passaggio precedente del grafo può compilarlo. La CHIAVE della mappa è una tra `full_name`, `first_name`, `last_name`, `address`; `source` indica il produttore e `key` indica il valore al suo interno - una chiave di campo Document AI per `document_ai`, un id di nodo del questionario per `questionnaire`, e `expected_details.` o `metadata.` per `expected_data`. Un valore sotto `expected_details.` può riferirsi solo a un campo che il payload di creazione della sessione contiene davvero: `address`, `country`, `date_of_birth`, `first_name`, `gender`, `id_country`, `identification_number`, `ip_address`, `last_name`, `nationality` o `poa_country`. Una voce malformata viene rifiutata al salvataggio, non ignorata. Formato: `{"full_name"\|"first_name"\|"last_name"\|"address": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "\|\|expected_details.\|metadata."}}`. | | `bank_name_match_threshold` | integer | Con un punteggio pari o superiore a questo, il nome del titolare corrisponde. da `50` a `100`, con valore predefinito `85`. | | `bank_partial_match_floor` | integer | Sotto questo punteggio il nome del titolare è una mancata corrispondenza. `0` a `99`, predefinito `70`. La fascia tra il minimo e la soglia è la corrispondenza parziale, quindi il minimo deve essere strettamente inferiore alla soglia, altrimenti il salvataggio viene rifiutato. Un `null` esplicito significa "usa il valore predefinito" anche qui, motivo per cui una soglia di `50` senza minimo viene rifiutata: viene verificata come `50` rispetto al minimo predefinito di `70`. | | `bank_require_address_match` | boolean | Richiede inoltre che l'indirizzo del titolare corrisponda. Un nome che ha raggiunto la soglia, ma il cui indirizzo ottiene un punteggio inferiore, scende a corrispondenza parziale. Un istituto che non restituisce alcun indirizzo esonera dal requisito; una sessione senza un indirizzo proprio con cui confrontarlo non è esonerata e finisce in corrispondenza parziale. Disattivato per impostazione predefinita. | | `bank_use_provider_score` | boolean | Legge anche il punteggio di corrispondenza del nome calcolato dall'istituto e lo lascia decidere quando è superiore a quello di Didit o quando Didit non aveva un nome del titolare da confrontare. Un risultato deciso in questo modo riporta `provider_only` come metodo di corrispondenza, e una connessione che non ha restituito tale punteggio registra un avviso `provider_score_unavailable`. Attivo per impostazione predefinita. | | `bank_show_match_result_to_user` | boolean | Mostra all'utente il risultato della titolarità all'interno del flusso di verifica. Se disattivato, viene registrato nella sessione ma non viene mai mostrato. | ### Verifica del conto Queste chiavi si applicano solo alla verifica del conto. L'accesso bancario mantiene le proprie corrispondenze quasi esatte e il proprio `bank_max_attempts`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `bank_account_check_accept_close_match` | boolean | Quando è attivo (impostazione predefinita), un nome a cui la banca assegna un punteggio compreso tra `bank_partial_match_floor` e `bank_name_match_threshold` è una corrispondenza quasi esatta: l'utente conferma il nome registrato presso la banca quando `bank_suggest_holder_name` è attivo, e `bank_partial_match_action` decide. Quando è disattivato, quella corrispondenza quasi esatta è una mancata corrispondenza (`OWNER_NAME_MISMATCH`, decisa da `bank_no_match_action`) e consuma il tentativo. | | `bank_account_check_max_attempts` | integer | Quante verifiche del conto ha a disposizione l'utente, da `1` a `5`, `3` se non impostato: quante volte può digitare i dati del conto per una verifica a cui la banca risponde. È un conteggio separato da `bank_max_attempts`. Una verifica rifiutata per i dati inseriti (ad esempio, un IBAN non valido) o una verifica a cui la banca non ha potuto rispondere non consuma alcun tentativo. | ### Dati finanziari `bank_expected_currencies` funziona da solo con il consenso predefinito `ownership`. Le altre tre chiavi leggono dati finanziari reali, quindi ognuna richiede il corrispondente ambito di consenso in `bank_scopes`, e il salvataggio viene rifiutato senza di esso. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `bank_expected_currencies` | string\[] | Valute ISO 4217 in cui ci si aspetta che sia denominato il conto. Vuoto significa qualsiasi valuta; una discrepanza viene segnalata tramite `bank_currency_mismatch_action`. | | `bank_min_balance` | number | Saldo disponibile minimo, nella valuta propria del conto. Al di sotto, scatta `bank_low_balance_action`. Richiede l'ambito `balances`. `0` è una soglia reale e non equivale a omettere la chiave: un conto in scoperto fa scattare l'azione. L'azione predefinita è `NO_ACTION`, che lascia invariato il verdetto, quindi per rifiutare un conto in scoperto occorre anche `bank_low_balance_action: "DECLINE"`. | | `bank_transactions_history_days` | intero | Per quanto tempo indietro viene letto lo storico delle transazioni, da `30` a `365` giorni. Predefinito `90`. Richiede lo scope `transactions`. | | `bank_refresh_enabled` | booleano | Riacquisisce i dati finanziari del conto dopo che il passaggio è già stato deciso, finché il consenso bancario è valido. Richiede almeno uno degli scope `balances`, `transactions` o `income`. Un consenso che scade successivamente è gestito da `bank_consent_expired_action`. | ### Cosa viene memorizzato | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `bank_store_full_identifiers` | booleano | Memorizza gli identificativi del conto non mascherati anziché mascherati. Richiede lo scope `identifiers`. Anche in questo caso, la forma non mascherata viene restituita solo a un chiamante che dispone dell'autorizzazione di lettura della verifica bancaria. | | `bank_store_raw_owner_data` | booleano | Conserva accanto alle prove di titolarità i dati del titolare forniti dall'istituto. Se disattivato, viene conservato solo il confronto stesso: punteggi, metodo di corrispondenza e codici motivo. | ### Azioni di esito Ogni chiave qui elencata accetta `DECLINE`, `REVIEW` o `NO_ACTION`, salvo che sia contrassegnata come limitata, e ricade sul valore predefinito indicato sotto quando la si omette o si invia `null`. Nessuna evidenza di titolarità non positiva approva per impostazione predefinita, e solo una prova dimostrabile contro l'utente porta al rifiuto. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `bank_no_match_action` | azione limitata | Esito quando il titolare del conto non è dimostrabilmente la persona verificata: il punteggio migliore sul nome è inferiore a `bank_partial_match_floor`. Usa `DECLINE` o `REVIEW`. Il valore predefinito è `DECLINE`. | | `bank_partial_match_action` | azione | Esito quando il nome del titolare rientra tra `bank_partial_match_floor` e `bank_name_match_threshold`. Il valore predefinito è `REVIEW`, e non approva mai per impostazione predefinita. | | `bank_not_verifiable_action` | azione | Esito quando l'istituto si è connesso ma non ha restituito un'identità del titolare da confrontare. Il valore predefinito è `REVIEW`. | | `bank_unknown_action` | azione | Esito quando le evidenze non sono state recuperate dopo i tentativi, cioè un errore transitorio. Il valore predefinito è `REVIEW`. | | `bank_reference_identity_missing_action` | azione | Esito quando nessun passaggio precedente ha prodotto un'identità con cui confrontare il titolare, per cui la titolarità può essere solo `unknown`. Il valore predefinito è `REVIEW`. | | `bank_joint_account_action` | azione | Esito quando il conto ha più di un titolare. Il valore predefinito è `NO_ACTION`. | | `bank_business_account_action` | azione | Esito quando l'istituto classifica il titolare come azienda anziché come persona. Il valore predefinito è `REVIEW` in un workflow per persone, e `NO_ACTION` in un workflow aziendale (KYB), dove il titolare aziendale è ciò che la sessione si aspetta di trovare. | | `bank_unsupported_action` | azione | Esito quando l'utente prosegue senza banca perché nessun metodo può verificare il suo paese o la sua banca: nessun accesso bancario o controllo del conto è disponibile per il paese, oppure la banca scelta non può essere usata in questo passaggio. Il risultato ha quindi `continued_without_bank` impostato su true e `NOT_COVERED` nei codici motivo. Il valore predefinito è `REVIEW`. | | `bank_skipped_action` | azione limitata | Esito quando l'utente sceglie di continuare senza la tua banca pur essendo disponibile un modo per verificare. Il risultato ha quindi `continued_without_bank` impostato su true e `SKIPPED` nei codici motivo. Usa `DECLINE` o `REVIEW`. Il valore predefinito è `REVIEW`. | | `bank_attempts_exhausted_action` | azione limitata | Esito quando l'utente ha esaurito i tentativi di ogni modo di verifica ancora proposto, incluso il caricamento di un estratto conto (`bank_max_attempts`, e `bank_account_check_max_attempts` dove il paese offre il controllo del conto), senza una connessione riuscita, anche quando poi continua senza banca. Usa `DECLINE` o `REVIEW`. Il valore predefinito è `DECLINE`. | | `bank_consent_expired_action` | azione | Esito quando il consenso bancario scade dopo che il passaggio è già stato deciso. Ha effetto solo con `bank_refresh_enabled`. Il valore predefinito è `NO_ACTION`. | | `bank_currency_mismatch_action` | azione | Esito quando la valuta del conto non è presente in `bank_expected_currencies`. Il valore predefinito è `NO_ACTION`. | | `bank_country_mismatch_action` | azione | Esito quando il paese dell'istituto è diverso da quello previsto o da quello del documento. Il valore predefinito è `NO_ACTION`. | | `bank_low_balance_action` | azione | Esito quando il saldo disponibile è inferiore a `bank_min_balance`. Richiede lo scope `balances`. Il valore predefinito è `NO_ACTION`. | | `status_rules` | array | Regole di stato personalizzate facoltative. | ### Altri controlli Queste chiavi sono facoltative. Ogni chiave di azione accetta `DECLINE`, `REVIEW` o `NO_ACTION`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `bank_abandoned_action` | azione | Esito quando il passaggio si chiude senza una corrispondenza, perché la persona ha lasciato la verifica presso la propria banca e non è più tornata (un tentativo è scaduto). | | `bank_account_age_action` | azione | Esito quando il conto è più recente di `bank_account_age_days`, un tipico schema di prestanome. | | `bank_account_age_days` | intero | Un conto il cui storico inizia da meno di questo numero di giorni è considerato nuovo; valore da 1 a 365, predefinito 30. Viene letto dallo storico delle transazioni, quindi solo con lo scope `transactions`. | | `bank_account_lookup_enabled` | booleano | Ritirato: usa `bank_method_order` e `bank_countries..methods`. Viene letto per una release quando un salvataggio non invia `bank_method_order`: con `bank_open_banking_enabled`, imposta l'ordine dei metodi e, se attivo, il controllo del conto dopo l'accesso bancario; se disattivato o non impostato, il controllo del conto viene omesso. Ogni salvataggio lo riscrive come indicazione se almeno un paese offre il controllo del conto. | | `bank_account_type_action` | azione | Esito quando il conto verificato è un conto di risparmio. | | `bank_address_match_threshold` | intero | A questo punteggio o superiore l'indirizzo del titolare corrisponde; valore da 50 a 100, predefinito 70. Viene letto solo con `bank_require_address_match`. | | `bank_address_mismatch_action` | azione | Esito quando l'indirizzo del titolare è diverso, il che trasforma una corrispondenza in una corrispondenza approssimativa. Solo con `bank_require_address_match`. | | `bank_auto_add_countries` | booleano | Propone ogni paese per cui questo nodo dispone di un percorso utilizzabile, anche quelli aggiunti dopo il salvataggio del nodo, esclusi i paesi disattivati in `bank_countries`. Disattivato quando la chiave è assente, così un nodo esistente non si amplia da solo. | | `bank_cash_flow_action` | azione | Esito quando il denaro entra e subito esce, oppure arrivano molti piccoli bonifici (flusso di cassa di transito). Richiede lo scope `transactions`. | | `bank_dob_match_enabled` | booleano | Confronta la data di nascita del titolare, dove la banca la condivide, con quella verificata. Una mancata corrispondenza non modifica mai il risultato sull'assetto proprietario: attiva `bank_dob_mismatch_action`. Attivo per impostazione predefinita. | | `bank_dob_match_threshold` | intero | A partire da questo punteggio la data di nascita corrisponde, da 50 a 100, con valore predefinito 70. Una data coincide o non coincide, quindi ottiene 100 o 0. | | `bank_dob_mismatch_action` | azione | Esito quando la data di nascita del titolare è diversa. Solo con `bank_dob_match_enabled`. | | `bank_email_match_enabled` | booleano | Confronta l'email registrata presso la banca con l'email verificata della sessione. Una mancata corrispondenza attiva `bank_email_mismatch_action`. Disattivo per impostazione predefinita. | | `bank_email_match_threshold` | intero | A partire da questo punteggio l'email corrisponde, da 50 a 100, con valore predefinito 70. | | `bank_email_mismatch_action` | azione | Esito quando l'email del titolare è diversa. Solo con `bank_email_match_enabled`. | | `bank_evidence_retention_days` | intero | Elimina le evidenze bancarie questo numero di giorni dopo l'esito: 30, 90, 365 o 1825. Null le conserva insieme alla sessione. Vengono eliminati: i dati del titolare, l'identità con cui sono stati confrontati, gli identificativi del conto, i dati finanziari e un estratto conto caricato; una connessione ancora attiva viene revocata. Esito, punteggi e codici motivo restano. Eliminare la sessione cancella tutto, qualunque dei due eventi avvenga per primo. | | `bank_fallback_used_action` | azione | Esito quando il conto è stato verificato con micro-depositi o con il caricamento di un estratto conto. | | `bank_match_any_holder` | booleano | Un conto cointestato o condiviso corrisponde quando QUALSIASI titolare elencato corrisponde alla persona. Disattivo: può corrispondere solo il primo titolare elencato dalla banca. Attivo per impostazione predefinita. | | `bank_microdeposits_enabled` | booleano | Offri i micro-depositi come alternativa: due piccoli versamenti arrivano sul conto e la persona inserisce gli importi. Proposti solo in un paese il cui percorso può inviarli, dopo un tentativo di verifica bancaria a pagamento nella stessa sessione. Incluso senza costi aggiuntivi; il cliente paga il prezzo del percorso una sola volta. Le sessioni sandbox possono testarli senza addebito. Il titolare è il nome verificato dalla sessione, che la persona dichiara essere quello dell'intestatario del conto, quindi un conto verificato registra un avviso `holder_declared`. Attivo per impostazione predefinita. | | `bank_mule_score_action` | azione | Esito quando il punteggio mule è pari o superiore a `bank_mule_score_threshold`. | | `bank_mule_score_threshold` | intero | A partire da questo punteggio mule, da 0 a 100, `bank_mule_score_action` si attiva; il valore predefinito è 70. Il punteggio combina un conto nuovo, un flusso di cassa di transito, un saldo svuotato e molti piccoli trasferimenti in entrata, letti dallo storico delle transazioni (lo scope `transactions`). | | `bank_open_banking_enabled` | booleano | Ritirato: usa `bank_method_order` e `bank_countries..methods`. Viene letto per una sola release da un salvataggio che non invia `bank_method_order`: con `bank_account_lookup_enabled`, imposta l'ordine sull'accesso bancario quando l'impostazione è attiva o non è impostata. Ogni salvataggio lo riscrive come indicazione se almeno un paese offre l'accesso bancario. | | `bank_phone_match_enabled` | booleano | Confronta il telefono registrato presso la banca con il telefono verificato della sessione. Una mancata corrispondenza attiva `bank_phone_mismatch_action`. Disattivo per impostazione predefinita. | | `bank_phone_match_threshold` | intero | A partire da questo punteggio il telefono corrisponde, da 50 a 100, con valore predefinito 70. | | `bank_phone_mismatch_action` | azione | Esito quando il telefono del titolare è diverso. Solo con `bank_phone_match_enabled`. | | `bank_popular_mode` | stringa | `auto` (predefinito) ordina le banche più diffuse in base a quelle che le persone del paese collegano di più; `manual` mostra invece i `popular_institutions` di ogni paese da `bank_countries`, nell'ordine indicato. | | `bank_statement_document_checks_action` | azione | Esito quando un estratto conto caricato presenta segni di modifica o alterazione. Il valore predefinito è `REVIEW`. | | `bank_statement_enabled` | booleano | Offri il caricamento di un estratto conto come alternativa: un estratto conto degli ultimi 3 mesi, controllato per verificarne l'alterazione, il cui nome del titolare viene confrontato come quello del titolare registrato dalla banca. Incluso senza costi aggiuntivi dopo un tentativo di verifica bancaria a pagamento nella stessa sessione. Con `bank_statement_standalone_enabled` viene proposto anche senza un tentativo bancario precedente, in qualsiasi paese, e in quel caso viene fatturato a parte. Le sessioni sandbox possono testarlo senza addebito. Disattivo per impostazione predefinita. | | `bank_suggest_holder_name` | booleano | In caso di corrispondenza quasi completa, mostra alla persona il nome con cui la banca registra il conto e chiedele di confermare che il conto è suo oppure di collegarne un altro. La risposta viene registrata come `holder_confirmation`; confermando, il passaggio termina con `bank_partial_match_action`. Attivo per impostazione predefinita. | | `fallback_to_native` | booleano | Indica se una connessione tramite marketplace che non può essere stabilita passa al percorso nativo di Didit. Disattivo per impostazione predefinita: un passaggio silenzioso consumerebbe il saldo Didit per una sessione che ti aspettavi venisse eseguita con il tuo contratto presso il provider. Una connessione di ripiego viene registrata come `credential_source = native` e fatturata al prezzo nativo. | | `provider_key` | stringa | Quale percorso esegue il passaggio. Vuoto (predefinito) indica la Verifica bancaria nativa di Didit, un prodotto indipendente dal provider che Didit instrada verso il fornitore regionale di open banking che serve il paese e l'istituto dell'utente, con i contratti e la fatturazione di Didit. Un valore indica un provider MARKETPLACE le cui credenziali sono state collegate a questa applicazione: la sessione viene quindi eseguita, fatturata e revocata sul tuo account presso il provider, e Didit addebita solo la commissione della piattaforma marketplace. Un provider non collegato viene rifiutato al salvataggio. | Esempio di oggetto `config`, per un account in cui la Verifica bancaria è attiva e il percorso selezionato copre il paese che indichi: ```json theme={null} { "bank_method_order": ["open_banking", "account_lookup"], "bank_countries": { "ESP": { "enabled": true, "institutions": "all" } }, "bank_scopes": { "ownership": true }, "bank_eligible_account_types": ["checking", "current"], "bank_name_match_threshold": 85, "bank_partial_match_floor": 70, "bank_partial_match_action": "REVIEW", "bank_no_match_action": "DECLINE" } ``` > [!WARNING] > > `bank_countries` è ciò che fa funzionare questo passaggio, e viene verificato rispetto al percorso su cui gira il nodo, non rispetto a un elenco globale. Un paese in cui quel percorso non può stabilire l'assetto proprietario del conto viene rifiutato al salvataggio e indicato nell'errore, quindi leggi l'errore invece di presumere che il paese sia stato accettato e verrà saltato in fase di esecuzione. ## AML Valore della funzionalità: `AML`. Per lo screening delle persone nel KYC, usa questi campi: | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `is_aml_ongoing_monitoring_enabled` | boolean | Attiva il monitoraggio AML continuo. | | `aml_score_approve_threshold` | integer | Soglia di approvazione. | | `aml_score_review_threshold` | integer | Soglia di revisione. | | `aml_match_score_threshold` | integer | Soglia del punteggio di corrispondenza per le possibili corrispondenze. | | `aml_name_weight` | integer | Peso del nome. Se viene fornito un peso AML, la somma dei pesi di nome, data di nascita e paese deve essere `100`. | | `aml_dob_weight` | integer | Peso della data di nascita. | | `aml_country_weight` | integer | Peso del paese. | | `create_cases_on_hit` | boolean | Apre automaticamente un caso quando lo screening restituisce una corrispondenza, invece di lasciare che la corrispondenza venga gestita dalla sessione. Disattivato per impostazione predefinita. | | `case_blueprint` | uuid | Il modello del caso da cui viene costruito il caso creato automaticamente. Ha effetto solo con `create_cases_on_hit`; se non è impostato, viene usato il valore predefinito dell'account. | | `status_rules` | array | Regole di stato personalizzate facoltative. | Per lo screening delle aziende nel KYB, usa questi campi: | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `kyb_score_approve_threshold` | integer | Soglia di approvazione AML per l'azienda. | | `kyb_score_review_threshold` | integer | Soglia di revisione AML per l'azienda. | | `kyb_enable_ongoing_monitoring` | boolean | Attiva il monitoraggio AML continuo KYB. | | `kyb_company_aml_match_score_threshold` | integer | Soglia del punteggio di corrispondenza AML per l'azienda. | | `kyb_company_aml_name_weight` | integer | Peso della ragione sociale. Se forniti, la somma dei pesi AML dell'azienda deve essere `100`. | | `kyb_company_aml_dob_weight` | integer | Peso della data di costituzione o della data di nascita. | | `kyb_company_aml_country_weight` | integer | Peso del paese. | ### Screening di un'entità estratta da un passaggio Document AI Un passaggio AML legge normalmente chi sottopone a screening dal passaggio `OCR` (una persona) o dal passaggio `KYB_REGISTRY` (un'azienda). Un workflow il cui unico passaggio di estrazione è `DOCUMENT_AI`, cioè documenti non standardizzati come un certificato fiscale o un atto costitutivo, non ha nessuno dei due, quindi deve indicare da dove provengono gli input di ogni screening. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `aml_field_sources` | object | Dove leggere l'entità che questo passaggio sottopone a screening. `source` indica il produttore e `key` indica il valore al suo interno: una chiave di campo Document AI per `document_ai`, un id di nodo del questionario per `questionnaire`, e `expected_details.` oppure `metadata.` per `expected_data`. La CHIAVE della mappa è uno dei quattro input dello screening (`full_name`, `date_of_birth`, `nationality`, `document_number`), letti per un'azienda come ragione sociale, data di costituzione, paese e numero di registrazione. Un campo Document AI già indicato come uno di questi quattro viene mappato automaticamente e non viene salvato di proposito, così che rinominarlo non fissi mai una mappatura obsoleta. Una mappatura esplicita prevale sia sulla mappatura automatica sia sul documento d'identità, e una mappatura che a runtime non restituisce nulla lascia vuoto l'input invece di ricorrere ad altro. In un workflow aziendale (KYB) l'azienda restituita da un passaggio `KYB_REGISTRY` fa fede: solo una mappatura esplicita può sovrascrivere uno dei suoi input, la mappatura automatica non viene applicata sopra un record del registro, e senza un passaggio di registro la mappatura costituisce l'intera identità. Forma: `{"full_name"\|"date_of_birth"\|"nationality"\|"document_number": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "\|\|expected_details.\|metadata."}}` | | `aml_entity_type` | string | `person` oppure `company`. Il valore predefinito è `person` in un workflow persona (KYC) e `company` in un workflow business (KYB). Imposta `company` per sottoporre a screening l'azienda indicata in un documento caricato senza un passaggio `KYB_REGISTRY`: il provider cerca nei registri aziendali e il punteggio di corrispondenza viene calcolato considerando l'entità come un'azienda. | | `aml_incomplete_data_action` | action | Verdetto quando lo screening è stato eseguito su un'identità incompleta (nome, data di nascita e paese). `REVIEW` è il valore predefinito. `NO_ACTION` procede con dati ridotti per un workflow che contiene consapevolmente solo un nome. Lo screening viene eseguito in ogni caso e il log dei dati parziali viene registrato in ogni caso: questa impostazione decide soltanto cosa succede allo stato. | Esempio: screening dell'azienda indicata in un'*acta constitutiva* messicana, senza alcun documento d'identità nel workflow: ```json theme={null} { "feature": "AML", "config": { "aml_entity_type": "company", "aml_field_sources": { "full_name": { "source": "document_ai", "key": "razon_social" }, "document_number": { "source": "document_ai", "key": "rfc" }, "date_of_birth": { "source": "document_ai", "key": "fecha_constitucion" }, "nationality": { "source": "document_ai", "key": "pais" } }, "aml_incomplete_data_action": "REVIEW" } } ``` > [!WARNING] > > Senza un passaggio `OCR` e senza un passaggio `KYB_REGISTRY` prima di esso, un passaggio `AML` deve poter compilare > `full_name`: senza un nome non c'è ricerca presso il provider. Un workflow che non mappa nulla, o che mappa una > chiave Document AI che nessun passaggio a monte estrae, viene rifiutato al salvataggio invece di essere salvato e lasciato > a eseguire uno screening vuoto. La precisione dell'AML dipende direttamente da quanti identificatori fornisci: uno > screening basato solo sul nome è ciò che genera un alto volume di falsi positivi. ## Analisi dispositivo e IP Valore della funzionalità: `IP_ANALYSIS`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `ip_mismatch_action` | azione | Azione da eseguire quando la geolocalizzazione dell'IP non corrisponde ai dati attesi. | | `ip_location_not_determined_action` | azione | Esito quando non è stato registrato alcun indirizzo IP che identifichi l'utente finale, quindi la sessione non ha alcuna posizione IP: paese, città, ISP, coordinate e fuso orario non sono disponibili, e `ip_geofencing_by_country`, il confronto con il paese del documento e i controlli VPN/data center non possono essere eseguiti. Il valore predefinito è `NO_ACTION`, che mantiene visibile sulla sessione l'avviso `IP_LOCATION_NOT_DETERMINED` senza modificarne l'esito; imposta `REVIEW` o `DECLINE` se una sessione senza posizione non deve superare la verifica. | | `vpn_detection_action` | azione | Azione da eseguire quando viene rilevato l'uso di una VPN o di un proxy. | | `expected_ip_mismatch_action` | azione | Azione da eseguire quando l'IP non corrisponde all'IP atteso. | | `duplicated_ip_action` | azione | Azione da eseguire quando l'IP viene riutilizzato in modo sospetto. | | `duplicated_device_action` | azione | Azione da eseguire quando lo stesso fingerprint persistente del dispositivo viene riutilizzato in sessioni con valori `vendor_data` diversi. | | `recovered_device_action` | azione | Azione da eseguire quando il recupero del fingerprint v2 collega la sessione a un dispositivo già visto in precedenza con alta affidabilità, dopo che l'ID persistente del dispositivo è cambiato. | | `is_ip_geofencing_enabled` | booleano | Attiva le restrizioni di geofencing IP. Se impostato su `false`, `ip_geofencing_by_country` viene mantenuto ma non applicato. | | `ip_geofencing_by_country` | oggetto | Regole di localizzazione IP per paese, con chiave il codice paese ISO-3: `{"USA": {"allowed": true, "states": {"California": {"allowed": false}}}}`. Le voci per stato o regione prevalgono sul flag del paese; i paesi non elencati sono consentiti. | | `ip_geofencing_action` | azione | Azione da eseguire quando l'IP della sessione si trova in un paese o in uno stato/regione non consentito. Il valore predefinito è `DECLINE`. | | `automation_detected_action` | azione | Esito quando la sessione sembra guidata da un'automazione anziché da una persona. | | `cross_org_fraud_device_action` | azione | Esito quando questo dispositivo è stato segnalato come fraudolento da un'altra organizzazione della rete. | | `cross_org_fraud_ip_action` | azione | Esito quando questo IP è stato segnalato come fraudolento da un'altra organizzazione della rete. | | `device_app_tampered_action` | azione | Esito quando il file binario dell'applicazione host sembra manomesso. | | `device_blocklist_action` | azione | Esito quando il dispositivo è presente nella blocklist dell'organizzazione. | | `device_debugger_action` | azione | Esito quando un debugger è collegato all'applicazione host. | | `device_emulator_action` | azione | Esito quando il dispositivo è un emulatore anziché un hardware reale. | | `device_hooking_action` | azione | Esito quando viene rilevato hooking o strumentazione a runtime. | | `device_integrity_missing_action` | azione | Esito quando non è stata restituita alcuna attestazione di integrità del dispositivo da parte della piattaforma. | | `device_rooted_action` | azione | Esito quando il dispositivo ha il root o il jailbreak. | | `multiple_devices_action` | azione | Esito quando la sessione è stata gestita da più di un dispositivo. | | `device_liveness_attack_history_action` | azione | Azione da eseguire quando lo stesso dispositivo (riconosciuto tramite il suo ID persistente) è stato usato in una sessione precedente di un altro utente, la cui acquisizione per il rilevamento della vitalità è stata giudicata un attacco (avviso `DEVICE_LINKED_TO_LIVENESS_ATTACK`). Il valore predefinito è `NO_ACTION`. | | `device_model_inconsistency_action` | azione | Azione da eseguire quando lo stesso dispositivo (riconosciuto tramite il suo ID persistente) è stato segnalato con un modello diverso in una sessione precedente (avviso `DEVICE_MODEL_INCONSISTENT`). Il valore predefinito è `NO_ACTION`. | | `status_rules` | array | Regole di stato personalizzate facoltative. | Esempio: ```json theme={null} { "feature": "IP_ANALYSIS", "config": { "vpn_detection_action": "REVIEW", "duplicated_device_action": "REVIEW", "recovered_device_action": "REVIEW", "is_ip_geofencing_enabled": true, "ip_geofencing_by_country": { "USA": { "allowed": true, "states": { "California": { "allowed": false } } }, "RUS": { "allowed": false, "states": null } }, "ip_geofencing_action": "DECLINE" } } ``` Usa `recovered_device_action` separatamente da `duplicated_device_action` quando vuoi monitorare i dispositivi recuperati con alta affidabilità prima di rifiutarli automaticamente. Questo è utile durante il rilascio, perché le corrispondenze dei dispositivi recuperati sono progettate per individuare reti fraudolente, ma vanno comunque calibrate sul tuo traffico. ## Verifica della posizione Valore della funzionalità: `GEOLOCATION`. Verifica dove si trova la persona durante la verifica, in base alla posizione del dispositivo o alla posizione IP della connessione, confrontandola con le aree consentite e bloccate, la posizione IP e l'indirizzo del documento. Consulta [Verifica della posizione](https://docs.didit.me/it/core-technology/location-verification/overview.md) per il comportamento del passaggio e [il relativo report](https://docs.didit.me/it/core-technology/location-verification/report-location-verification.md) per i campi della decisione. Inseriscilo dopo Verifica dell'identità o Prova di residenza se vuoi la distanza dall'indirizzo del documento, perché la distanza viene misurata solo quando è presente un indirizzo registrato. Con `geolocation_position_source` non impostato, la distanza dalla posizione IP richiede un passaggio Analisi dispositivo e IP nello stesso workflow. Tutte le chiavi sono facoltative: un passaggio con `config` vuoto chiede al dispositivo una posizione con precisione di 250 m, non più vecchia di 120 secondi, concede alla persona 3 tentativi e non applica alcuna regola sulle aree. Ogni rilevamento ha una propria chiave di azione; una chiave di azione lasciata non impostata assume il valore predefinito del `geolocation_preset` scelto oppure, se non ne hai scelto alcuno, il valore predefinito per chiave indicato di seguito. Una posizione incerta o negata viene impostata su `REVIEW` per impostazione predefinita, mai su `DECLINE`, perché un'autorizzazione negata o un raggio ampio non sono prova di frode. Un'azione impostata esplicitamente prevale sempre sul preset. Una sfida riprodotta (`LOCATION_REPLAY_DETECTED`) e un'attestazione del dispositivo non riuscita (`LOCATION_INTEGRITY_FAILED`) causano sempre un rifiuto e non hanno una chiave di azione. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `geolocation_position_source` | string | Da dove proviene la posizione. `device_and_ip` richiede la posizione del dispositivo e la confronta con la posizione IP della connessione da cui viene inviata (una ricerca di informazioni sull'IP se quell'IP non è ancora in cache). Non impostato (predefinito) richiede comunque la posizione del dispositivo e, come prima che esistesse questa chiave, la confronta con la posizione IP rilevata dal passaggio Analisi dispositivo e IP della sessione; quindi non c'è distanza senza quel passaggio, e la connessione non viene mai cercata. Fa eccezione un nodo che agisce su un rilevamento di VPN, proxy o Tor (la sua azione o il suo preset): in questo caso cerca la connessione per quel rilevamento e confronta il dispositivo con essa, esattamente come `device_and_ip`. `device_only` non confronta mai con la posizione IP e cerca la connessione solo per quei rilevamenti; `ip_only` non chiede mai la posizione alla persona e valuta invece la posizione IP della connessione, a livello di città con un raggio di 50 km, senza regole su precisione, recenza o concessione di una posizione approssimativa; con `geolocation_areas` una città costiera viene valutata all'interno del suo paese, a meno che un altro paese non rientri in quel raggio. In un nodo che richiede il dispositivo, un tentativo senza posizione del dispositivo viene considerato un rifiuto o un errore, a seconda del caso: la posizione IP non lo sostituisce mai. | | `geolocation_preset` | string | I valori predefiniti che ogni azione non impostata di questo nodo assume. `licensing`: fuori da un'area, in un'area bloccata, una VPN, Tor o un emulatore comportano un rifiuto; un proxy e gli altri rilevamenti vengono sottoposti a revisione, e un'attestazione del dispositivo mancante resta Nessuna azione. `fraud_screening`: come sopra, tranne che ciò che Licensing rifiuta viene inviato a revisione. Null mantiene i valori predefiniti storici. Un'azione impostata esplicitamente prevale sempre. | | `geolocation_accuracy_mode` | string | Cosa viene richiesto al dispositivo. `precise` chiede al sistema operativo una posizione precisa; a una persona che concede solo una posizione approssimativa viene chiesto di nuovo di fornire la posizione finché restano tentativi, poi valutata da `geolocation_approximate_action`; `approximate_allowed` accetta una concessione approssimativa senza quel giudizio. `geolocation_max_accuracy_radius_m` si applica in entrambi i casi. `precise` se non impostato. | | `geolocation_max_accuracy_radius_m` | integer | Il raggio di incertezza più ampio, in metri, che una posizione del dispositivo può avere ed essere ancora considerata valida. Da 10 a 50000 metri; 250 se non impostato. Una posizione più ampia, oppure una che non riporta alcun raggio, fa ciò che indica `geolocation_low_accuracy_behavior` ed è valutata da `geolocation_low_accuracy_action`. Un nodo `ip_only` non ha un raggio del dispositivo e non lo applica mai. | | `geolocation_max_accuracy_radius_unit` | string | L'unità in cui la console mostra `geolocation_max_accuracy_radius_m`. Solo visualizzazione: il valore memorizzato è sempre in metri, nessuna regola dipende da esso, e i dati del passaggio lo inoltrano solo affinché un client possa mostrare la stessa unità. | | `geolocation_low_accuracy_behavior` | string | Cosa fa una posizione più ampia di `geolocation_max_accuracy_radius_m`, oppure senza raggio: `ask_again` (predefinito) chiede alla persona di riprovare finché restano tentativi; `fail` termina il passaggio al primo caso. | | `geolocation_max_age_seconds` | integer | Quanto può essere vecchia, in secondi, una posizione del dispositivo quando il server la riceve. Da 5 a 3600 secondi; 120 se non impostato. Una posizione più vecchia viene richiesta di nuovo finché restano tentativi, poi valutata da `geolocation_stale_fix_action`. | | `geolocation_timeout_seconds` | integer | Per quanto tempo, in secondi, il client lascia che il dispositivo cerchi una posizione a ogni tentativo; il server lo inoltra nei dati del passaggio e non applica nulla da solo. Da 5 a 120 secondi; 20 se non impostato. Un tentativo che non trova una posizione in tempo viene inviato come `timeout`; alla persona viene chiesto di riprovare finché restano tentativi, poi valutato da `geolocation_unavailable_action`. | | `geolocation_max_attempts` | integer | Quanti tentativi ha la persona su questo nodo. Da 1 a 5 tentativi; 3 se non impostato. Un tentativo che la persona può ancora modificare (un rifiuto, una posizione ampia, obsoleta o approssimativa, oppure un rilevamento relativo a un'area o a un anonimizzatore su cui il nodo agisce) viene richiesto di nuovo finché restano tentativi, e l'ultimo decide il passaggio. Una posizione simulata, o un emulatore su cui il nodo agisce, termina il passaggio al tentativo che l'ha segnalata. | | `geolocation_allow_qr_handoff` | boolean | Offre di continuare su un telefono tramite codice QR finché il passaggio è ancora aperto (`allow_qr_handoff` nei dati del passaggio, `can_handoff` in ogni risposta a un invio). Gli SDK nativi girano già sul telefono e non mostrano mai il codice. Attivo per impostazione predefinita. | | `geolocation_allow_skip` | boolean | Consente alla persona di proseguire senza posizione in qualsiasi momento, dalla schermata introduttiva o da una schermata di nuovo tentativo (`skipped: true`). L'opzione di saltare termina il passaggio ed è valutata da `geolocation_unavailable_action`, tranne un salto che risponde a un rifiuto su un `geolocation_refusal_path` `continue_without_location`, che viene registrato come quel rifiuto. Disattivato per impostazione predefinita. | | `geolocation_deep_link_enabled` | boolean | Inoltrato al client come `deep_link_enabled` nei dati del passaggio: propone invece di aprire l'app del cliente. Il server non applica alcuna regola a questo valore. Disattivato per impostazione predefinita. | | `geolocation_refusal_path` | string | Il percorso proposto quando l'accesso alla posizione viene rifiutato. `retry_then_handoff` (il valore predefinito) chiede di nuovo finché restano tentativi e propone un trasferimento telefonico; `continue_without_location` lascia proseguire la persona, registrando il rifiuto; `end_session` termina il passaggio e la sessione al primo rifiuto, e richiede che `geolocation_permission_denied_action` sia Review o Decline e un workflow che possa concludersi con un esito Declined, In Review o Final decision. La sessione viene decisa in base ai passaggi eseguiti e non è mai approvata: su un workflow che non può concludersi con quella decisione, prende l'altro esito non approvativo (rifiutata per In Review, in revisione per Declined). | | `is_geolocation_geofencing_enabled` | boolean | Attiva le regole per area: `geolocation_areas`, oppure la più vecchia `geolocation_geofencing_by_country`, si applicano solo mentre questo valore è true, e solo in tal caso i dati del passaggio elencano `available_areas`. Disattivato per impostazione predefinita. Con questo valore attivo, un elenco `geolocation_areas` richiede almeno un'area consentita. | | `geolocation_areas` | array | Aree consentite e bloccate, applicate mentre `is_geolocation_geofencing_enabled` è true. Passa solo una posizione all'interno di un'area consentita, e un'area bloccata prevale sempre su una consentita. Una posizione conta in base al suo intero cerchio di precisione: un cerchio che attraversa un bordo che decide l'esito è indeterminato, mai esterno. Un paese o una regione termina dove inizia un'altra terra, mai sulla linea di costa, e una posizione che i contorni collocano su nessuna terra (un lungomare o un molo che la linea di costa semplificata ha escluso) è indeterminata per ogni paese o regione entro il proprio raggio più 12 miglia nautiche. `id` è il nome a cui fanno riferimento le regole di ramo e `geolocation.inside_areas` / `geolocation.blocked_areas`; `kind` sceglie la forma: un intero `country` (ISO 3166-1 alpha-3 con contorno pubblicato: un territorio che i contorni rappresentano come regione di un altro paese va indicato come `region`, come La Riunione, indicata come `FR-RE` dalla Francia, oppure Bonaire, Sint Eustatius e Saba come da `NL-BQ1` a `NL-BQ3`), `region` (codici ISO 3166-2 di un paese con confini pubblicati), `circle` (da 1 a 500 km) o `polygon` (da 3 a 200 punti, un anello i cui bordi non si incrociano né si toccano). Al massimo 50 aree, con id unici, e almeno un'area consentita mentre il geofencing è attivo. Non può essere combinato con `geolocation_geofencing_by_country`. | | `geolocation_geofencing_by_country` | object | Regole di autorizzazione e negazione per paese e regione, sulla posizione rilevata dal dispositivo stesso, applicate solo mentre `is_geolocation_geofencing_enabled` è true. Stessa struttura di `ip_geofencing_by_country` dell'Analisi IP, con una differenza: le chiavi di `states` sono codici ISO 3166-2 (`US-NJ`), non nomi di stati, perché la posizione viene risolta in una suddivisione e non in un'etichetta di città del fornitore. Un paese non elencato è consentito. Una regola di regione per un paese senza confini ISO 3166-2 pubblicati viene rifiutata, invece di essere ignorata in silenzio. | | `geolocation_ip_distance_km` | integer | Quanto possono distare, in chilometri, la posizione del dispositivo e la posizione IP, dopo aver sottratto entrambi i raggi di incertezza, prima che si applichi `geolocation_ip_distance_action`. 200 quando la chiave è omessa; null disattiva il confronto. Il confronto viene effettuato solo per un nodo il cui `geolocation_position_source` è `device_and_ip` o non è impostato; quella chiave indica con quale posizione IP viene effettuato il confronto. | | `geolocation_ip_distance_unit` | string | L'unità in cui la console mostra `geolocation_ip_distance_km`. Solo visualizzazione: il valore memorizzato è sempre in chilometri e nessuna regola ne dipende. | | `geolocation_document_distance_km` | integer | Quanto può distare, in chilometri, la posizione (la posizione IP su un nodo `ip_only`) dall'indirizzo indicato da `geolocation_document_distance_basis`, prima che si applichi `geolocation_document_distance_action`. Non impostato o null (il valore predefinito) significa disattivato. | | `geolocation_document_distance_unit` | string | L'unità in cui la console mostra `geolocation_document_distance_km`. Solo visualizzazione: il valore memorizzato è sempre in chilometri e nessuna regola ne dipende. | | `geolocation_document_distance_basis` | string | Da quale indirizzo viene misurato `geolocation_document_distance_km`: `document` (il valore predefinito: l'indirizzo del documento d'identità, poi la prova di residenza), solo `proof_of_address`, oppure `declared` (l'`expected_details.address` fornito alla creazione della sessione, geocodificato). | | `geolocation_travel_tolerance_enabled` | boolean | Consente di ignorare la distanza dall'indirizzo quando la stessa persona (stesso `vendor_data`) è stata rilevata entro `geolocation_travel_usual_area_km` da esso negli ultimi `geolocation_travel_max_days` giorni. Non giustifica mai una VPN, una posizione falsificata, un'area bloccata o il trovarsi fuori dalle aree consentite. Conta come rilevazione in quel luogo solo una posizione misurata dal dispositivo: un fix simulato o mockato, un emulatore o un'attestazione non riuscita non contano mai. | | `geolocation_travel_usual_area_km` | integer | Raggio attorno all'indirizzo che definisce l'area abituale della persona. Da 10 a 500 km; 100 se non impostato. | | `geolocation_travel_max_days` | integer | Per quanto tempo, dopo essere stati rilevati nell'area abituale, una posizione lontana è ancora considerata viaggio. Da 1 a 90 giorni; 14 se non impostato. | | `geolocation_consecutive_mismatch_count` | integer | Genera LOCATION\_CONSECUTIVE\_MISMATCHES quando questo controllo e i controlli precedenti della stessa persona (stesso `vendor_data`) sono risultati fuori dalle aree consentite, in un'area bloccata o troppo lontani dall'indirizzo per questo numero di volte di fila. Un controllo che non ha confrontato nulla non estende né interrompe la serie, e lo stesso vale per una posizione che il dispositivo non ha misurato (un fix simulato o mockato, un emulatore, un'attestazione non riuscita). Da 2 a 10; null (il valore predefinito) significa disattivato. | | `geolocation_approximate_action` | action | Esito quando l'utente ha concesso una posizione approssimativa mentre `geolocation_accuracy_mode` ne richiede una precisa. Il valore predefinito è `REVIEW`. | | `geolocation_blocked_area_action` | action | Esito quando la posizione, e il suo intero cerchio di precisione, cade all'interno di un'area bloccata di `geolocation_areas`. Il valore predefinito è Decline. | | `geolocation_consecutive_mismatch_action` | azione | Esito quando vengono raggiunte `geolocation_consecutive_mismatch_count` mancate corrispondenze consecutive. Il valore predefinito è Revisione. | | `geolocation_document_distance_action` | azione | Esito quando la posizione del dispositivo è più lontana dall'indirizzo del documento di quanto stabilito da `geolocation_document_distance_km`. L'indirizzo viene geocodificato in modo approssimativo, quindi si tratta di un segnale debole. Il valore predefinito è `REVIEW`. | | `geolocation_emulator_action` | azione | Esito quando l'app che ha condiviso la posizione risulta in esecuzione su un emulatore. I browser non possono segnalarlo. A meno che non sia impostata su Nessuna azione, il passaggio termina a quel tentativo: riprovare non può cambiare il dispositivo. Nessuna azione, a meno che non sia impostata o un preset non indichi diversamente. | | `geolocation_geofence_undetermined_action` | azione | Esito quando non è possibile stabilire se la posizione si trova dentro o fuori il perimetro, perché il cerchio di precisione raggiunge il confine. L'incertezza non viene mai riportata come esterna al perimetro. Il valore predefinito è `REVIEW`. | | `geolocation_geofencing_action` | azione | Esito quando la posizione del dispositivo, insieme a tutto il suo cerchio di incertezza, cade al di fuori di `geolocation_geofencing_by_country`. Il valore predefinito è `DECLINE`. | | `geolocation_integrity_missing_action` | azione | Esito quando un client nativo ha inviato una posizione senza token di attestazione del dispositivo. Il valore predefinito è Nessuna azione; i client web vengono registrati come non supportati anziché mancanti, perché nessun browser può attestare il dispositivo. | | `geolocation_ip_distance_action` | azione | Esito quando la posizione del dispositivo e la posizione IP della sessione distano più di `geolocation_ip_distance_km`, dopo aver sottratto entrambi i raggi di incertezza. Il valore predefinito è `REVIEW`. | | `geolocation_low_accuracy_action` | azione | Esito quando nessun tentativo ha raggiunto la precisione richiesta: la posizione migliore ha un raggio di incertezza superiore a `geolocation_max_accuracy_radius_m`, oppure non ha segnalato alcun raggio. Una posizione senza raggio non viene mai considerata conforme al limite. Il valore predefinito è `REVIEW`. | | `geolocation_mock_location_action` | azione | Esito quando il sistema operativo ha segnalato la posizione come simulata anziché misurata (provider mock di Android, simulata dal software su iOS). Il valore predefinito è `REVIEW`. | | `geolocation_permission_denied_action` | azione | Esito quando l'utente ha rifiutato o chiuso la richiesta di accesso alla posizione in ogni tentativo consentito. Il valore predefinito è Revisione: un rifiuto è una scelta, non un segnale di frode. | | `geolocation_proxy_action` | azione | Esito quando la connessione che ha condiviso la posizione passa attraverso un proxy aperto, anonimo o di relay privato. Nessuna azione, a meno che non sia impostata o un preset non indichi diversamente. | | `geolocation_stale_fix_action` | azione | Esito quando la posizione è stata misurata più di `geolocation_max_age_seconds` prima che il server la ricevesse. Il valore predefinito è `REVIEW`. | | `geolocation_tor_action` | azione | Esito quando la connessione che ha condiviso la posizione è un nodo di uscita Tor. Nessuna azione, a meno che non sia impostata o un preset non indichi diversamente. | | `geolocation_unavailable_action` | azione | Esito quando non è stato possibile ottenere alcuna posizione: servizi di localizzazione disattivati o limitati, sistema di posizionamento che non ha restituito nulla, tentativo scaduto, utente che ha saltato il passaggio, oppure client troppo vecchio per supportare questa funzionalità. Il valore predefinito è `REVIEW`. | | `geolocation_vpn_action` | azione | Esito quando la connessione che ha condiviso la posizione è una VPN commerciale. A meno che non sia impostata su Nessuna azione, alla persona viene chiesto di disattivarla e di riprovare finché restano tentativi. Nessuna azione, a meno che non sia impostata o un preset non indichi diversamente. | | `status_rules` | array | Regole di stato personalizzate facoltative. Puoi applicarle ai campi `geolocation.*` elencati nel [Report di verifica della posizione](https://docs.didit.me/it/core-technology/location-verification/report-location-verification.md#campi-per-le-regole-di-stato-e-i-rami). | ### Forme delle aree Ogni elemento di `geolocation_areas` ha un `id` (da 1 a 64 caratteri di `A-Z a-z 0-9 _ -`, univoco nell'elenco), un `label` facoltativo (fino a 80 caratteri), un `type` pari a `allowed` o `blocked`, e un `kind` che determina la forma. | `kind` | Campi aggiuntivi | Significato | | - | - | - | | `country` | `country` (ISO 3166-1 alpha-3) | Un intero paese con confini pubblicati. | | `region` | `country`, `regions` (codici ISO 3166-2 di quel paese) | Una o più suddivisioni di un solo paese con confini pubblicati. | | `circle` | `center` (`latitude`, `longitude`), `radius_km` (da 1 a 500) | Ogni punto entro il raggio dal centro. | | `polygon` | `points` (da 3 a 200 elementi di `latitude`, `longitude`) | Un anello chiuso i cui lati non si incrociano né si toccano mai. | Un elenco contiene al massimo 50 aree e richiede almeno un'area `allowed` quando `is_geolocation_geofencing_enabled` è `true`. `geolocation_areas` e `geolocation_geofencing_by_country` non possono essere inviati insieme, e `geolocation_refusal_path: "end_session"` richiede che `geolocation_permission_denied_action` sia `REVIEW` o `DECLINE`. L'API rifiuta un'area che non potrebbe mai corrispondere, ad esempio una regione di un paese senza confini pubblicati, invece di salvarla. Esempio: ```json theme={null} { "feature": "GEOLOCATION", "config": { "geolocation_position_source": "device_and_ip", "geolocation_preset": "licensing", "geolocation_max_accuracy_radius_m": 250, "geolocation_max_attempts": 3, "is_geolocation_geofencing_enabled": true, "geolocation_areas": [ { "id": "spain", "label": "Spain", "type": "allowed", "kind": "country", "country": "ESP" }, { "id": "ceuta-melilla", "type": "blocked", "kind": "region", "country": "ESP", "regions": ["ES-CE", "ES-ML"] } ], "geolocation_ip_distance_km": 200, "geolocation_ip_distance_action": "REVIEW", "geolocation_vpn_action": "DECLINE" } } ``` ## Prova di residenza Valore della funzionalità: `PROOF_OF_ADDRESS`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `poa_documents_allowed` | object | Configurazione dei tipi di documento POA per codice paese ISO3. Dovrebbe essere abilitato almeno un tipo di documento valido. | | `poa_languages_allowed` | object | Codice lingua ISO 639-1 associato a `0` o `1`. Dovrebbe essere abilitata almeno una lingua. | | `poa_name_or_address_mismatch_action` | action | Azione da eseguire quando il nome o l'indirizzo non corrispondono ai dati attesi. | | `poa_document_issues_action` | action | Azione da eseguire quando il documento presenta problemi di qualità o di estrazione dei dati. | | `poa_max_attempts_exceeded_action` | restricted action | Azione da eseguire quando l'utente supera il numero di tentativi consentiti. Usa `DECLINE` o `REVIEW`. | | `poa_document_authenticity_action` | restricted action | Azione da eseguire quando i controlli di autenticità non vengono superati. Usa `DECLINE` o `REVIEW`. | | `poa_document_unproven_text_replacement_action` | action | Azione da eseguire quando un campo di testo è stato cancellato e riscritto con un altro tipo di carattere, e il file non contiene alcuna prova che il contenuto sia cambiato (`POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`). | | `poa_unsupported_document_type_action` | action | Azione da eseguire quando il tipo di documento non è supportato. | | `poa_unsupported_language_action` | action | Azione da eseguire quando la lingua del documento non è supportata. | | `poa_issuer_not_identified_action` | action | Azione da eseguire quando l'ente emittente del documento non viene identificato. | | `poa_issue_date_not_detected_action` | action | Azione da eseguire quando manca la data di emissione. | | `poa_unparsable_or_invalid_address_action` | action | Azione da eseguire quando l'indirizzo non è valido o non può essere analizzato. | | `address_validation_enabled` | boolean | Valida l'indirizzo letto da questo passaggio (stampato sulla prova di residenza; vengono validati solo i caricamenti che hanno superato i controlli sul documento) confrontandolo con i dati di riferimento postali: conferma che l'indirizzo esiste, lo normalizza e non lo collega mai a una persona. Il risultato è l'oggetto `address_validation` del passaggio nella decisione. **Addebitato \$0.10 per indirizzo validato**; una validazione che non può essere eseguita (`unavailable`) è gratuita. Disattivata per impostazione predefinita. | | `address_not_verified_action` | action | Azione da eseguire quando Address Validation non riesce a confermare l'indirizzo fino all'edificio (`ADDRESS_NOT_VERIFIED`: `partially_verified` o `not_verified`). Si applica solo quando `address_validation_enabled` è attivo. Il valore predefinito è `NO_ACTION`, che si limita a registrare l'avviso. | | `poa_name_match_score_threshold` | integer | Soglia di corrispondenza del nome. | | `poa_max_retry_attempts` | integer | Limite di nuovi tentativi, da `2` a `5`. | | `status_rules` | array | Regole di stato personalizzate opzionali. | ## Questionario Valore della funzionalità: `QUESTIONNAIRE`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `questionnaire_uuid` | UUID | Obbligatorio. Usa il `questionnaire_id` restituito da `POST /v3/questionnaires/`. | | `review_questionnaire_manually` | boolean | Invia le risposte al questionario alla revisione manuale. | | `status_rules` | array | Regole di stato personalizzate opzionali. Puoi specificare come destinazione i campi `questionnaire.answers.`. | ## Registro KYB Valore della funzionalità: `KYB_REGISTRY`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `kyb_accepted_countries` | object | Lista di paesi consentiti ISO3 per la ricerca nel registro delle imprese. Obsoleta: sostituita da `kyb_registry_countries_config`; resta leggibile e per i workflow esistenti continua a essere derivata da quest'ultima, ma non è più il modo per configurare nuovi workflow. | | `kyb_manual_company_action` | action | Azione da eseguire quando l'azienda richiede una gestione manuale. | | `kyb_registry_fields_config` | object | Visibilità e obbligatorietà di ciascun campo per il modulo del registro nel flusso ospitato. Vedi sotto. | | `kyb_registry_countries_config` | object | Instradamento del registro per paese, nella forma `{"": {"enabled": bool, "tier": "basic" \| "shareholders" \| "ubo"}}`. Ogni paese abilitato sceglie il livello di dati addebitato quando viene selezionata un'azienda (`basic` è il livello Lite), e possono essere abilitati solo i livelli che l'[endpoint dei prezzi](https://docs.didit.me/it/getting-started/kyb-registry-pricing.md) indica come disponibili per quel paese. Deve essere abilitato almeno un paese: un controllo sul registro che non effettua alcuna ricerca viene rifiutato. Le aziende inserite manualmente vengono fatturate separatamente e non usano questa configurazione. | | `kyb_registry_monitoring_enabled` | boolean | Mantiene il record dell'azienda nel registro sotto monitoraggio continuo dopo un risultato Shareholders o UBO: una variazione di stato, dei dirigenti, dell'assetto proprietario o dell'indirizzo riporta la sessione in revisione e attiva un webhook. Disponibile solo dove il fornitore del registro offre il monitoraggio. USD 2.00 per azienda all'anno, annullabile in qualsiasi momento. Disattivata per impostazione predefinita. | | `kyb_vat_invalid_action` | action | Azione da eseguire quando il numero di partita IVA dell'azienda non supera la validazione VIES dell'UE. Il valore predefinito è `REVIEW`. | | `kyb_vat_unverified_action` | action | Azione da eseguire quando il numero di partita IVA non può essere validato perché VIES non è disponibile. Il valore predefinito è `NO_ACTION`. | | `status_rules` | array | Regole di stato personalizzate opzionali. | `kyb_registry_fields_config` associa ogni chiave di campo configurabile a `{"enabled": bool, "required": bool}`. `enabled: false` nasconde il campo, `enabled: true, required: false` lo mostra come facoltativo, e `enabled: true, required: true` lo rende obbligatorio all'invio. `company_name`, `country_code` e `region` sono sempre mostrati e obbligatori e non possono essere configurati. Quando l'oggetto viene omesso, è `null` oppure è `{}`, si applica il valore predefinito: solo `incorporation_date` è obbligatorio e tutti gli altri campi sono facoltativi. ```json theme={null} { "kyb_registry_fields_config": { "registration_number": { "enabled": true, "required": true }, "incorporation_date": { "enabled": true, "required": true }, "vat_number": { "enabled": true, "required": false }, "control_scheme": { "enabled": false, "required": false } } } ``` Chiavi di campo configurabili: `registration_number`, `incorporation_date`, `legal_address`, `vat_number`, `alternative_names`, `tax_number`, `company_type`, `legal_entity_identifier`, `location_of_registration`, `nature_of_business`, `registered_capital_amount`, `registered_capital_currency`, `website`, `email`, `phone`, `control_scheme`. Vedi [campi configurabili del modulo di registro](https://docs.didit.me/it/business-verification/company-data.md#campi-del-modulo-di-registro-configurabili) per il comportamento lato utente finale e [validazione della partita IVA e dell'identificativo fiscale](https://docs.didit.me/it/business-verification/company-data.md#validazione-del-numero-vat-e-dell’identificativo-fiscale) per come vengono controllati `vat_number` e `tax_number`. ## Documenti KYB Valore della funzionalità: `KYB_DOCUMENTS`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `kyb_required_document_groups` | oggetto o array | Obbligatorio. Gruppi di documenti KYB richiesti. | | `kyb_document_subtype_config` | oggetto | Abilitazione per sottotipo di documento e configurazione dell'età. | | `kyb_document_tampering_action` | azione limitata | Azione quando viene rilevata una manomissione. Usa `DECLINE` o `REVIEW`. | | `kyb_document_unproven_text_replacement_action` | azione | Azione quando un campo di testo di un documento aziendale è stato svuotato e riscritto in un altro font e il file non contiene alcuna prova che il suo contenuto sia cambiato (`KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`). | | `kyb_document_critical_mismatch_action` | azione limitata | Azione per le non corrispondenze critiche nei documenti. Usa `DECLINE` o `REVIEW`. | | `kyb_document_non_critical_mismatch_action` | azione | Azione per le non corrispondenze non critiche nei documenti. | | `kyb_document_age_action` | azione | Azione quando le regole sull'età del documento non sono rispettate. | | `kyb_document_max_retry_attempts` | intero | Limite di nuovi tentativi per i documenti KYB. | | `kyb_document_max_attempts_exceeded_action` | azione limitata | Azione quando viene superato il numero massimo di tentativi. Usa `DECLINE` o `REVIEW`. | | `status_rules` | array | Regole di stato personalizzate facoltative. | ## Persone chiave KYB Valore della funzionalità: `KYB_KEY_PEOPLE`. | Campo di configurazione | Tipo | Descrizione | | - | - | - | | `kyb_ubo_ownership_threshold` | intero | Soglia di proprietà per il titolare effettivo (UBO), da `0` a `100`. | | `kyb_shareholder_ownership_threshold` | intero | Soglia di proprietà per gli azionisti, da `0` a `100`. Non può essere superiore a `kyb_ubo_ownership_threshold`. | | `kyb_key_people_ownership_required` | booleano | Richiede una percentuale di proprietà per ogni persona chiave inserita. Viene applicato in fase di invio e riportato nell'interfaccia ospitata, che contrassegna il campo come obbligatorio. Predefinito `false`. | | `kyb_require_ubo_kyc` | booleano | Richiede che i titolari effettivi (UBO) completino un workflow di verifica della persona. | | `kyb_ubo_verification_workflow` | UUID | Obbligatorio quando `kyb_require_ubo_kyc` è `true`. Deve fare riferimento a un workflow non KYB nella stessa applicazione. | | `kyb_require_officer_kyc` | booleano | Richiede che i dirigenti completino la verifica della persona. | | `kyb_shareholder_verification_workflow` | UUID | Workflow di verifica della persona per gli azionisti. | | `kyb_officer_verification_workflow` | UUID | Workflow di verifica della persona per i dirigenti. | | `kyb_require_corporate_ubo_kyb` | booleano | Richiede che i titolari effettivi di tipo societario completino la verifica KYB. | | `kyb_corporate_ubo_verification_workflow` | UUID | Obbligatorio quando `kyb_require_corporate_ubo_kyb` è `true`. Deve fare riferimento a un workflow KYB nella stessa applicazione. | | `kyb_reject_if_ubo_rejected` | booleano | Rifiuta l'azienda quando la verifica di un titolare effettivo (UBO) obbligatorio viene rifiutata. | | `kyb_wait_for_all_ubos` | booleano | Attende tutte le verifiche obbligatorie dei titolari effettivi (UBO) prima di decidere la sessione KYB. | | `kyb_role_config` | oggetto o array | Configurazione per ruolo. Ogni ruolo KYC obbligatorio deve includere un `verification_workflow`. | | `kyb_reuse_verified_individuals` | booleano | Riutilizza le persone fisiche già verificate, quando possibile. | | `kyb_notify_parties_by_email` | booleano | Invia notifiche email alle persone chiave invitate. | | `kyb_key_people_company_fields` | oggetto | Dati aziendali raccolti per una persona chiave di tipo CORPORATE. Stessa forma a elenco di descrittori e stesse regole di `kyb_key_people_person_fields`. Forma: `[{"key": "", "label": "