Configurazione funzionalità workflow: riferimento API

Usa questi campi config all’interno di ogni elemento dell’array features per POST /v3/workflows/ e PATCH /v3/workflows/{settings_uuid}/.

{
  "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.

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

{
  "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.

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 @<node_id> 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.

{
  "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à 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 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 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.
`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.
`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.
`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.
`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.
`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.
`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.

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:

{
  "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. Ogni paese prevede fino a tre oggetti metodo; ciò che si omette assume il valore predefinito.

{
  "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.

{
  "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:

{
  "DNK": {
    "document": { "enabled": true },
    "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" }
  }
}

Key	Type	Default	Descrizione
`<ISO3>.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`.
`<ISO3>.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.
`<ISO3>.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`.
`<ISO3>.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.
`<ISO3>.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.
`<ISO3>.id_lookup.on_partial_match`	`fallback_to_document` \| `decline`	`fallback_to_document`	Cosa succede quando il registro ha risposto ma alcuni campi non corrispondono.
`<ISO3>.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.
`<ISO3>.id_lookup.on_provider_error`	`fallback_to_document` \| `decline`	`fallback_to_document`	Cosa succede quando non è possibile raggiungere il registro. Mai fatturato.
`<ISO3>.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.
`<ISO3>.wallet.enabled`	boolean	`false`	Propone l’accesso con wallet di identità digitale in questo paese.
`<ISO3>.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.
`<ISO3>.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.

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. Comportamento, copertura e fatturazione sono descritti in Metodi di verifica dell’identità.

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, 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.
`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 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 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.

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.

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.<field>` oppure `metadata.<key>` 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: `{"<db_validation_input_field>": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}`.
`status_rules`	array	Regole di stato personalizzate facoltative.

Esempio:

{
  "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"
  }
}

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/. 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:

{
  "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.

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

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 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. 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: `{"<ISO3>": {"enabled": true\|false, "institutions": ["<institution_id>", ...]\|"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.

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

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.<field>` o `metadata.<key>` 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": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}`.
`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.<ISO3>.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.<ISO3>.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:

{
  "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"
}

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.<field>` oppure `metadata.<key>` 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": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}`
`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:

{
  "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"
  }
}

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:

{
  "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 per il comportamento del passaggio e il relativo report 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.

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:

{
  "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.<question_id>`.

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 `{"<ISO2>": {"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 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.

{
  "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 per il comportamento lato utente finale e validazione della partita IVA 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": "<field key>", "label": "<label>", "type": "text"\|"number"\|"date"\|"phone"\|"email", "required": true\|false, "custom": true\|false}]`.
`kyb_key_people_document_mismatch_action`	azione	Esito quando il documento di una persona chiave non corrisponde ai dati dichiarati per lei.
`kyb_key_people_person_fields`	oggetto	Dati personali raccolti per una persona chiave individuale (o persona fisica), come ELENCO ORDINATO di descrittori di campo (non una mappa). `key` è obbligatoria e non vuota; `type` deve essere uno tra text, number, date, phone o email; `custom` contrassegna un campo aggiunto dal cliente anziché uno dei campi predefiniti. Forma: `[{"key": "<field key>", "label": "<label>", "type": "text"\|"number"\|"date"\|"phone"\|"email", "required": true\|false, "custom": true\|false}]`.
`kyb_key_people_prefill_from_registry`	booleano	Precompila l’elenco delle persone chiave con il risultato del registro delle imprese, così il cliente conferma e corregge invece di inserire manualmente ogni dirigente e azionista.
`status_rules`	array	Regole di stato personalizzate facoltative.

Document AI

Valore della funzionalità: DOCUMENT_AI. Richiede all’utente uno o più documenti ed estrae con un modello di visione i campi che definisci. Ogni campo configurato diventa un valore utilizzabile per le diramazioni, document_ai.<key>, e l’esito del passaggio è document_ai.status.

Campo di configurazione	Tipo	Descrizione
`document_ai_documents`	array	Obbligatorio. I documenti da richiedere (al massimo `3`). Ogni voce è un oggetto documento (vedi sotto).
`document_ai_unreadable_document_action`	azione	Azione da eseguire quando il documento non può essere letto o non è possibile estrarre alcun dato.
`document_ai_missing_required_fields_action`	azione	Azione da eseguire quando non è possibile estrarre un campo obbligatorio.
`document_ai_document_tampering_action`	azione limitata	Azione da eseguire quando il documento mostra segni di manipolazione. Usa `DECLINE` o `REVIEW`.
`document_ai_name_mismatch_action`	azione	Azione da eseguire quando il nome completo estratto non corrisponde all’identità verificata. Richiede un campo contrassegnato con `is_full_name`.
`document_ai_unsupported_file_action`	azione	Azione da eseguire quando il tipo di file caricato non è supportato.
`document_ai_max_attempts_exceeded_action`	azione limitata	Azione da eseguire quando l’utente supera il limite di tentativi. Usa `DECLINE` o `REVIEW`.
`document_ai_name_match_score_threshold`	integer	Punteggio minimo (`0`–`100`) affinché il nome completo estratto corrisponda all’identità verificata. Al di sotto di questa soglia si applica `document_ai_name_mismatch_action`.
`document_ai_max_retry_attempts`	integer	Limite di nuovi tentativi, da `2` a `5`.
`status_rules`	array	Regole di stato personalizzate, facoltative. Puoi indirizzare i campi `document_ai.<key>`.

Ogni voce di document_ai_documents è un documento:

Campo del documento	Tipo	Descrizione
`document_key`	string	Obbligatorio. Identificatore stabile del documento, univoco all’interno del passaggio.
`title`	string	Obbligatorio. Titolo mostrato all’utente.
`description`	string	Obbligatorio. Istruzioni mostrate all’utente su cosa caricare.
`title_i18n`	object	Facoltativo. Codice locale per il titolo tradotto (ad esempio `{ "es": "Comprobante de fondos" }`).
`description_i18n`	object	Facoltativo. Codice locale per la descrizione tradotta.
`fields`	array	Obbligatorio. I campi da estrarre (almeno uno). Le chiavi dei campi devono essere univoche all’interno del documento.

Ogni voce di fields di un documento è un campo:

Campo	Tipo	Descrizione
`key`	string	Obbligatorio. Chiave JSON stabile per il valore estratto, univoca all’interno del documento. Usala per le diramazioni come `document_ai.<key>`.
`name`	string	Obbligatorio. Etichetta del campo comprensibile.
`name_i18n`	object	Facoltativo. Codice locale per il nome del campo tradotto.
`instruction`	string	Facoltativo. Istruzione che indica al modello esattamente cosa estrarre per questo campo.
`type`	string	Tipo del campo: `text`, `number` o `date`. Il valore predefinito è `text`.
`required`	boolean	Indica se il campo deve essere presente. Il valore predefinito è `false`. Se è `true` e il valore manca, si applica `document_ai_missing_required_fields_action`.
`is_full_name`	boolean	Facoltativo, il valore predefinito è `false`. Contrassegna il campo il cui valore è il nome completo del titolare del documento, confrontato con l’identità verificata (il nome verificato tramite la verifica dell’identità o i dati attesi della sessione). Al massimo un campo per documento può impostarlo a `true`. Non è obbligatorio: un documento può non contrassegnare alcun campo, e in tal caso non viene eseguito alcun confronto del nome per quel documento. Solo i campi `text` possono essere il nome completo.

Esempio:

{
  "feature": "DOCUMENT_AI",
  "config": {
    "document_ai_documents": [
      {
        "document_key": "proof_of_funds",
        "title": "Proof of Funds",
        "description": "Upload a recent bank statement.",
        "title_i18n": { "es": "Comprobante de fondos" },
        "fields": [
          {
            "key": "account_holder",
            "name": "Account holder",
            "instruction": "The full name of the account holder as printed on the statement.",
            "type": "text",
            "required": true,
            "is_full_name": true
          },
          {
            "key": "closing_balance",
            "name": "Closing balance",
            "instruction": "The closing balance amount.",
            "type": "number",
            "required": false
          }
        ]
      }
    ],
    "document_ai_missing_required_fields_action": "REVIEW",
    "document_ai_name_mismatch_action": "REVIEW",
    "document_ai_name_match_score_threshold": 80
  }
}

E-signature

Valore della funzionalità: SIGNATURE. Consente alla persona verificata o alle persone chiave di un’azienda di firmare i documenti, al livello Simple (predefinito) o Advanced (AES). Inseriscila dopo i passaggi che verificano il firmatario: Verifica dell’identità e, per il codice, Verifica email o Verifica telefonica. Vedi Firma elettronica.

Campo di configurazione	Tipo	Descrizione
`signature_documents`	array	I documenti caricati in questo workflow nella console, nell’ordine in cui il firmatario li vede, nel formato `[{"uuid", "title", "file_name", "pages", "size_bytes"}]`. Vengono letti solo i valori `uuid` e il loro ordine; il resto proviene dai file salvati. Fino a 20 documenti e 50 MB in totale. Predefinito `[]`.
`signature_documents_source`	string	Da dove provengono i documenti: `workflow` (predefinito), `session` (`sign.documents` in crea sessione) oppure `both` (prima i documenti del workflow).
`signature_require_read_to_end`	boolean	Il firmatario deve arrivare alla fine di ogni documento senza campi prima di accettarlo. Predefinito `true`.
`signature_consent_per_document`	boolean	Il firmatario accetta separatamente ogni documento senza campi. Per i documenti con campi, i campi guidati e il consenso finale sostituiscono l’accettazione separata. Predefinito `true`.
`signature_signer`	string	Chi firma: `verified_person` (predefinito, KYC) oppure, per KYB, `legal_representative` (persone chiave con ruolo `representative` o `authorized_signatory`) o `key_people` (ogni singola persona chiave con una sessione KYC).
`signature_level`	string	`simple` (predefinito): nessuna verifica dell’identità, email, telefono o codice; il firmatario digita il proprio nome e firma tramite il link di sessione. `aes`: richiede una verifica dell’identità approvata, un’email o un telefono verificati e un codice monouso. `simple` viene rifiutato per i firmatari `legal_representative` e `key_people` con `signature_simple_requires_verified_person`. Finché `signature_availability.aes` è `false` nel workflow, il salvataggio di un nuovo passaggio `aes` restituisce `400` con `aes_not_available`. `qes` è in arrivo: il suo salvataggio restituisce `400` con `qes_not_available`.
`signature_format`	string	`pades` (predefinito). `xades` e `cades` vengono rifiutati per AES con `signature_format_not_supported`.
`signature_otp_channel`	string	Dove arriva il codice monouso: `email` (predefinito) o `sms`. Viene inviato solo a un contatto verificato in precedenza nella sessione.
`signature_email_signed_copy`	boolean	Invia al firmatario via email una copia dei documenti firmati. Richiede un’email verificata. Predefinito `true`.
`signature_evidence_page`	boolean	Aggiunge la pagina delle prove a ogni PDF firmato. Predefinito `true`.
`signature_link_validity_days`	integer	Per quanti giorni il link di firma resta valido, da `1` a `30` giorni dalla creazione della sessione. Predefinito `7`.
`signature_declined_action`	action	Esito quando il firmatario rifiuta. Nessun addebito. Predefinito `REVIEW`.
`signature_otp_failed_action`	action	Esito dopo 3 codici errati o più di 5 codici richiesti. Predefinito `DECLINE`.
`signature_name_mismatch_action`	action	Esito quando il nome dichiarato di una persona chiave non corrisponde al nome verificato. Predefinito `DECLINE`.
`signature_identity_not_verified_action`	action	Esito quando il firmatario non ha una prova di identità approvata. Predefinito `DECLINE`.
`signature_document_changed_action`	action	Esito quando un documento non corrisponde più allo SHA-256 registrato al momento della visualizzazione. Predefinito `DECLINE`.
`status_rules`	array	Regole di stato personalizzate facoltative. Puoi applicarle a `signature.status`, `signature.level` e `signature.format`.

I campi su un documento del workflow si inseriscono nell’editor dei modelli della console. Per i documenti di sessione, inviali in sign.documents[].fields e invia i valori dei campi api.<key> in sign.field_values. Vedi Crea sessione. Esempio, per documenti inviati con ogni sessione:

{
  "feature": "SIGNATURE",
  "config": {
    "signature_documents_source": "session",
    "signature_signer": "verified_person",
    "signature_level": "aes",
    "signature_otp_channel": "email",
    "signature_link_validity_days": 14,
    "signature_declined_action": "REVIEW"
  }
}

​Regole di validazione

​Regole comuni sullo stato

​Confronto con un passaggio specifico

​OCR / Verifica dell’identità

​Metodi per paese

​NFC / ePassport

​Rilevamento della vitalità

​Confronto facciale

​Stima dell’età

​Verifica telefonica

​Verifica email

​Validazione su database

​Verifica del conto bancario

​Collegamento di un conto

​Quando l’utente non può verificare

​Confronto del titolare

​Verifica del conto

​Dati finanziari

​Cosa viene memorizzato

​Azioni di esito

​Altri controlli

​AML

​Screening di un’entità estratta da un passaggio Document AI

​Analisi dispositivo e IP

​Verifica della posizione

​Forme delle aree

​Prova di residenza

​Questionario

​Registro KYB

​Documenti KYB

​Persone chiave KYB

​Document AI

​E-signature

Regole di validazione

Regole comuni sullo stato

Confronto con un passaggio specifico

OCR / Verifica dell’identità

Metodi per paese

NFC / ePassport

Rilevamento della vitalità

Confronto facciale

Stima dell’età

Verifica telefonica

Verifica email

Validazione su database

Verifica del conto bancario

Collegamento di un conto

Quando l’utente non può verificare

Confronto del titolare

Verifica del conto

Dati finanziari

Cosa viene memorizzato

Azioni di esito

Altri controlli

AML

Screening di un’entità estratta da un passaggio Document AI

Analisi dispositivo e IP

Verifica della posizione

Forme delle aree

Prova di residenza

Questionario

Registro KYB

Documenti KYB

Persone chiave KYB

Document AI

E-signature