{ "openapi": "3.0.0", "info": { "version": "3.0.0", "title": "Didit Verification API", "description": "API di verifica dell'identità. Autenticati con l'intestazione x-api-key." }, "servers": [ { "url": "https://verification.didit.me" } ], "tags": [], "paths": { "/system/healthcheck": { "get": { "summary": "Controllo dello stato del servizio (pubblico, non autenticato)", "description": "Probe di vitalità pubblica non autenticata. Restituisce `HTTP 200` con `{status: \"ok\", timestamp}` quando il servizio, il DB, la cache e il broker sono operativi.", "operationId": "get_system_healthcheck", "x-didit-sdk": { "resource": "system", "method": "healthcheck", "auth": "public", "server": false }, "tags": [ "System" ], "security": [ {} ], "parameters": [], "responses": { "200": { "description": "Il servizio è integro e accetta richieste. Il corpo è sempre `{\"status\": \"ok\", \"timestamp\": \"\"}`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "Marcatore di rilevamento della vitalità. Sempre la stringa letterale `\"ok\"` in una risposta 200.", "example": "ok" }, "timestamp": { "type": "string", "format": "date-time", "description": "Ora del server in cui è stato valutato il controllo dello stato, in formato ISO 8601 con precisione al millisecondo e suffisso `Z` (UTC).", "example": "2026-04-21T16:42:50.445Z" } } }, "examples": { "Healthy": { "summary": "Il servizio è attivo", "value": { "status": "ok", "timestamp": "2026-04-21T16:42:50.445Z" } } } } } }, "503": { "description": "Il servizio non è integro: uno dei plugin di controllo dello stato configurati (database, cache, broker) è in errore. Il corpo della risposta è intenzionalmente minimale; lo stato HTTP è il segnale fondamentale. Riprova con backoff esponenziale." }, "5XX": { "description": "Il servizio di verifica è degradato o non raggiungibile. Considera qualsiasi risposta non-2xx come \"non integro\" e riprova con backoff esponenziale." } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -i https://verification.didit.me/system/healthcheck" }, { "lang": "Python", "label": "Python (requests)", "source": "import requests\n\nresp = requests.get(\"https://verification.didit.me/system/healthcheck\", timeout=5)\nresp.raise_for_status()\nprint(resp.json()) # {'status': 'ok', 'timestamp': '2026-04-21T16:42:50.445Z'}" }, { "lang": "JavaScript", "label": "Node.js (fetch)", "source": "const res = await fetch(\"https://verification.didit.me/system/healthcheck\");\nif (!res.ok) throw new Error(`Didit unhealthy: ${res.status}`);\nconst body = await res.json();\nconsole.log(body); // { status: 'ok', timestamp: '2026-04-21T16:42:50.445Z' }" } ] } }, "/v3/email/risk/": { "post": { "summary": "Calcola il punteggio di rischio di un indirizzo email", "description": "Restituisce segnali di recapitabilità, relativi agli indirizzi usa e getta, alle violazioni di dati, alle corrispondenze tra sessioni e informazioni normalizzate sul rischio senza inviare un OTP. L'endpoint crea una sessione API e restituisce il suo id come `request_id`.\n\n**Decisione.** Il campo di primo livello `status` riflette `email.status`. Di norma è `Approved`; la valutazione del rischio può produrre `In Review` o `Declined`.\n\n**Alias di compatibilità.** Le risposte in produzione espongono l'oggetto informativo normalizzato sia come `email.email_intelligence` sia come `email.enrichment`. I valori sono identici. Le nuove integrazioni possono leggere `email.enrichment`. Entrambe le chiavi sono assenti se non è stato restituito alcun dato utilizzabile.\n\n**Fatturazione.** Le chiamate in produzione utilizzano i prezzi dell'API Email Risk. La richiesta è fatturabile a partire dall'avvio della ricerca, anche qualora alcuni campi elaborati con approccio best effort non siano disponibili.\n\n**Sandbox.** Le chiavi sandbox convalidano la richiesta e restituiscono dati approvati deterministici senza inviare un'email, consumare crediti, creare una sessione o contribuire a Networks.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403`: questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste al minuto per chiave API su tutti gli endpoint POST/PATCH/DELETE (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600).\n\n**Impronta social.** Imposta `enable_social` su `true` per aggiungere un blocco `email_social`: le piattaforme online su cui questo indirizzo è registrato, con conteggi per categoria e gli eventuali dettagli del profilo disponibili. `profiles_registered: 0` indica che le piattaforme sono state verificate e l'indirizzo non è stato trovato su nessuna di esse: una risposta valida e fatturabile. Il blocco è assente quando il componente aggiuntivo non è stato richiesto o non è stato possibile completare la verifica, e in tal caso non viene fatturato. La fatturazione aggiunge un'unità `email_social` per richiesta oltre al prezzo proprio di questo endpoint.", "operationId": "post_v3email_risk", "x-didit-sdk": { "resource": "email", "method": "assess_risk", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/email/risk/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"alice@example.com\",\n \"country_code\": \"US\",\n \"vendor_data\": \"lead-123\",\n \"metadata\": {\"source\": \"signup_prescreen\"}\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.email.assess_risk(\n email=\"alice@example.com\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.email.assessRisk({\n email: \"alice@example.com\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{\n\tEmail: \"alice@example.com\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EmailRiskRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.email().assessRisk(EmailRiskRequest.builder()\n .email(\"alice@example.com\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "email->assessRisk([\n 'email' => 'alice@example.com',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.email.assess_risk(email: \"alice@example.com\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Email.AssessRiskAsync(new EmailRiskRequest\n{\n Email = \"alice@example.com\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRiskRequest" }, "examples": { "Minimal": { "summary": "Calcola il punteggio di un indirizzo con i valori predefiniti", "value": { "email": "alice@example.com" } }, "Full context": { "summary": "Calcola il punteggio con segnali, indicazione del paese e ID di correlazione", "value": { "email": "alice@example.com", "country_code": "US", "signals": { "ip": "192.0.2.1", "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2", "device_platform": "web", "os_version": "14.4", "app_version": "1.2.34", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15" }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" } } } } } } }, "responses": { "200": { "description": "La valutazione del rischio è completata. Ispeziona `status` per la decisione; il codice HTTP è sempre `200` per le ricerche completate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRiskResponse" }, "examples": { "Clean address": { "summary": "Indirizzo recapitabile senza esposizione a violazioni", "value": { "request_id": "82397be9-5921-4970-a979-2d5b43e08b33", "status": "Approved", "email": { "status": "Approved", "email": "alice@example.com", "is_breached": false, "breaches": [], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "email_intelligence": { "score": 4.0, "deliverable": "high", "breach_risk_level": "Low", "breach_risk_index": 4, "is_recent_breach": false, "is_frequent_breached": false, "is_disposable": false, "is_free_domain": false, "is_breached": false, "no_of_breaches": 0, "reason_codes": [] }, "enrichment": { "score": 4.0, "deliverable": "high", "breach_risk_level": "Low", "breach_risk_index": 4, "is_recent_breach": false, "is_frequent_breached": false, "is_disposable": false, "is_free_domain": false, "is_breached": false, "no_of_breaches": 0, "reason_codes": [] } }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" }, "created_at": "2026-09-01T10:30:00.123456+00:00" } }, "Breached address": { "summary": "Indirizzo trovato in violazioni note", "value": { "request_id": "d1e5c2a8-6f30-4c1a-8b2d-3e4f5a6b7c8d", "status": "In Review", "email": { "status": "In Review", "email": "bob@example.org", "is_breached": true, "breaches": [ { "name": "ExampleBreach2023", "domain": "example.org", "breach_date": "2023-06-01", "breach_emails_count": 1200000, "description": "A data breach affecting example.org accounts.", "logo_path": "https://logos.example.org/example.png", "data_classes": [ "email_addresses", "passwords" ], "is_verified": true } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "email_intelligence": { "score": 58.0, "deliverable": "high", "breach_risk_level": "High", "breach_risk_index": 72, "is_recent_breach": true, "is_frequent_breached": true, "is_disposable": false, "is_free_domain": true, "is_breached": true, "no_of_breaches": 4, "reason_codes": [ { "code": "IR-F784B630", "direction": "risk", "message": "Email's digital footprint diversity is Very Low", "impact_level": "low" } ] }, "enrichment": { "score": 58.0, "deliverable": "high", "breach_risk_level": "High", "breach_risk_index": 72, "is_recent_breach": true, "is_frequent_breached": true, "is_disposable": false, "is_free_domain": true, "is_breached": true, "no_of_breaches": 4, "reason_codes": [ { "code": "IR-F784B630", "direction": "risk", "message": "Email's digital footprint diversity is Very Low", "impact_level": "low" } ] } }, "vendor_data": "lead-125", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } } } } } }, "400": { "$ref": "#/components/responses/EmailRiskValidationError" }, "403": { "$ref": "#/components/responses/RiskPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/ip/risk/": { "post": { "summary": "Calcola il punteggio di rischio di un indirizzo", "description": "Restituisce geolocalizzazione, assetto proprietario della rete, flag VPN/Tor e data center, dati sulle minacce e `country_mismatch` per l'indirizzo IP fornito. L'endpoint crea una sessione API e restituisce il suo id come `request_id`.\n\n**Decisione.** Il valore di `status` è `In Review` quando il paese individuato è in conflitto con `claimed_country`, oppure quando l'indirizzo è associato a un'infrastruttura VPN, Tor o data center. Altrimenti è `Approved`.\n\n**Con ogni ragionevole sforzo.** L'arricchimento dell'IP viene eseguito con ogni ragionevole sforzo. Se nessuna fonte di arricchimento restituisce dati utilizzabili, l'endpoint restituisce una risposta approvata con `ip.ip_address: null`, `ip.country_mismatch: null` e un oggetto `ip.threat` vuoto.\n\n**Fatturazione.** Le chiamate in produzione utilizzano i prezzi dell'API IP Risk. La richiesta è fatturabile a partire dall'avvio della ricerca.\n\n**Sandbox.** Le chiavi sandbox convalidano la richiesta e restituiscono dati approvati deterministici senza consumare crediti, creare una sessione o contribuire a Networks.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403`: questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste al minuto per chiave API su tutti gli endpoint POST/PATCH/DELETE (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600).", "operationId": "post_v3ip_risk", "x-didit-sdk": { "resource": "ip", "method": "assess_risk", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/ip/risk/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"ip_address\": \"8.8.8.8\",\n \"claimed_country\": \"ESP\",\n \"user_agent\": \"Mozilla/5.0\",\n \"vendor_data\": \"lead-123\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.ip.assess_risk(\n ip_address=\"8.8.8.8\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.ip.assessRisk({\n ip_address: \"8.8.8.8\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IP.AssessRisk(ctx, didit.IPRiskRequest{\n\tIPAddress: \"8.8.8.8\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.IPRiskRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.ip().assessRisk(IPRiskRequest.builder()\n .ipAddress(\"8.8.8.8\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "ip->assessRisk([\n 'ip_address' => '8.8.8.8',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.ip.assess_risk(ip_address: \"8.8.8.8\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Ip.AssessRiskAsync(new IPRiskRequest\n{\n IpAddress = \"8.8.8.8\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IPRiskRequest" }, "examples": { "Minimal": { "summary": "Calcola il punteggio di un indirizzo con i valori predefiniti", "value": { "ip_address": "8.8.8.8" } }, "With claimed country": { "summary": "Calcola il punteggio con un paese dichiarato per il rilevamento di discrepanze", "value": { "ip_address": "8.8.8.8", "claimed_country": "ESP", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15", "vendor_data": "lead-123" } } } } } }, "responses": { "200": { "description": "La valutazione del rischio è completata. Ispeziona `status` per la decisione; il codice HTTP è sempre `200` per le ricerche completate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IPRiskResponse" }, "examples": { "Clean residential IP": { "summary": "Indirizzo di residenza, il paese dichiarato corrisponde", "value": { "request_id": "9a96ed2a-721e-4b86-8cbf-d61eda529279", "status": "Approved", "ip": { "status": "Approved", "ip_address": "192.0.2.10", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Madrid", "ip_city": "Madrid", "latitude": 40.4168, "longitude": -3.7038, "isp": "Example Telecom", "organization": "Example Telecom SA", "is_vpn_or_tor": false, "is_data_center": false, "time_zone": "Europe/Madrid", "time_zone_offset": "+0200", "asn_number": 3352, "asn_organization": "EXAMPLE-TELECOM", "connection_type": "broadband", "carrier": "Example Telecom", "proxy_type": null, "claimed_country": "ESP", "country_mismatch": false, "threat": {} }, "vendor_data": "lead-123", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } }, "Datacenter mismatch": { "summary": "Indirizzo del data center in conflitto con il paese dichiarato", "value": { "request_id": "5b1d4e9a-3c7b-4f8e-9a2d-1b0c9d8e7f6a", "status": "In Review", "ip": { "status": "In Review", "ip_address": "8.8.8.8", "ip_country": "United States", "ip_country_code": "US", "ip_state": "California", "ip_city": "Mountain View", "latitude": 37.386, "longitude": -122.0838, "isp": "Google", "organization": "Google LLC", "is_vpn_or_tor": true, "is_data_center": true, "time_zone": "America/Los_Angeles", "time_zone_offset": "-0700", "asn_number": 15169, "asn_organization": "GOOGLE, US", "connection_type": "hosting", "carrier": null, "proxy_type": "VPN", "claimed_country": "ESP", "country_mismatch": true, "threat": { "is_proxy": true, "is_data_center": true, "is_tor": false } }, "vendor_data": "lead-126", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } } } } } }, "400": { "$ref": "#/components/responses/IPRiskValidationError" }, "403": { "$ref": "#/components/responses/RiskPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/phone/risk/": { "post": { "summary": "Calcola il punteggio di rischio di un numero di telefono", "description": "Risolvi un numero di telefono e ottieni operatore, tipo di linea, portabilità, numeri usa e getta, corrispondenza tra sessioni e segnali normalizzati di intelligence sul rischio senza inviare un OTP. L'endpoint crea una sessione API e restituisce il suo id come `request_id`.\n\n**Decisione.** Il campo di primo livello `status` riflette `phone.status`. Di norma è `Approved`; la valutazione del rischio può produrre `In Review` o `Declined`.\n\n**Alias di compatibilità.** Le risposte in produzione espongono l'oggetto intelligence normalizzato sia come `phone.phone_intelligence` sia come `phone.enrichment`. I valori sono identici. Le nuove integrazioni possono leggere `phone.enrichment`. Entrambe le chiavi sono assenti se non sono stati restituiti dati di intelligence utilizzabili.\n\n**Fatturazione.** Le chiamate in produzione utilizzano i prezzi della Phone Risk API. La richiesta è fatturabile non appena inizia la ricerca, anche se alcuni campi disponibili nei limiti del possibile non sono disponibili.\n\n**Sandbox.** Le chiavi sandbox convalidano la richiesta e restituiscono dati approvati deterministici senza inviare un OTP, consumare crediti, creare una sessione o contribuire a Networks.\n\n**Autenticazione.** Invia la chiave API della tua applicazione in `x-api-key`. Credenziali mancanti o non valide restituiscono `403` - questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste al minuto per chiave API su tutti gli endpoint POST/PATCH/DELETE (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600).\n\n**Impronta social.** Imposta `enable_social` su `true` per aggiungere un blocco `phone_social`: le piattaforme online su cui questo numero è registrato, con conteggi per categoria ed eventuali dettagli del profilo disponibili. `profiles_registered: 0` significa che le piattaforme sono state controllate e il numero non è stato trovato su nessuna di esse: una risposta valida e fatturabile. Il blocco è assente quando il componente aggiuntivo non è stato richiesto o il controllo non ha potuto essere completato, e in tal caso non viene fatturato. La fatturazione aggiunge un'unità `phone_social` per richiesta oltre al prezzo di questo stesso endpoint.", "operationId": "post_v3phone_risk", "x-didit-sdk": { "resource": "phone", "method": "assess_risk", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/phone/risk/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"+14155552671\",\n \"country_code\": \"US\",\n \"vendor_data\": \"lead-123\",\n \"metadata\": {\"source\": \"signup_prescreen\"}\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.phone.assess_risk(\n phone_number=\"+14155552671\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.phone.assessRisk({\n phone_number: \"+14155552671\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.AssessRisk(ctx, didit.PhoneRiskRequest{\n\tPhoneNumber: \"+14155552671\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.PhoneRiskRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.phone().assessRisk(PhoneRiskRequest.builder()\n .phoneNumber(\"+14155552671\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "phone->assessRisk([\n 'phone_number' => '+14155552671',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.phone.assess_risk(phone_number: \"+14155552671\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Phone.AssessRiskAsync(new PhoneRiskRequest\n{\n PhoneNumber = \"+14155552671\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneRiskRequest" }, "examples": { "Minimal": { "summary": "Calcola il punteggio di un numero con i valori predefiniti", "value": { "phone_number": "+14155552671" } }, "Full context": { "summary": "Calcola il punteggio con segnali, indicazione del paese e ID di correlazione", "value": { "phone_number": "+14155552671", "country_code": "US", "signals": { "ip": "192.0.2.1", "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2", "device_platform": "ios", "device_model": "iPhone17,2", "os_version": "18.0.1", "app_version": "1.2.34", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1" }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" } } } } } } }, "responses": { "200": { "description": "La valutazione del rischio è completata. Ispeziona `status` per la decisione; il codice HTTP è sempre `200` per le ricerche completate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneRiskResponse" }, "examples": { "Clean mobile number": { "summary": "Numero di cellulare pulito con copertura di intelligence", "value": { "request_id": "4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62", "status": "Approved", "phone": { "status": "Approved", "phone_number_prefix": "+1", "phone_number": "4155552671", "full_number": "+14155552671", "country_code": "US", "country_name": "United States", "carrier": { "name": "Example Mobile", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": null, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "phone_intelligence": { "score": 3.0, "phone_type_risk": "Low", "phone_trust_index": 97, "network_stability_index": 95, "is_disposable": false, "is_ported": false, "is_recently_ported": false, "carrier_type": "mobile", "reason_codes": [] }, "enrichment": { "score": 3.0, "phone_type_risk": "Low", "phone_trust_index": 97, "network_stability_index": 95, "is_disposable": false, "is_ported": false, "is_recently_ported": false, "carrier_type": "mobile", "reason_codes": [] } }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" }, "created_at": "2026-09-01T10:30:00.123456+00:00" } }, "Number in review": { "summary": "Numero usa e getta o virtuale contrassegnato per la revisione", "value": { "request_id": "8c22e1f0-4b3d-4a3a-9d1e-2f6b7c8d9e0f", "status": "In Review", "phone": { "status": "In Review", "phone_number_prefix": "+44", "phone_number": "7700900123", "full_number": "+447700900123", "country_code": "GB", "country_name": "United Kingdom", "carrier": { "name": "Example VoIP", "type": "voip" }, "is_disposable": true, "is_virtual": true, "verification_method": null, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "phone_intelligence": { "score": 72.0, "phone_type_risk": "High", "phone_trust_index": 28, "network_stability_index": 40, "is_disposable": true, "is_ported": true, "is_recently_ported": true, "carrier_type": "voip", "reason_codes": [ { "code": "IR-5AC67A32", "direction": "risk", "message": "Phone type identified as non-mobile", "impact_level": "medium" } ] }, "enrichment": { "score": 72.0, "phone_type_risk": "High", "phone_trust_index": 28, "network_stability_index": 40, "is_disposable": true, "is_ported": true, "is_recently_ported": true, "carrier_type": "voip", "reason_codes": [ { "code": "IR-5AC67A32", "direction": "risk", "message": "Phone type identified as non-mobile", "impact_level": "medium" } ] } }, "vendor_data": "lead-124", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } } } } } }, "400": { "$ref": "#/components/responses/PhoneRiskValidationError" }, "403": { "$ref": "#/components/responses/RiskPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/": { "post": { "summary": "Crea una sessione di verifica", "description": "Crea una sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB) e ricevi un `url` di verifica ospitata insieme a un `session_token` da reindirizzare o incorporare per il tuo utente finale. Il parametro `workflow_id` seleziona quali passaggi di verifica eseguire e se la sessione è KYC o KYB.\n\nChiama questo endpoint dal tuo backend (mai dal browser — la chiave API è un segreto) ogni volta che un utente o un'azienda deve essere verificata: alla registrazione, prima di un'azione sensibile o quando è richiesta una nuova verifica. Prerequisiti: un workflow pubblicato (creato nella pagina [Workflows](https://docs.didit.me/it/console/workflows) della Console) e una chiave API dell'applicazione con crediti disponibili. Le applicazioni sandbox ignorano il controllo dei crediti.\n\n**Idempotenza:** quando viene fornito `vendor_data` ed esiste già una sessione non completata (`Not Started`, `In Progress`, `Resubmitted` o `Awaiting User`) con lo stesso `vendor_data` nell'**ultima versione attualmente pubblicata** del workflow (e tale sessione dispone già di un URL di verifica ospitata), viene restituita la sessione esistente (sempre `201`) invece di creare un duplicato — con i relativi `callback` e `metadata` aggiornati ai nuovi valori forniti. Una sessione non completata creata su una versione precedente del workflow (che nel frattempo è stata ripubblicata) **non** viene riutilizzata; viene invece creata una nuova sessione associata all'ultima versione pubblicata. Le sessioni in `Approved`, `Declined`, `In Review`, `Expired`, `Abandoned` o `Kyc Expired` non vengono mai riutilizzate.\n\n**Effetti collaterali:** l'URL di verifica ospitata viene generato e memorizzato; se `contact_details.send_notification_emails` è `true` e viene fornita un'email, viene inviata un'email di invito alla verifica. La sessione scade dopo il tempo di scadenza della sessione configurato nel workflow. Per i workflow KYB, `contact_details.phone` ed `expected_details` vengono ignorati.", "operationId": "post_v3_session_create", "x-didit-sdk": { "resource": "sessions", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "201": { "description": "Sessione creata (o restituita, se esiste già una sessione non completata con gli stessi `vendor_data` sull'ultima versione pubblicata del workflow). La risposta è la sessione serializzata, incluso l'`url` della pagina di verifica ospitata a cui reindirizzare l'utente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "session_number", "session_token", "url", "vendor_data", "metadata", "status", "workflow_id", "workflow_version", "callback" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Identificativo univoco della sessione di verifica. Usa questo id quando chiami `GET /v3/session/{sessionId}/decision/`.", "example": "11111111-2222-3333-4444-555555555555" }, "session_number": { "type": "integer", "description": "Numero sequenziale e di facile lettura assegnato alla sessione all'interno della tua applicazione. Utile per l'assistenza e le dashboard.", "example": 43762 }, "session_token": { "type": "string", "description": "Token URL-safe di 12 caratteri che autorizza l'utente finale ad accedere al flusso di verifica ospitato all'indirizzo `url`. Valido fino alla scadenza della sessione. Trattalo come un segreto: chiunque lo possieda può aprire il flusso di verifica per questa sessione.", "example": "3FaJ9wLqX2Mz" }, "url": { "type": "string", "format": "uri", "description": "URL di verifica ospitato a cui reindirizzare l'utente finale. L'URL include il `session_token` e, se configurato, utilizza il tuo dominio white label. Quando la richiesta include `language`, l'URL contiene un segmento di percorso per la lingua — `https://verify.didit.me/{language}/session/{session_token}` (ad es. `/es/session/...`); senza `language`, il segmento viene omesso.", "example": "https://verify.didit.me/session/3FaJ9wLqX2Mz" }, "vendor_data": { "type": "string", "nullable": true, "description": "Identificatore che hai passato nella richiesta per collegare la sessione a un utente o a un'azienda nel tuo sistema. Restituito esattamente come inviato. Null se non fornito.", "example": "user-123" }, "metadata": { "description": "Payload JSON arbitrario memorizzato con la sessione al momento della creazione. Viene restituito testualmente: qualunque valore JSON inviato (oggetto, stringa, numero, array) viene restituito così com'è, anche se è consigliato un oggetto JSON. Non viene mostrato all'utente finale. Sempre presente nelle risposte; `null` se non fornito al momento della creazione.", "example": { "user_type": "premium", "account_id": "ABC123" } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "I tag presenti sulla sessione, per nome.", "example": [ "VIP", "ONBOARDING Q4" ] }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Stato attuale della sessione. Le sessioni appena create restituiscono `Not Started`. Se esisteva già una sessione non conclusa per lo stesso `vendor_data` sull'ultima versione pubblicata del workflow, lo stato restituito riflette tale sessione esistente.", "example": "Not Started" }, "callback": { "type": "string", "format": "uri", "nullable": true, "description": "URL di reindirizzamento finale a cui l'utente viene inviato dopo aver completato il flusso. Didit aggiunge `?verificationSessionId={session_id}&status={status}` a questo URL. Utilizza come fallback l'URL di callback configurato nel workflow se non fornito nella richiesta; `null` quando nessuno dei due è impostato. Se l'applicazione ha domini consentiti e questo URL è un URL web esterno a essi (ad esempio un valore predefinito del workflow impostato prima della modifica dell'elenco), il flusso ospitato non vi reindirizza l'utente.", "example": "https://example.com/verification/callback" }, "workflow_id": { "type": "string", "format": "uuid", "description": "Identificatore stabile del workflow su cui viene eseguita questa sessione. Corrisponde sempre all'identificatore di gruppo stabile del workflow; anche se nella richiesta hai fatto riferimento all'UUID di una versione specifica del workflow (ricerca retrocompatibile), la risposta riporta il `workflow_id` stabile. Usalo per correlare la sessione con il workflow configurato nella Console.", "example": "11111111-2222-3333-4444-555555555555" }, "workflow_version": { "type": "integer", "description": "Numero di versione della versione pubblicata del workflow a cui la sessione è stata associata al momento della creazione. Didit risolve `workflow_id` con l'ultima versione pubblicata del workflow quando la sessione viene creata, e la sessione continua a eseguire quella versione anche se il workflow viene ripubblicato successivamente.", "example": 3 } } }, "examples": { "KYC session": { "summary": "Sessione KYC creata", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "session_number": 43762, "session_token": "3FaJ9wLqX2Mz", "url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz", "vendor_data": "user-123", "metadata": { "user_type": "premium", "account_id": "ABC123" }, "status": "Not Started", "workflow_id": "11111111-2222-3333-4444-555555555555", "workflow_version": 3, "callback": "https://example.com/verification/callback" } }, "KYB session": { "summary": "Sessione KYB creata", "value": { "session_id": "22222222-3333-4444-5555-666666666666", "session_number": 43763, "session_token": "Yk7pQ2vN8aBc", "url": "https://verify.didit.me/en/session/Yk7pQ2vN8aBc", "vendor_data": "company-acme-001", "metadata": { "tier": "enterprise" }, "status": "Not Started", "workflow_id": "33333333-4444-5555-6666-777777777777", "workflow_version": 1, "callback": "https://example.com/kyb/callback" } } } } } }, "400": { "description": "Richiesta non valida: la convalida del payload non è riuscita (`workflow_id` mancante o sconosciuto, `language` non valido, `vendor_data` inserito nella blocklist, `portrait_image` non valido, `address` senza `country`/`poa_country`, `sandbox_scenario` non valido, documenti `sign`, campi o valori rifiutati dal passaggio di Firma elettronica del workflow, come `signature_document_not_supported`, `signature_document_conversion_failed`, `field_anchor_not_found` o `field_value_missing`, ecc.) oppure la tua organizzazione non dispone di crediti sufficienti per avviare la sessione.\n\nIl corpo è un oggetto avente come chiave il nome del campo responsabile dell'errore (o `detail` per gli errori non legati ai campi). I valori sono un **array di stringhe** per gli errori di convalida dell'input (ad es. campo obbligatorio mancante, lingua non valida, immagine del ritratto di dimensioni eccessive) e una **stringa semplice** per gli errori rilevati durante la creazione della sessione (`workflow_id` sconosciuto, `vendor_data` presente nella blocklist, nessun volto di riferimento disponibile per un workflow di Confronto facciale). Gestisci entrambi i formati.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura per errori non legati a singoli campi (ad es. crediti insufficienti). Gli errori a livello di campo utilizzano invece il nome del campo come chiave, con una stringa o un array di stringhe come valore.", "example": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } }, "examples": { "Missing workflow_id": { "summary": "Campo obbligatorio omesso (formato array di stringhe)", "value": { "workflow_id": [ "This field is required." ] } }, "Invalid workflow_id": { "summary": "workflow_id sconosciuto (formato stringa semplice)", "value": { "workflow_id": "Invalid workflow_id." } }, "Insufficient credits": { "summary": "L'organizzazione ha esaurito i crediti", "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } }, "Blocklisted vendor_data": { "summary": "vendor_data è in blocklist", "value": { "vendor_data": "This user or business has been blocked and cannot create new verification sessions." } }, "Portrait image too large": { "summary": "portrait_image non supera la validazione delle dimensioni", "value": { "portrait_image": [ "Image size exceeds 2MB." ] } }, "No stored face for vendor_data": { "summary": "Workflow di Confronto facciale senza portrait_image e senza volto memorizzato per l'utente vendor_data", "value": { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } }, "Portrait image required without vendor_data": { "summary": "Workflow di Confronto facciale senza portrait_image e senza vendor_data", "value": { "portrait_image": "A portrait image is required to perform face match for this workflow. Send a portrait_image, or provide the vendor_data of a user with a previously stored face image to reuse it." } } } } } }, "403": { "description": "Autenticazione o autorizzazione non riuscita. Una chiave errata, revocata o scaduta restituisce `401`. L'endpoint restituisce `403` quando l'intestazione `x-api-key` è mancante o la chiave API è valida ma il client non dispone dell'autorizzazione per creare sessioni in questa applicazione (ad esempio la chiave API appartiene a un'organizzazione diversa). Questi errori condividono il corpo `{\"detail\": \"You do not have permission to perform this action.\"}`. Verifica che l'intestazione `x-api-key` sia presente e appartenga all'applicazione desiderata, recupera nuovamente la chiave API dell'applicazione tramite l'[Auth API](/it/auth-api/get-credentials) se necessario, e riprova.\n\n**Applicazione eliminata:** per alcuni minuti dopo l'eliminazione di un'applicazione, una richiesta effettuata con una delle sue chiavi API può rispondere `{\"detail\": \"This application was deleted.\", \"code\": \"application_deleted\"}`. Non riprovare: l'applicazione e le sue chiavi API non esistono più. Trascorsi questi pochi minuti, la chiave viene rifiutata come qualsiasi altra chiave non valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." }, "code": { "type": "string", "description": "Motivo leggibile dalla macchina, presente solo per alcuni errori. `application_deleted`: la chiave API appartiene a un'applicazione che è stata eliminata.", "example": "application_deleted" } }, "required": [ "detail" ] }, "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key` o chiave API non valida", "value": { "detail": "You do not have permission to perform this action." } }, "No permission": { "summary": "Il client non può creare sessioni", "value": { "detail": "You do not have permission to perform this action." } }, "Application deleted": { "summary": "Chiave API di un'applicazione eliminata", "value": { "detail": "This application was deleted.", "code": "application_deleted" } } } } } }, "429": { "description": "Limite di frequenza superato — più di 600 richieste di creazione di sessioni in una finestra di 60 secondi dalla stessa chiave API / IP. Esamina `Retry-After` e attendi prima di riprovare.\n\n**Nota:** il codice sorgente definisce anche un `FREE_SESSION_RATE_LIMIT` di 10 chiamate/minuto insieme a `PAID_SESSION_RATE_LIMIT=600` (`sessions/serializers/session.py`), ma tale soglia del piano gratuito **non è applicata a questo endpoint V3** — il middleware del limite di frequenza applica il valore di 600/min `SESSION_CREATE_RATE_LIMIT` indipendentemente dal piano. 600/min è l'unico limite che puoi raggiungere qui.", "headers": { "Retry-After": { "description": "Secondi che il chiamante deve attendere prima di riprovare la richiesta.", "schema": { "type": "integer", "minimum": 1, "example": 42 } }, "X-RateLimit-Limit": { "description": "Numero massimo di richieste consentite nella finestra temporale corrente di 60 secondi per il limite superato (600 per session-create). Assente nella variante della quota sandbox.", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Numero di richieste ancora consentite nell'intervallo corrente per il limite superato. Assente nella variante della quota di sandbox.", "schema": { "type": "integer", "minimum": 0, "example": 0 } }, "X-RateLimit-Reset": { "description": "Secondi dell'epoch UTC in cui si reimposta l'attuale finestra del limite di frequenza. Assente nella variante della quota di sandbox.", "schema": { "type": "integer", "minimum": 0, "example": 1747497600 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Spiegazione di facile lettura del superamento del limite di frequenza. Usa questo messaggio per distinguere quale dei tre limiti è stato raggiunto.", "example": "Session creation rate limit exceeded. You can make up to 600 requests per minute." } } }, "examples": { "Session-create limit": { "summary": "Più di 600 richieste di creazione sessione al minuto", "value": { "detail": "Session creation rate limit exceeded. You can make up to 600 requests per minute." } }, "Sandbox session quota": { "summary": "L'applicazione sandbox ha superato 500 sessioni in 24 ore", "value": { "detail": "Sandbox session quota exceeded (500 sessions per 24h). Wait for the window to reset. Expected available in 3600 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/session/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"workflow_id\": \"11111111-2222-3333-4444-555555555555\",\n \"vendor_data\": \"user-123\",\n \"callback\": \"https://example.com/verification/callback\",\n \"callback_method\": \"both\",\n \"metadata\": {\"user_type\": \"premium\", \"account_id\": \"ABC123\"},\n \"language\": \"en\",\n \"contact_details\": {\n \"email\": \"john.doe@example.com\",\n \"send_notification_emails\": true,\n \"email_lang\": \"en\",\n \"phone\": \"+14155552671\"\n },\n \"expected_details\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"id_country\": \"USA\",\n \"expected_document_types\": [\"P\", \"ID\"]\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.create(\n workflow_id=\"11111111-2222-3333-4444-555555555555\",\n vendor_data=\"user-123\",\n callback=\"https://example.com/verification/callback\",\n callback_method=\"both\",\n metadata={\"user_type\": \"premium\", \"account_id\": \"ABC123\"},\n language=\"en\",\n contact_details={\n \"email\": \"john.doe@example.com\",\n \"send_notification_emails\": True,\n \"email_lang\": \"en\",\n \"phone\": \"+14155552671\",\n },\n expected_details={\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"nationality\": \"USA\",\n \"id_country\": \"USA\",\n \"expected_document_types\": [\"P\", \"ID\"],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.create({\n workflow_id: \"11111111-2222-3333-4444-555555555555\",\n vendor_data: \"user-123\",\n callback: \"https://example.com/verification/callback\",\n callback_method: \"both\",\n metadata: { user_type: \"premium\", account_id: \"ABC123\" },\n language: \"en\",\n contact_details: {\n email: \"john.doe@example.com\",\n send_notification_emails: true,\n email_lang: \"en\",\n phone: \"+14155552671\",\n },\n expected_details: {\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1990-05-15\",\n nationality: \"USA\",\n id_country: \"USA\",\n expected_document_types: [\"P\", \"ID\"],\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().create(SessionsCreateParams.builder()\n .workflowId(\"11111111-2222-3333-4444-555555555555\")\n .vendorData(\"user-123\")\n .callback(\"https://example.com/verification/callback\")\n .callbackMethod(SessionsCreateParams.CallbackMethod.of(\"both\"))\n .metadata(Map.of(\"user_type\", \"premium\", \"account_id\", \"ABC123\"))\n .language(SessionsCreateParams.Language.of(\"en\"))\n .contactDetails(SessionsCreateParams.ContactDetails.builder()\n .email(\"john.doe@example.com\")\n .sendNotificationEmails(true)\n .emailLang(SessionsCreateParams.ContactDetails.EmailLang.of(\"en\"))\n .phone(\"+14155552671\")\n .build())\n .expectedDetails(SessionsCreateParams.ExpectedDetails.builder()\n .firstName(\"John\")\n .lastName(\"Doe\")\n .dateOfBirth(LocalDate.parse(\"1990-05-15\"))\n .nationality(\"USA\")\n .idCountry(\"USA\")\n .expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of(\"P\"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of(\"ID\")))\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->create([\n 'workflow_id' => '11111111-2222-3333-4444-555555555555',\n 'vendor_data' => 'user-123',\n 'callback' => 'https://example.com/verification/callback',\n 'callback_method' => 'both',\n 'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],\n 'language' => 'en',\n 'contact_details' => [\n 'email' => 'john.doe@example.com',\n 'send_notification_emails' => true,\n 'email_lang' => 'en',\n 'phone' => '+14155552671',\n ],\n 'expected_details' => [\n 'first_name' => 'John',\n 'last_name' => 'Doe',\n 'date_of_birth' => '1990-05-15',\n 'nationality' => 'USA',\n 'id_country' => 'USA',\n 'expected_document_types' => ['P', 'ID'],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.create(\n workflow_id: \"11111111-2222-3333-4444-555555555555\",\n vendor_data: \"user-123\",\n callback: \"https://example.com/verification/callback\",\n callback_method: \"both\",\n metadata: { user_type: \"premium\", account_id: \"ABC123\" },\n language: \"en\",\n contact_details: {\n email: \"john.doe@example.com\",\n send_notification_emails: true,\n email_lang: \"en\",\n phone: \"+14155552671\",\n },\n expected_details: {\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1990-05-15\",\n nationality: \"USA\",\n id_country: \"USA\",\n expected_document_types: [\"P\", \"ID\"],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.CreateAsync(new SessionsCreateParams\n{\n WorkflowId = \"11111111-2222-3333-4444-555555555555\",\n VendorData = \"user-123\",\n Callback = \"https://example.com/verification/callback\",\n CallbackMethod = new SessionsCreateParamsCallbackMethod(\"both\"),\n Metadata = new Dictionary { [\"user_type\"] = \"premium\", [\"account_id\"] = \"ABC123\" },\n Language = new SessionsCreateParamsLanguage(\"en\"),\n ContactDetails = new SessionsCreateParamsContactDetails\n {\n Email = \"john.doe@example.com\",\n SendNotificationEmails = true,\n EmailLang = new SessionsCreateParamsContactDetailsEmailLang(\"en\"),\n Phone = \"+14155552671\",\n },\n ExpectedDetails = new SessionsCreateParamsExpectedDetails\n {\n FirstName = \"John\",\n LastName = \"Doe\",\n DateOfBirth = \"1990-05-15\",\n Nationality = \"USA\",\n IdCountry = \"USA\",\n ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { \"P\", \"ID\" },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workflow_id" ], "properties": { "workflow_id": { "type": "string", "format": "uuid", "description": "Identificatore stabile del workflow che definisce i passaggi di verifica che la sessione eseguirà. I workflow vengono creati e gestiti nella pagina [Workflows](/it/console/workflows) della Console. Il valore `workflow_id` seleziona inoltre implicitamente se la sessione è KYC o KYB.", "example": "11111111-2222-3333-4444-555555555555", "x-readme-id": "0.0" }, "vendor_data": { "type": "string", "description": "Un identificatore univoco per l'utente in fase di verifica, come un UUID, un'email o un ID utente interno. Questo campo è utilizzato per: (1) **Raggruppamento degli utenti** — le sessioni con lo stesso vendor_data vengono collegate allo stesso profilo utente nella scheda Utenti. (2) **Rilevamento di duplicati cross-sessione** — durante il controllo di volti, documenti, numeri di telefono, email, indirizzi IP o fingerprint dei dispositivi duplicati, le sessioni con lo stesso vendor_data vengono trattate come lo stesso utente ed escluse dalle corrispondenze. Senza vendor_data, ogni sessione viene considerata come un utente univoco e vengono mostrati tutti i potenziali duplicati. Consigliamo vivamente di fornire sempre un vendor_data per ridurre il rumore nel rilevamento dei duplicati.", "example": "user-123", "x-readme-id": "0.1" }, "multi_account_segment": { "type": "string", "maxLength": 64, "description": "Ambito opzionale per il rilevamento dei duplicati all'interno della tua organizzazione. I controlli dei volti duplicati confrontano questa sessione solo con altre sessioni che presentano lo stesso segmento, in modo che basi di account distinte (account personali e aziendali, o uno per ciascun sub-cliente B2B) non segnalino una persona che possiede legittimamente un account in ciascuna di esse. Omettilo per utilizzare il singolo ambito predefinito, che è quello utilizzato oggi da ogni sessione. La corrispondenza con blocklist e allowlist ignora questo campo.", "example": "business-accounts" }, "callback": { "type": "string", "description": "URL a cui reindirizzare l'utente al termine della verifica. Didit aggiunge automaticamente `verificationSessionId` e `status` (Approved, Declined, In Review) come parametri di query. Gli schemi URL personalizzati (es. `myapp://`) sono supportati per i callback su dispositivi mobili. Se omesso, viene utilizzato il `callback_url` predefinito del workflow. Quando l'applicazione ha domini consentiti (`allowed_domains` su `PATCH /v3/webhook/`), un callback `http` o `https` deve appartenere a una di queste origini (stesso schema, host e porta), altrimenti la richiesta non va a buon fine con 400 su `callback`: `callback must be on one of the application's allowed domains: https://app.example.com`. Gli schemi URL personalizzati sono sempre accettati.", "example": "https://example.com/verification/callback", "x-readme-id": "0.2" }, "callback_method": { "type": "string", "description": "Determina quale dispositivo deve gestire il reindirizzamento all'URL di callback fornito. Usa `initiator` per reindirizzare solo il dispositivo che ha avviato il flusso, `completer` per il dispositivo che lo completa, oppure `both` per consentire a entrambi i dispositivi di attivare il callback. Se noti che il callback non si attiva in modo affidabile, ti consigliamo di impostare questo valore su `both`.", "enum": [ "initiator", "completer", "both" ], "default": "initiator", "example": "both", "x-readme-id": "0.3" }, "metadata": { "description": "JSON arbitrario memorizzato con la sessione e restituito nella risposta e nei webhook. È accettato qualsiasi valore JSON (oggetto, stringa, numero, array), ma è consigliato un oggetto JSON di coppie chiave/valore. Non viene mostrato all'utente finale. Utilizzalo per trasmettere i tuoi ID di correlazione, varianti A/B o il contesto aziendale.", "example": { "user_type": "premium", "account_id": "ABC123" }, "x-readme-id": "0.4" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 10, "description": "Tag aggiunti alla sessione al momento della creazione, per nome. Fino a 10, ciascuno di massimo 50 caratteri. I nomi non distinguono tra maiuscole e minuscole e vengono memorizzati in maiuscolo. Un nome non ancora presente nell'applicazione viene creato come nuovo tag. I tag compaiono sulla sessione nella console, dove puoi filtrarli.", "example": [ "VIP", "ONBOARDING Q4" ] }, "language": { "type": "string", "description": "Codice lingua (ISO 639-1) per l'interfaccia della procedura di verifica. Controlla la lingua mostrata all'utente finale durante la verifica. Se non fornito, la lingua del browser verrà rilevata e utilizzata automaticamente. Consulta tutte le lingue supportate [qui](/it/integration/supported-languages).", "enum": [ "en", "ar", "bg", "bn", "bs", "ca", "cnr", "cs", "da", "de", "el", "es", "et", "fa", "fi", "fr", "he", "hi", "hr", "hu", "hy", "id", "it", "ja", "ka", "kk", "ko", "ky", "lt", "lv", "mk", "mn", "ms", "nl", "no", "pl", "pt-BR", "pt", "ro", "ru", "sk", "sl", "so", "sq", "sr", "sv", "th", "tr", "uk", "uz", "vi", "zh-CN", "zh-TW", "zh" ], "example": "en", "x-readme-id": "0.5" }, "contact_details": { "type": "object", "description": "Informazioni di contatto dell'utente che possono essere utilizzate per le notifiche, la precompilazione dei moduli di verifica e la verifica telefonica. Sono inclusi l'indirizzo email, la lingua preferita per le comunicazioni e il numero di telefono.", "example": { "email": "john.doe@example.com", "send_notification_emails": true, "email_lang": "en", "phone": "+14155552671" }, "properties": { "email": { "type": "string", "format": "email", "description": "Indirizzo email dell'utente (ad es. \"john.doe@example.com\") che verrà utilizzato durante il passaggio di [Verifica email](/it/core-technology/email-verification/overview). Se non fornito, l'utente dovrà inserirlo durante il flusso di verifica.", "example": "john.doe@example.com", "x-readme-id": "1.0" }, "send_notification_emails": { "type": "boolean", "default": false, "description": "Se true e viene fornito un indirizzo email, Didit invia l'email iniziale \"Verifica la tua identità\" in modo asincrono quando viene creata la sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB). Didit invia inoltre le notifiche sullo stato della verifica per le sessioni che richiedono una revisione manuale all'indirizzo email fornito (es. da 'In Review' ad 'Approved' o 'Declined'). Questo aiuta gli utenti a tornare alla tua applicazione una volta completata la verifica. Se hai attivato il white label per la sessione, l'email inviata sarà in white label.", "example": true, "x-readme-id": "1.1" }, "email_lang": { "type": "string", "description": "Codice lingua (ISO 639-1) per le notifiche email. Controlla la lingua di tutte le comunicazioni via email (es. \"en\", \"es\", \"fr\"). Non è memorizzato alcun valore predefinito: quando omesso, l'email di invito alla verifica torna semplicemente all'inglese (`en`) al momento dell'invio. L'enum sottostante è un'istantanea; la fonte di verità aggiornata per i valori accettati è la documentazione sulle [lingue supportate](/it/integration/supported-languages): consultala sempre prima di affidarti a uno specifico codice.", "enum": [ "en", "ar", "bg", "bn", "bs", "ca", "cnr", "cs", "da", "de", "el", "es", "et", "fa", "fi", "fr", "he", "hi", "hr", "hu", "hy", "id", "it", "ja", "ka", "kk", "ko", "ky", "lt", "lv", "mk", "mn", "ms", "nl", "no", "pl", "pt-BR", "pt", "ro", "ru", "sk", "sl", "so", "sq", "sr", "sv", "th", "tr", "uk", "uz", "vi", "zh-CN", "zh-TW", "zh" ], "example": "en", "x-readme-id": "1.2" }, "phone": { "type": "string", "description": "Numero di telefono in formato E.164 (ad es. \"+14155552671\") che verrà utilizzato durante il passaggio di [Verifica telefonica](/it/core-technology/phone-verification/overview). Se non fornito, l'utente deve inserirlo durante il flusso di verifica. Ignorato per i workflow di Verifica aziendale (KYB). **Importante:** questo numero di telefono viene applicato solo se è un numero di telefono E.164 valido. Se il numero fornito non è valido o non può essere analizzato, verrà ignorato e l'utente potrà inserire qualsiasi numero di telefono valido durante il passaggio di Verifica telefonica.", "example": "+14155552671", "x-readme-id": "1.3" } }, "x-readme-id": "0.4" }, "expected_details": { "type": "object", "description": "Dettagli dell'utente previsti utilizzati per la convalida incrociata rispetto ai dati estratti dal documento d'identità dell'utente, dalla Prova di residenza e da altri passaggi di verifica. Le discrepanze vengono segnalate come avvisi nella decisione; alcuni campi (ad es. `id_country`, `expected_document_types`) modificano anche il flusso visibile all'utente. Per i workflow di Verifica aziendale (KYB) vengono utilizzati solo i campi aziendali (`company_name`, `registry_country`, `registration_number`) — che precompilano la ricerca nel registro delle imprese per l'utente — e tutti i campi relativi alla persona vengono ignorati.", "example": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "nationality": "USA", "id_country": "USA", "expected_document_types": [ "P", "ID" ] }, "properties": { "first_name": { "type": "string", "description": "Nome dell'utente. Ad esempio, `John`. La corrispondenza utilizza un confronto fuzzy ed è possibile regolare il livello di rigore configurando la soglia del punteggio di corrispondenza del nome nella Console sia per i workflow di Documento d'identità che per quelli di Prova di residenza.", "example": "John", "x-readme-id": "1.0" }, "last_name": { "type": "string", "description": "Cognome dell'utente. Ad esempio, `Doe`. La corrispondenza utilizza un confronto fuzzy ed è possibile regolare il livello di rigore configurando la soglia del punteggio di corrispondenza del nome nella Console sia per i workflow di Documento d'identità che per quelli di Prova di residenza.", "example": "Doe", "x-readme-id": "1.1" }, "date_of_birth": { "type": "string", "format": "date", "description": "Data di nascita dell'utente nel formato: YYYY-MM-DD. Ad esempio, `1990-05-15`.", "example": "1990-05-15", "x-readme-id": "1.2" }, "gender": { "type": "string", "nullable": true, "enum": [ "M", "F" ], "default": null, "description": "Genere dell'utente. Deve essere 'M', 'F' o null.", "example": "M", "x-readme-id": "1.3" }, "nationality": { "type": "string", "description": "Codice paese ISO 3166-1 alpha-3 che rappresenta il paese di origine del richiedente. Ad esempio, `USA`. Consulta l'[elenco completo dei codici paese supportati](https://docs.didit.me/it/core-technology/id-verification/supported-documents-id-verification#documenti-supportati-per-paese).", "example": "USA", "x-readme-id": "1.4" }, "country": { "type": "string", "description": "Codice paese ISO 3166-1 alpha-3 utilizzato come fallback per i controlli di mancata corrispondenza del paese sia per la Verifica dell'identità sia per la Prova di residenza. Obbligatorio se viene fornito `address` e non sono impostati né `id_country` né `poa_country`.", "example": "USA", "x-readme-id": "1.4.1" }, "id_country": { "type": "string", "description": "Codice paese ISO 3166-1 alpha-3 che rappresenta il paese previsto del documento d'identità del richiedente, che può differire dalla nazionalità. Ad esempio, `GBR`. Ha la priorità su `country` per i controlli di mancata corrispondenza del paese per la Verifica dell'identità. Consulta l'[elenco completo dei codici paese supportati](https://docs.didit.me/it/core-technology/id-verification/supported-documents-id-verification#documenti-supportati-per-paese).", "example": "GBR", "x-readme-id": "1.5" }, "poa_country": { "type": "string", "description": "Codice paese ISO 3166-1 alpha-3 che rappresenta il paese previsto del documento di Prova di residenza. Ad esempio, `USA`. Ha la priorità su `country` per i controlli di mancata corrispondenza del paese del POA. Consulta l'[elenco completo dei codici paese supportati](https://docs.didit.me/it/core-technology/id-verification/supported-documents-id-verification#documenti-supportati-per-paese).", "example": "USA", "x-readme-id": "1.5.1" }, "address": { "type": "string", "description": "L'indirizzo in un formato leggibile, includendo quante più informazioni possibili. Ad esempio, `123 Main St, San Francisco, CA 94105, USA`. Se fornito, devi includere anche `country` o `poa_country`, altrimenti la richiesta non va a buon fine con un errore `400`.", "example": "123 Main St, San Francisco, CA 94105, USA", "x-readme-id": "1.6" }, "identification_number": { "type": "string", "description": "Il numero del documento, il codice personale o il codice fiscale dell'utente. Ad esempio, `123456789`.", "example": "123456789", "x-readme-id": "1.7" }, "ip_address": { "type": "string", "description": "Indirizzo IP previsto per la sessione, in formato IPv4 o IPv6. Se l'indirizzo IP effettivo differisce da questo valore, verrà registrato un avviso. Ad esempio, `192.168.1.100` o `2001:db8::1`.", "example": "192.168.1.100", "x-readme-id": "1.8" }, "expected_document_types": { "type": "array", "description": "Limita i tipi di documento che l'utente può presentare durante il passaggio di verifica dell'identità (OCR). Quando viene impostato, la schermata di selezione del documento mostra solo i tipi richiesti e il valore restituito `documents_allowed` viene filtrato di conseguenza. I valori non distinguono tra maiuscole e minuscole e vengono deduplicati; i valori sconosciuti vengono rifiutati con `400`. Codici consentiti: `P` (passaporto), `ID` (carta d'identità), `DL` (patente di guida), `RP` (permesso di soggiorno), `HIC` (tessera sanitaria), `TC` (codice fiscale/tessera fiscale), `SSC` (tessera di sicurezza sociale).", "items": { "type": "string", "enum": [ "P", "ID", "DL", "RP", "HIC", "TC", "SSC" ] }, "example": [ "P", "ID" ], "x-readme-id": "1.9" }, "company_name": { "type": "string", "maxLength": 255, "description": "Ragione sociale prevista dell'azienda oggetto di verifica. Ad esempio, `Tesco PLC`. Precompila il campo della ragione sociale nella ricerca nel registro nei workflow di Verifica aziendale (KYB); quando viene fornito anche `registration_number`, la ricerca nel registro combina entrambi gli identificatori. Ignorato per i workflow KYC.", "example": "Tesco PLC", "x-readme-id": "1.10" }, "registry_country": { "type": "string", "maxLength": 10, "description": "Codice ISO 3166-1 alpha-2 del paese nel cui registro delle imprese è registrata l'azienda. Ad esempio, `GB`. Laddove i registri delle imprese operano a livello statale o provinciale, aggiungi il codice di suddivisione ISO 3166-2 come `XX-YY`: `US-CA` punta al registro della California. Stesso formato di `country_code` sull'[API di ricerca nel registro KYB](https://docs.didit.me/it/standalone-apis/kyb-registry-search). Pre-seleziona il paese del registro nei workflow di Verifica aziendale (KYB); ignorato per i workflow KYC.", "example": "US-CA", "x-readme-id": "1.11" }, "registration_number": { "type": "string", "maxLength": 100, "description": "Numero di registrazione previsto dell'azienda nel registro delle imprese. Ad esempio, `00445790`. Precompila il campo del numero di registrazione nella ricerca nel registro nei workflow di Verifica aziendale (KYB); quando viene fornito anche `company_name`, la ricerca nel registro combina entrambi gli identificatori. Ignorato per i workflow KYC.", "example": "00445790", "x-readme-id": "1.12" } }, "x-readme-id": "0.5" }, "portrait_image": { "type": "string", "format": "byte", "description": "Immagine del volto dell'utente finale codificata in Base64 (max 2 MB; JPEG, PNG, WebP o TIFF). Utilizzata come immagine di riferimento da confrontare con l'acquisizione della vitalità quando il workflow è un workflow di `Biometric Authentication` con Confronto facciale abilitato, o qualsiasi workflow a grafo in cui il Confronto facciale viene eseguito prima della Verifica dell'identità (OCR). Opzionale quando l'utente specificato in `vendor_data` ha già un'immagine del volto memorizzata: Didit la riutilizza automaticamente, risolvendola in ordine di priorità: volto da rilevamento della vitalità approvato, foto del chip dell'ePassport, ritratto del documento d'identità, volto del profilo registrato manualmente (vengono riutilizzati solo i volti provenienti da sessioni approvate o i volti che hai registrato personalmente). Se fornita, `portrait_image` ha sempre la precedenza sul volto memorizzato. Se omessa e non esiste alcun volto memorizzato (o non viene inviato `vendor_data`), la creazione della sessione fallisce con `400`. Ignorata per altri tipi di workflow.", "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "x-readme-id": "0.6" }, "sandbox_scenario": { "type": "string", "description": "Slug dello scenario solo per la sandbox. Accettato solo quando la chiave API appartiene a un'applicazione in modalità sandbox; rifiutato nelle applicazioni di produzione. Se impostato, il flusso di creazione inserisce i valori magici associati allo scenario nei campi di input della sessione (contact_details, expected_details), consentendo ai provider simulati di riprodurre l'esito dello scenario lungo l'effettiva pipeline del workflow. Consulta il catalogo degli scenari con GET /v1/sandbox/scenarios/ o in [Sandbox e dati di test](/it/integration/sandbox-testing). Puoi anche preparare (o ripreparare) uno scenario dopo la creazione tramite POST /v3/session/{sessionId}/sandbox/arm/, a condizione che la sessione sia ancora `Not Started`. Per le verifiche senza documenti, usa `lookup_partial_match`, `lookup_no_match` o `lookup_provider_error` per testare il budget di tentativi configurato e il fallback. Per i wallet di identità, usa `wallet_cancelled`, `wallet_timeout` o `wallet_provider_error`; `approve` simula un wallet verificato. Tutti i wallet del catalogo possono essere testati in sandbox, inclusi gli schemi non disponibili nelle applicazioni di produzione. I tentativi simulati non vengono addebitati.", "example": "decline_document_expired" }, "sign": { "type": "object", "description": "Dati di input di Firma elettronica per questa sessione. I `documents` sono i documenti da firmare, per un workflow il cui passaggio di Firma elettronica riceve i documenti dalla sessione (`signature_documents_source` `session` o `both`): fino a 20 documenti e 50 MB in totale. `field_values` compila i campi il cui `prefill` è `api.`, sia sui documenti del workflow che su quelli della sessione. Creando nuovamente una sessione per gli stessi `workflow_id` e `vendor_data` viene restituita la sessione in sospeso; se tale chiamata invia `sign`, i relativi documenti, campi e valori devono essere identici a quelli iniziali, altrimenti qualsiasi differenza restituisce `400` con `{\"sign\": \"signature_document_changed\"}`. Consulta [Documenti di Firma elettronica](/it/sessions-api/create-session#documenti-di-firma-elettronica).", "properties": { "documents": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/SessionSignDocument" } }, "field_values": { "type": "object", "description": "Valori indicizzati dalla `` di ciascuna origine di precompilazione `api.`: stringhe da 1 a 500 caratteri per i campi `text` e `data`, booleani per una `checkbox`. `400` con `field_value_unknown` per una chiave non utilizzata da alcun campo, `field_value_missing` per un campo obbligatorio privo del relativo valore e `field_value_invalid` per un valore che non supera la validazione del rispettivo campo.", "additionalProperties": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "boolean" } ] }, "example": { "credit_limit": "3,000 EUR" } } } }, "user_state": { "type": "string", "maxLength": 16, "description": "Dove risiede la persona, se noto: un codice di suddivisione ISO 3166-2 (`US-IL`, `ES-M`) o un codice o nome di uno stato USA (`IL`, `Illinois`). Uno stato la cui legislazione richiede un consenso biometrico esplicito (Illinois, Texas, Colorado) fa sì che il flusso di verifica lo richieda prima di acquisire il volto, con trigger `declared_state`. Un valore non riconosciuto restituisce `400`. Consulta [Consenso biometrico](/it/getting-started/biometric-consent).", "example": "US-IL" }, "biometric_consent": { "type": "object", "description": "Consenso biometrico esplicito già raccolto dalla persona. Soddisfa il requisito, quindi il flusso di verifica non lo richiede nuovamente, e la decisione lo registra come `status: \"given\"` con trigger `customer_collected`. Una risposta già fornita dalla persona nel flusso non viene mai sostituita. Consulta [Consenso biometrico](/it/getting-started/biometric-consent).", "required": [ "given_at", "text_version" ], "properties": { "given_at": { "type": "string", "format": "date-time", "description": "Quando la persona ha fornito il consenso biometrico esplicito (ISO 8601). Non può essere nel futuro." }, "text_version": { "type": "string", "maxLength": 64, "description": "ID versione del testo del consenso accettato dalla persona, nei tuoi registri." } } } }, "example": { "workflow_id": "11111111-2222-3333-4444-555555555555", "vendor_data": "user-123", "callback": "https://example.com/verification/callback", "callback_method": "both", "metadata": { "user_type": "premium", "account_id": "ABC123" }, "language": "en", "contact_details": { "email": "john.doe@example.com", "send_notification_emails": true, "email_lang": "en", "phone": "+14155552671" }, "expected_details": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "id_country": "USA", "expected_document_types": [ "P", "ID" ] } } }, "examples": { "Create KYC session": { "summary": "Payload completo del percorso ideale per una sessione di Verifica degli utenti (KYC)", "description": "Chiamata di creazione realistica che utilizza tutti i campi impostati comunemente: selezione del workflow, collegamento del vendor, instradamento dei callback, metadati, impostazioni locali, precompilazione dei contatti e dettagli attesi dell'utente. Copia e incolla questo contenuto direttamente nell'esempio cURL precedente.", "value": { "workflow_id": "11111111-2222-3333-4444-555555555555", "vendor_data": "user-123", "callback": "https://example.com/verification/callback", "callback_method": "both", "metadata": { "user_type": "premium", "account_id": "ABC123" }, "language": "en", "contact_details": { "email": "john.doe@example.com", "send_notification_emails": true, "email_lang": "en", "phone": "+14155552671" }, "expected_details": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "nationality": "USA", "id_country": "USA", "expected_document_types": [ "P", "ID" ] } } }, "Create KYB session": { "summary": "Payload per il percorso ottimale di una sessione di Verifica aziendale (KYB)", "description": "Stessa struttura della chiamata KYC: il `workflow_id` è ciò che rende la sessione KYB. `vendor_data` fa generalmente riferimento all'azienda nel tuo sistema e `contact_details.email` è destinato al legale rappresentante che completerà il flusso. `expected_details` accetta i campi aziendali (`company_name`, `registry_country`, `registration_number`), che precompilano la ricerca nel registro delle imprese; i campi relativi alla persona e `contact_details.phone` vengono ignorati per i workflow KYB.", "value": { "workflow_id": "33333333-4444-5555-6666-777777777777", "vendor_data": "company-acme-001", "callback": "https://example.com/kyb/callback", "callback_method": "both", "metadata": { "tier": "enterprise", "company_id": "ACME-001" }, "expected_details": { "company_name": "Tesco PLC", "registry_country": "GB", "registration_number": "00445790" }, "language": "en", "contact_details": { "email": "legal-rep@acme.example.com", "send_notification_emails": true, "email_lang": "en" } } } } } } } } }, "/v3/session/imports/": { "post": { "summary": "Crea un job di importazione delle verifiche", "description": "Crea un job di importazione asincrono per sessioni storiche di Verifica degli utenti, sessioni di Verifica aziendale, record di monitoraggio delle transazioni o regole di stato personalizzate del workflow. Imposta `source=provider` per migrare da un altro provider: Didit legge Sumsub, Onfido, Persona e ComplyCube con la tua chiave di sola lettura, legge i record di Veriff, iDenfy e MetaMap tramite gli ID che carichi in `file`, e importa un file di esportazione nel formato di Didit per gli altri provider. Gli ID dei record sono associati a un namespace per provider (`sumsub:`), quindi una nuova esecuzione ignora tutto ciò che è già presente in Didit; inoltre, un record importato tramite file con l'ID semplice del provider viene riconosciuto in entrambe le direzioni, garantendo che il passaggio tra un'importazione da file e una migrazione da provider non importi mai un record due volte. Un'applicazione può eseguire fino a 4 job di importazione contemporaneamente; un job interrotto da un deploy o dal riavvio di un worker riprende automaticamente dall'ultima riga importata. Le importazioni sono disabilitate per impostazione predefinita e devono essere abilitate per organizzazione da Didit.", "operationId": "post_v3_session_imports_create", "x-didit-sdk": { "resource": "sessions.imports", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "import_type": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ], "default": "user_verification", "description": "Cosa importare: sessioni storiche di Verifica degli utenti, sessioni storiche di Verifica aziendale, regole di stato personalizzate del workflow o record storici di monitoraggio delle transazioni." }, "workflow_id": { "type": "string", "format": "uuid", "description": "UUID del workflow a cui collegare le sessioni importate o le regole di stato. Obbligatorio per user_verification, business_verification e status_rules. Omettere per transactions." }, "source_format": { "type": "string", "enum": [ "csv", "ndjson" ], "description": "Opzionale. Se omesso, viene dedotto dall'estensione del file caricato." }, "file": { "type": "string", "format": "binary", "description": "File canonico CSV o NDJSON. Usa NDJSON per importazioni di grandi dimensioni. Dimensione massima di caricamento 25 MB (usa `source_file_url` per file più grandi). È mutuamente esclusivo con `source_file_url`." }, "source_file_url": { "type": "string", "format": "uri", "description": "Alternativa al caricamento del file. Deve essere un URL HTTPS che punta a un indirizzo pubblico (le reti private/di loopback vengono rifiutate). Si esclude a vicenda con `file`." }, "source": { "type": "string", "enum": [ "file", "provider" ], "description": "`provider` indica una migrazione da un altro provider di verifica dell'identità. Ometti per un'importazione da file." }, "provider": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ], "description": "Origine della migrazione, da `GET /v3/session/imports/providers/`. Obbligatoria quando `source` è `provider`." }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "La chiave di sola lettura del provider, con i nomi dei campi elencati in `credential_fields`. Crittografata a riposo, mai restituita ed eliminata al termine dell'importazione. Inviala come stringa JSON in multipart." }, "options": { "type": "object", "properties": { "region": { "type": "string", "description": "La regione del provider, una delle sue `regions` (Onfido: `eu`, `us`, `ca`)." } } }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] }, "description": "Modifiche alla mappatura predefinita degli stati del provider: dallo stato di origine allo stato di Didit. `Not Finished` e `Abandoned` vengono ignorati e conteggiati, mai importati." }, "dry_run": { "type": "boolean", "default": false, "description": "Conta ciò che la migrazione importerebbe (per stato, già in Didit, stessa persona, non completato) senza scrivere nulla. Il job termina nello stato `READY`; avvialo con `POST /v3/session/imports/{importId}/start/`." }, "face_templates": { "type": "boolean", "default": false, "description": "Genera modelli biometrici dai selfie importati ed esegui la ricerca rispetto ai volti e alla blocklist dell'applicazione. Le corrispondenze vengono contrassegnate solo per la revisione. Richiede `lawful_basis_confirmed`." }, "lawful_basis_confirmed": { "type": "boolean", "default": false, "description": "Conferma che disponi di una base giuridica per condividere questi selfie con Didit in qualità di responsabile del trattamento." } } } }, "application/json": { "schema": { "type": "object", "required": [ "source_file_url" ], "properties": { "import_type": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ], "default": "user_verification", "description": "Cosa importare: sessioni storiche di Verifica degli utenti, sessioni storiche di Verifica aziendale, regole di stato personalizzate del workflow o record storici di monitoraggio delle transazioni." }, "workflow_id": { "type": "string", "format": "uuid", "description": "UUID del workflow a cui collegare le sessioni importate o le regole di stato. Obbligatorio per user_verification, business_verification e status_rules. Omettere per transactions." }, "source_format": { "type": "string", "enum": [ "csv", "ndjson" ], "description": "Opzionale. Se omesso, viene dedotto dall'estensione del file dell'URL." }, "source_file_url": { "type": "string", "format": "uri", "description": "Alternativa al caricamento del file. Deve essere un URL HTTPS che punta a un indirizzo pubblico (le reti private/di loopback vengono rifiutate). Si esclude a vicenda con `file`." }, "source": { "type": "string", "enum": [ "file", "provider" ], "description": "`provider` indica una migrazione da un altro provider di verifica dell'identità. Ometti per un'importazione da file." }, "provider": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ], "description": "Origine della migrazione, da `GET /v3/session/imports/providers/`. Obbligatoria quando `source` è `provider`." }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "La chiave di sola lettura del provider, con i nomi dei campi elencati in `credential_fields`. Crittografata a riposo, mai restituita ed eliminata al termine dell'importazione. Inviala come stringa JSON in multipart." }, "options": { "type": "object", "properties": { "region": { "type": "string", "description": "La regione del provider, una delle sue `regions` (Onfido: `eu`, `us`, `ca`)." } } }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] }, "description": "Modifiche alla mappatura predefinita degli stati del provider: dallo stato di origine allo stato di Didit. `Not Finished` e `Abandoned` vengono ignorati e conteggiati, mai importati." }, "dry_run": { "type": "boolean", "default": false, "description": "Conta ciò che la migrazione importerebbe (per stato, già in Didit, stessa persona, non completato) senza scrivere nulla. Il job termina nello stato `READY`; avvialo con `POST /v3/session/imports/{importId}/start/`." }, "face_templates": { "type": "boolean", "default": false, "description": "Genera modelli biometrici dai selfie importati ed esegui la ricerca rispetto ai volti e alla blocklist dell'applicazione. Le corrispondenze vengono contrassegnate solo per la revisione. Richiede `lawful_basis_confirmed`." }, "lawful_basis_confirmed": { "type": "boolean", "default": false, "description": "Conferma che disponi di una base giuridica per condividere questi selfie con Didit in qualità di responsabile del trattamento." } } }, "examples": { "URL-based import": { "value": { "import_type": "user_verification", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "source_file_url": "https://files.example.com/exports/sessions.ndjson" } } } } } }, "responses": { "201": { "description": "Processo di importazione accettato. Effettua il polling dello `uuid` restituito fino a quando lo `status` non è `COMPLETED` o `FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" }, "examples": { "Job accepted": { "value": { "uuid": "3f9c1a2b-4d5e-4f60-8a7b-9c0d1e2f3a4b", "status": "PENDING", "import_type": "user_verification", "source_format": "ndjson", "source_filename": "sessions.ndjson", "total_rows": 0, "processed_rows": 0, "checkpoint_row": 0, "created_count": 0, "updated_count": 0, "skipped_count": 0, "failed_count": 0, "total_media_bytes": 0, "last_error": null, "created_at": "2026-05-17T08:42:11Z", "updated_at": "2026-05-17T08:42:11Z", "started_at": null, "completed_at": null } } } } } }, "400": { "description": "Workflow, tipo di file, dimensione del file, URL di origine o combinazione di selettori non validi. Una migrazione la cui chiave viene rifiutata dal provider restituisce `code` (`invalid_credentials`, `missing_permission`, `wrong_region`, `provider_unavailable`, `rate_limited`, `ids_required`, `record_not_found`), `missing_permissions` e `suggested_region`.", "content": { "application/json": { "examples": { "Invalid workflow": { "value": { "workflow_id": [ "Invalid workflow_id." ] } }, "Workflow required": { "value": { "workflow_id": [ "This field is required for this import type." ] } }, "Wrong file type": { "value": { "file": [ "Only CSV and NDJSON files are supported." ] } }, "File too large": { "value": { "file": [ "Import file exceeds the maximum allowed size." ] } }, "No source": { "value": { "file": [ "Upload a file or provide source_file_url." ] } }, "Both sources": { "value": { "file": [ "Use either file or source_file_url, not both." ] } } } } } }, "403": { "description": "Importazioni non abilitate, applicazione sandbox o chiave API mancante (una chiave errata, revocata o scaduta riceve `401`). Le importazioni di verifiche sono disabilitate per impostazione predefinita e devono essere abilitate da Didit per ogni organizzazione.", "content": { "application/json": { "examples": { "Imports not enabled": { "value": { "detail": "Verification imports are not enabled for this organization." } }, "Sandbox": { "value": { "detail": "Verification imports are not enabled for sandbox applications." } }, "Bad API key": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "L'applicazione ha già 4 job di importazione attivi (PENDING/PROCESSING/PAUSED), il numero massimo eseguibile contemporaneamente. Attendi che uno termini prima di avviarne un altro.", "content": { "application/json": { "examples": { "Active job": { "value": { "detail": "This application already has 4 active import jobs, the most it can run at once. Wait for one to finish before starting another." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.create(\n import_type=\"user_verification\",\n workflow_id=\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n source_file_url=\"https://files.example.com/exports/sessions.ndjson\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.create({\n import_type: \"user_verification\",\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n source_file_url: \"https://files.example.com/exports/sessions.ndjson\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Create(ctx, didit.SessionsImportsCreateParams{\n\tImportType: didit.Some(didit.SessionsImportsCreateParamsImportType(\"user_verification\")),\n\tWorkflowID: didit.String(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\"),\n\tSourceFileURL: didit.String(\"https://files.example.com/exports/sessions.ndjson\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsImportsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().create(SessionsImportsCreateParams.builder()\n .importType(SessionsImportsCreateParams.ImportType.of(\"user_verification\"))\n .workflowId(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\")\n .sourceFileUrl(\"https://files.example.com/exports/sessions.ndjson\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->create([\n 'import_type' => 'user_verification',\n 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab',\n 'source_file_url' => 'https://files.example.com/exports/sessions.ndjson',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.create(\n import_type: \"user_verification\",\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n source_file_url: \"https://files.example.com/exports/sessions.ndjson\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.CreateAsync(new SessionsImportsCreateParams\n{\n ImportType = new SessionsImportsCreateParamsImportType(\"user_verification\"),\n WorkflowId = \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n SourceFileUrl = \"https://files.example.com/exports/sessions.ndjson\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/template/": { "get": { "summary": "Scarica il modello di importazione delle verifiche", "description": "Scarica l'intestazione CSV canonica per le importazioni di verifica. L'insieme delle colonne è determinato da `import_type`. La prima colonna dei modelli di sessione è la chiave di idempotenza `external_id`.", "operationId": "get_v3_session_imports_template", "x-didit-sdk": { "resource": "sessions.imports", "method": "retrieve_template", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "import_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ], "default": "user_verification" } } ], "responses": { "200": { "description": "File di modello CSV.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può scaricare i modelli di importazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "summary": "Chiave API mancante, non valida o revocata", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.imports.retrieve_template()\nwith open(\"download.csv\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.imports.retrieveTemplate();\nawait writeFile(\"download.csv\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Imports.RetrieveTemplate(ctx, didit.SessionsImportsRetrieveTemplateParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.csv\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().imports().retrieveTemplate()\n .writeTo(Path.of(\"download.csv\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->retrieveTemplate();\n$content->saveTo('download.csv');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.imports.retrieve_template\nFile.binwrite(\"download.csv\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Imports.RetrieveTemplateAsync();\nawait content.SaveToAsync(\"download.csv\");" } ] } }, "/v3/session/imports/{importId}/": { "get": { "summary": "Recupera un job di importazione delle verifiche", "description": "Recupera i contatori di avanzamento dell'importazione e lo stato finale di un job. Esegui il polling finché `status` non è `COMPLETED` o `FAILED`; `failed_count` > 0 indica che alcune righe sono state rifiutate — elencale tramite l'endpoint degli errori.", "operationId": "get_v3_session_imports_retrieve", "x-didit-sdk": { "resource": "sessions.imports", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Stato del processo di importazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "404": { "description": "Processo di importazione non trovato per questa applicazione.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può leggere i job di importazione per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "summary": "Chiave API mancante, non valida o revocata", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/errors/": { "get": { "summary": "Elenca gli errori delle righe di importazione delle verifiche", "description": "Elenca gli errori a livello di riga per un processo di importazione di verifiche, ordinati per `row_number`. Usa questo endpoint per generare un file corretto per un nuovo tentativo contenente solo le righe non riuscite.", "operationId": "get_v3_session_imports_errors", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_errors", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Dimensione della pagina. Se omessa, il valore predefinito è 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Offset in base zero del primo record da restituire." } ], "responses": { "200": { "description": "Errori di riga impaginati.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero di righe di errore: esatto fino a 100, con limite massimo di 100 oltre tale soglia. Fai affidamento sul fatto che `next` sia `null` per rilevare l'ultima pagina." }, "next": { "type": "string", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SessionImportError" } } } }, "examples": { "Row errors": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "row_number": 17, "external_id": "ext-000017", "error": "status: invalid value 'unknown_status'", "raw_row": { "external_id": "ext-000017", "status": "unknown_status", "first_name": "Jane" }, "created_at": "2026-05-17T08:44:02Z" } ] } } } } } }, "404": { "description": "Processo di importazione non trovato per questa applicazione.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può leggere i job di importazione per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "summary": "Chiave API mancante, non valida o revocata", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.imports.list_errors(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.imports.listErrors(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.Imports.ListErrorsAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsImportsListErrorsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().imports().listErrors(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listErrors('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.imports.list_errors(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.Imports.ListErrorsAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/decision/": { "get": { "summary": "Recupera la decisione completa per una sessione di verifica", "description": "Recupera il report completo della decisione per una sessione di verifica: lo `status` complessivo della sessione più un report per ogni funzionalità di verifica eseguita dal workflow. Questo è l'endpoint canonico di lettura sia per le sessioni di Verifica degli utenti (KYC) sia per quelle di Verifica aziendale (KYB): lo stesso percorso gestisce entrambe, e il discriminatore di primo livello `session_kind` indica quale struttura hai ricevuto (`\"user\"` o `\"business\"`).\n\n**Ogni report di funzionalità è un array con nome al plurale.** I workflow V3 sono grafi che possono eseguire la stessa funzionalità più di una volta, quindi ciascun blocco (`id_verifications`, `nfc_verifications`, `liveness_checks`, `face_matches`, `poa_verifications`, `document_ai_documents`, `phone_verifications`, `email_verifications`, `aml_screenings`, `ip_analyses`, `database_validations`, `questionnaire_responses`) è un array JSON i cui elementi contengono ciascuno un `node_id` che identifica il nodo del grafo del workflow che li ha prodotti. Leggi NFC come `response.nfc_verifications[0]`, mai come campo singolare `nfc`. Un blocco è `null` finché il workflow non ha eseguito quella funzionalità almeno una volta; le funzionalità non incluse nel workflow non compaiono mai con dati. I risultati della Firma elettronica si trovano in `signatures`, presente solo quando il workflow include un passaggio di Firma elettronica.\n\n**Quando chiamare.** Il pattern consigliato è basato su eventi: attendi il webhook `status.updated` che viene attivato quando la sessione raggiunge una decisione (`Approved`, `Declined`, `In Review`), quindi chiama questo endpoint una volta per recuperare il report completo. Anche il polling funziona (l'endpoint può essere chiamato in qualsiasi momento del ciclo di vita della sessione e restituisce i dati prodotti fino a quel punto), ma l'approccio basato su webhook e successivo recupero è più economico e veloce. Gli URL dei file multimediali nella risposta (immagini di documenti, video, PDF) sono link pre-firmati di breve durata: scaricali tempestivamente o richiedi nuovamente la decisione per ottenerne di nuovi, e non memorizzarli come riferimenti a lungo termine.\n\n**Stati.** Lo `status` di primo livello è lo stato del ciclo di vita della sessione (`Not Started`, `In Progress`, `Awaiting User`, `In Review`, `Approved`, `Declined`, `Resubmitted`, `Expired`, `Kyc Expired`, `Abandoned`). Ogni elemento della funzionalità include inoltre il proprio `status` a livello di funzionalità (`Not Finished`, `Approved`, `Declined`, `In Review`, ...). Una sessione può essere complessivamente `Approved` mentre una singola funzionalità è `In Review`, a seconda delle regole decisionali del workflow.\n\n**Autenticazione e visibilità.** Esegui l'autenticazione con la chiave API dell'applicazione nell'intestazione `x-api-key` (funziona anche un token Bearer di un utente della console con l'autorizzazione `read:sessions`). Sono visibili solo le sessioni di proprietà dell'applicazione autenticata. Se il tuo workflow limita gli attributi di risposta, i campi non consentiti all'interno degli elementi delle funzionalità vengono restituiti come `null`, mentre `status`, `warnings` e `node_id` vengono sempre conservati.\n\n**Limiti di frequenza.** Le richieste GET sono limitate a 600 al minuto per chiave API. Il superamento del limite restituisce `429` con le intestazioni `Retry-After` e `X-RateLimit-*`.", "operationId": "get_v3_session_decision", "x-didit-sdk": { "resource": "sessions", "method": "retrieve_decision", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "Report di decisione completo. `session_kind` distingue le due strutture: le sessioni `user` contengono gli array di funzionalità KYC mostrati di seguito; le sessioni `business` contengono invece `registry_checks`, `document_verifications` e `key_people_checks` insieme agli array condivisi. Gli array delle funzionalità sono `null` finché il workflow non ha eseguito tale funzionalità; gli URL dei contenuti multimediali sono link pre-firmati di breve durata.", "content": { "application/json": { "examples": { "Example": { "summary": "Esempio completo", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "session_kind": "user", "session_number": 43762, "session_url": "https://verify.didit.me/session/11111111-2222-3333-4444-555555555555", "status": "In Review", "environment": "live", "workflow_id": "11111111-2222-3333-4444-555555555555", "features": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACE_MATCH", "POA", "PHONE", "DATABASE_VALIDATION", "AML", "IP_ANALYSIS" ], "vendor_data": "11111111-1111-1111-1111-111111111111", "metadata": { "user_type": "premium", "account_id": "ABC123" }, "expected_details": { "first_name": "Carmen", "last_name": "Española Española" }, "contact_details": { "email": "carmen@example.com", "email_lang": "es", "send_notification_emails": false, "phone": null }, "callback": "https://verify.didit.me/", "id_verifications": [ { "node_id": "feature_ocr_1", "status": "Approved", "document_type": "Identity Card", "document_subtype": "ID_CARD_GENERIC", "document_number": "CAA000000", "personal_number": "99999999R", "portrait_image": "https:///portrait.jpg", "front_image": "https:///front.jpg", "front_video": "https:///front.mp4", "back_image": "https:///back.jpg", "back_video": "https:///back.mp4", "full_front_image": "https:///full_front.jpg", "full_back_image": "https:///full_back.jpg", "front_image_camera_front": "https:///front_camera_front.jpg", "back_image_camera_front": "https:///back_camera_front.jpg", "date_of_birth": "1980-01-01", "age": 45, "expiration_date": "2031-06-02", "date_of_issue": "2021-06-02", "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "Carmen", "last_name": "Española Española", "full_name": "Carmen Española Española", "gender": "F", "address": "Avda de Madrid 34, Madrid, Madrid", "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain", "place_of_birth": "Madrid", "marital_status": "Single", "nationality": "ESP", "extra_fields": { "dl_categories": [], "blood_group": null }, "mrz": { "surname": "ESPANOLA ESPANOLA", "name": "CARMEN", "country": "ESP", "nationality": "ESP", "birth_date": "800101", "expiry_date": "310602", "sex": "F", "document_type": "ID", "document_number": "CAA000000", "optional_data": "99999999R", "optional_data_2": "", "birth_date_hash": "4", "expiry_date_hash": "8", "document_number_hash": "4", "final_hash": "1", "personal_number": "99999999R", "warnings": [], "errors": [], "mrz_type": "TD1", "mrz_string": "IDESPCAA000000499999999R<<<<<<\n8001014F3106028ESP<<<<<<<<<<<1\nESPANOLA/match_face.jpg", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null, "source": "session" } ], "front_image_quality_score": { "focus_score": 85.3, "brightness_score": 92.1, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 72.4, "overall_score": 88.7 }, "back_image_quality_score": { "focus_score": 79.1, "brightness_score": 90.5, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 72.4, "overall_score": 85.2 }, "extra_files": [ "https:///extra_id_verification.jpg" ], "matches": [ { "session_id": "7d4f1f60-9c2e-4b8a-8f3d-2a1b5c6d7e8f", "session_number": 1234, "vendor_data": "user_ref_001", "verification_date": "2024-06-15T10:30:00Z", "user_details": { "name": "John Smith", "document_type": "ID", "document_number": "CLM148418" }, "status": "Approved", "is_blocklisted": false, "api_service": null, "front_image_url": "https:///document_front.jpg" }, { "session_id": "b2c8e4d1-6a3f-4e7b-95c0-1d8f2a6b4c9e", "session_number": 1235, "vendor_data": null, "verification_date": "2024-05-20T14:45:00Z", "user_details": { "name": "John Smith", "document_type": "ID", "document_number": "CLM148418" }, "status": "Declined", "is_blocklisted": true, "api_service": "ID_VERIFICATION", "front_image_url": "https:///document_front_2.jpg" } ], "warnings": [ { "feature": "ID_VERIFICATION", "risk": "QR_NOT_DETECTED", "additional_data": null, "log_type": "information", "short_description": "QR not detected", "long_description": "The system couldn't find or read the QR code on the document, which is necessary for document verification. This could be due to poor image quality or an unsupported document type.", "node_id": "feature_ocr_1" } ], "verification_method": "document", "assurance": "documentary", "wallet_provider": null, "fallback_from": null, "id_lookup": null, "wallet_verification": null, "document_liveness": { "portrait_replace": { "score": 96.46, "front": 96.46, "back": 98.2, "decline_threshold": 35, "review_threshold": 70, "bucket": "approve" }, "printed_copy": { "score": 91.2, "front": 91.2, "back": 93.7, "decline_threshold": 35, "review_threshold": 77, "bucket": "approve" }, "screen_replay": { "score": 99.9, "front": 99.9, "back": 99.5, "decline_threshold": 30, "review_threshold": 70, "bucket": "approve" } } }, { "node_id": "feature_ocr_2", "status": "Approved", "issuing_state": "ZAF", "issuing_state_name": "South Africa", "first_name": "Thabo", "last_name": "Mokoena", "full_name": "Thabo Mokoena", "date_of_birth": "1991-06-15", "personal_number": "9106155043088", "verification_method": "id_lookup", "assurance": "data_match", "wallet_provider": null, "fallback_from": null, "id_lookup": { "source": "Department of Home Affairs", "checked_at": "2026-09-04T09:12:44Z", "attempts": 1, "max_attempts": 2, "outcome": "match", "comparison": [ { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" }, { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" }, { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" } ], "registry_portrait": "https:///registry_portrait.jpg", "face_match_score": 96.4, "source_errors": [] }, "wallet_verification": null, "warnings": [] }, { "node_id": "feature_ocr_3", "status": "Approved", "issuing_state": "DNK", "issuing_state_name": "Denmark", "first_name": "Freja", "last_name": "Nielsen", "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "verification_method": "wallet", "assurance": "cryptographic", "wallet_provider": "mitid", "fallback_from": null, "id_lookup": null, "wallet_verification": { "provider": "mitid", "provider_name": "MitID", "issuing_authority": "Danish Agency for Digital Government", "issuing_country": "DNK", "credential_type": "person_identification", "level_of_assurance": "substantial", "verified_at": "2026-09-04T09:12:44Z", "signature_valid": true, "attributes": { "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678" }, "portrait": null, "face_match_score": null }, "warnings": [] } ], "nfc_verifications": [ { "node_id": "feature_nfc_1", "status": "In Review", "is_nfc_skipped": false, "skip_reason": null, "chip_protocol": "icao", "jpki": null, "portrait_image": "https:///portrait.jpg", "signature_image": "https:///signature.jpg", "chip_data": { "document_type": "ID", "issuing_country": "ESP", "document_number": "123456789", "expiration_date": "2030-01-01", "first_name": "John", "last_name": "Smith", "birth_date": "1990-05-15", "gender": "M", "nationality": "ESP", "address": "CALLE MAYOR 123 4B, MADRID, MADRID", "place_of_birth": "MADRID, MADRID" }, "authenticity": { "sod_integrity": true, "dg_integrity": true }, "certificate_summary": { "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES", "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES", "serial_number": "118120836164494130086420187336801405660", "not_valid_after": "2031-02-18 10:21:11", "not_valid_before": "2020-11-18 10:21:11" }, "warnings": [ { "feature": "NFC", "risk": "DATA_INCONSISTENT", "additional_data": null, "log_type": "warning", "short_description": "OCR and NFC mrz code extracted are not the same", "long_description": "The Optical Character Recognition (OCR) data and the NFC chip data don't match, indicating potential document tampering or data inconsistency.", "node_id": "feature_nfc_1" } ] } ], "liveness_checks": [ { "node_id": "feature_liveness_1", "status": "Approved", "method": "ACTIVE_3D", "score": 89.92, "reference_image": "https:///reference.jpg", "video_url": "https:///video.mp4", "age_estimation": 24.3, "matches": [ { "session_id": "7d4f1f60-9c2e-4b8a-8f3d-2a1b5c6d7e8f", "session_number": 1234, "vendor_data": "user_ref_001", "verification_date": "2024-06-15T10:30:00Z", "user_details": { "full_name": "John Smith", "document_type": "ID", "document_number": "CLM148418" }, "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null, "source": "session", "match_image_url": "https:///face_match.jpg", "similarity_percentage": 98.5 }, { "session_id": "3e9a7c21-5b48-4f0e-9c6a-8d2f4b1e0a35", "session_number": 1100, "vendor_data": "customer_xyz", "verification_date": "2024-04-10T09:15:00Z", "user_details": { "full_name": "John Smith", "document_type": "P", "document_number": "DZ8375806" }, "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": "PASSIVE_LIVENESS", "source": "session", "match_image_url": "https:///face_match_2.jpg", "similarity_percentage": 95.2 } ], "warnings": [ { "feature": "LIVENESS", "risk": "LOW_LIVENESS_SCORE", "additional_data": null, "log_type": "information", "short_description": "Low liveness score", "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.", "node_id": "feature_liveness_1" } ], "face_quality": null, "face_luminance": null } ], "face_matches": [ { "node_id": "feature_face_match_1", "status": "In Review", "score": 65.43, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///target-image.jpg", "warnings": [ { "feature": "FACEMATCH", "risk": "LOW_FACE_MATCH_SIMILARITY", "additional_data": null, "log_type": "warning", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.", "node_id": "feature_face_match_1" } ] } ], "phone_verifications": [ { "node_id": "feature_phone_1", "status": "Approved", "phone_number_prefix": "+34", "phone_number": "600600600", "full_number": "+34600600600", "country_code": "ES", "country_name": "Spain", "carrier": { "name": "Orange", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "sms", "verification_attempts": 1, "verified_at": "2024-07-28T06:47:35.654321Z", "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-08-24T09:12:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" }, "fee": 0.1 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-08-24T09:12:39.662157+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2025-08-24T09:12:39.684292+00:00", "details": null, "fee": 0 } ], "warnings": [], "matches": [ { "session_id": null, "session_number": null, "vendor_data": null, "verification_date": null, "phone_number": "+34600000000", "status": null, "is_blocklisted": true, "api_service": null, "source": "list_entry" } ] } ], "email_verifications": [ { "node_id": "feature_email_1", "status": "Approved", "email": "test@example.com", "is_breached": true, "breaches": [ { "name": "TAPAirPortugal", "domain": "flytap.com", "logo_path": "https://logos.example.com/TAPAirPortugal.png", "breach_date": "2022-08-25", "description": "In August 2022, the Portuguese airline TAP Air Portugal was the target of a ransomware attack perpetrated by the Ragnar Locker gang who later leaked the compromised data via a public dark web site. Over 5M unique email addresses were exposed alongside other personal data including names, genders, DoBs, phone numbers and physical addresses.", "is_verified": true, "data_classes": [ "dates_of_birth", "email_addresses", "genders", "names", "nationalities", "phone_numbers", "physical_addresses", "salutations", "spoken_languages" ], "breach_emails_count": 6083479 } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2025-09-15T17:36:19.963451Z", "warnings": [ { "feature": "EMAIL", "risk": "BREACHED_EMAIL_DETECTED", "additional_data": null, "log_type": "information", "short_description": "Breached email detected", "long_description": "This email address was found in one or more known data breaches.", "node_id": "feature_email_1" } ], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-09-15T17:36:19.792684+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-09-15T17:36:19.963427+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_DECLINED", "timestamp": "2025-09-15T17:36:20.081471+00:00", "details": { "reason": "BREACHED_EMAIL_DETECTED" }, "fee": 0 } ], "matches": [ { "session_id": null, "session_number": null, "vendor_data": null, "verification_date": null, "email": "test@example.com", "status": null, "is_blocklisted": true, "api_service": null, "source": "list_entry" } ] } ], "poa_verifications": [ { "node_id": "feature_poa_1", "status": "Declined", "document_file": "https:///poa_document.pdf", "issuing_state": "AR", "document_type": "UTILITY_BILL", "document_subtype": null, "document_language": "es", "document_metadata": { "file_size": 1000, "content_type": "application/pdf", "creation_date": "2021-01-01", "modified_date": "2021-01-01", "overlay_manipulation": null, "creator": null, "producer": "PDF Generator", "software": null, "encryption": null, "is_signed": false, "is_tampered": false, "signature_info": null, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": true }, "issuer": "Aguas del Norte", "issue_date": "2021-02-01", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 3396, SALTA", "poa_formatted_address": "Av. Monseñor Tavella 3396, A4400 Salta, Argentina", "poa_parsed_address": { "address_type": "Avenida", "street_1": "Avenida Monseñor Tavella 3396", "street_2": null, "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208664, "longitude": -65.4131 } }, "name_on_document": "Fernando De Lima", "name_match_score_expected_details": null, "name_match_score_id_verification": 38.5, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": {}, "extra_fields": { "bank_account_number": "1234567890", "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": "+5491112345678", "additional_names": [] }, "extra_files": [ "https:///extra_poa.pdf" ], "detected_codes": [ { "type": "QR_CODE", "page_number": 1, "position": [ [ 820, 1120 ], [ 1002, 1120 ], [ 1002, 1302 ], [ 820, 1302 ] ], "x": 820, "y": 1120, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==", "parsed_payload": "https://aguasdelnorte.com/factura/998811" }, { "type": "CODE_128", "page_number": 1, "position": [ [ 112, 1480 ], [ 560, 1480 ], [ 560, 1540 ], [ 112, 1540 ] ], "x": 112, "y": 1480, "width": 448, "height": 60, "page_width": 1190, "page_height": 1684, "raw_payload": "MDA5OTg4MTEwMDA0Mg==", "parsed_payload": "0099881100042" } ], "warnings": [] } ], "document_ai_documents": [ { "status": "Approved", "node_id": "feature_document_ai_1", "items": [ { "uuid": "c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071", "node_id": "feature_document_ai_1", "document_key": "proof_of_funds", "original_filename": "bank_statement.pdf", "file_size": 184320, "file_url": "https:///document_ai/proof_of_funds.pdf", "status": "Approved", "extracted_data": { "account_holder": "John Doe", "balance": 15230.55, "currency": "EUR", "statement_date": "2026-05-31" }, "detected_codes": [ { "type": "QR_CODE", "page_number": 2, "position": [ [ 124, 86 ], [ 306, 86 ], [ 306, 268 ], [ 124, 268 ] ], "x": 124, "y": 86, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "SU5WLTIwMjYtMDA0Mg==", "parsed_payload": "INV-2026-0042" } ], "fields": [ { "key": "account_holder", "name": "Account holder", "instruction": "Extract the full name of the account holder.", "type": "text", "required": true }, { "key": "balance", "name": "Closing balance", "instruction": "Extract the closing balance amount.", "type": "number", "required": true } ], "document_metadata": { "is_tampered": false }, "cross_check_result": null, "created_at": "2026-06-01T12:34:56Z" } ], "warnings": [] } ], "questionnaire_responses": [ { "node_id": "feature_questionnaire_1", "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213", "title": "Source of Funds", "description": "Reply to this questionnaire to help us understand the source of funds.", "languages": [ "en" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60", "version": 1, "published_at": "2025-11-02T09:14:55.000000Z", "sections": [ { "title": null, "description": null, "items": [ { "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db", "value": "question_1", "element_type": "DROPDOWN", "is_required": true, "title": "What is your primary source of funds?", "description": null, "placeholder": null, "choices": [ { "label": "Salary", "value": "salary" }, { "label": "Business Income", "value": "business_income" }, { "label": "Savings", "value": "savings" }, { "label": "Investments", "value": "investments" }, { "label": "Sale of Asset", "value": "sale_of_asset" }, { "label": "Inheritance/Gift", "value": "inheritance_gift" }, { "label": "Pension", "value": "pension" }, { "label": "Crypto Proceeds", "value": "crypto_proceeds" }, { "label": "Other", "value": "other", "requires_text_input": true } ], "max_files": 1, "answer": { "value": "salary" }, "required_if": null, "repeatable_config": null }, { "uuid": "2d16b527-72be-42e0-8e96-b164b818386c", "value": "question_2", "element_type": "LONG_TEXT", "is_required": true, "title": "Provide details of the primary source.", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null }, { "uuid": "a9239b7c-fbfb-4ea7-b7e4-c835cd4016e0", "value": "question_3", "element_type": "DROPDOWN", "is_required": true, "title": "What is your annual income range (pre-tax)?", "description": null, "placeholder": null, "choices": [ { "label": "Less than $25,000", "value": "<25k" }, { "label": "$25,000 - $50,000", "value": "25k-50k" }, { "label": "$50,001 - $100,000", "value": "50k-100k" }, { "label": "$100,001 - $250,000", "value": "100k-250k" }, { "label": "More than $250,000", "value": ">250k" } ], "max_files": 1, "answer": { "value": "<25k" }, "required_if": null, "repeatable_config": null }, { "uuid": "93dede62-6d0c-4a7f-934d-42175eb94011", "value": "question_4", "element_type": "DROPDOWN", "is_required": true, "title": "What is your approximate net worth (range)?", "description": null, "placeholder": null, "choices": [ { "label": "Less than $50,000", "value": "<50k" }, { "label": "$50,000 - $250,000", "value": "50k-250k" }, { "label": "$250,001 - $1,000,000", "value": "250k-1m" }, { "label": "$1,000,001 - $5,000,000", "value": "1m-5m" }, { "label": "More than $5,000,000", "value": ">5m" } ], "max_files": 1, "answer": { "value": "<50k" }, "required_if": null, "repeatable_config": null }, { "uuid": "2af60d6f-6961-4692-9ee7-24b3033610a6", "value": "question_5", "element_type": "LONG_TEXT", "is_required": true, "title": "For your initial deposit/funding, indicate the exact source and amount.", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null }, { "uuid": "0ad9d1aa-736f-46cf-947b-9e1241b53e40", "value": "question_6", "element_type": "LONG_TEXT", "is_required": true, "title": "Breakdown of sources by percentage.", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null }, { "uuid": "1bf8a2a3-14ee-48a8-bb3d-175481aae4aa", "value": "question_7", "element_type": "SINGLE_CHOICE", "is_required": true, "title": "Will any funds originate from third parties? If yes, please provide details.", "description": null, "placeholder": null, "choices": [ { "label": "Yes", "value": "yes", "requires_text_input": true }, { "label": "No", "value": "no" } ], "max_files": 1, "answer": { "text": "Additional details", "value": "yes" }, "required_if": null, "repeatable_config": null }, { "uuid": "e18d4dd3-b7bf-4883-ba18-d6046adbe313", "value": "question_8", "element_type": "SINGLE_CHOICE", "is_required": true, "title": "Do you hold or plan to use virtual assets (e.g., crypto) to fund this account? If yes, please provide details.", "description": null, "placeholder": null, "choices": [ { "label": "Yes", "value": "yes", "requires_text_input": true }, { "label": "No", "value": "no" } ], "max_files": 1, "answer": { "text": "Additional details", "value": "yes" }, "required_if": null, "repeatable_config": null }, { "uuid": "a90a073d-e098-404c-bbce-5130d8b12a13", "value": "question_9", "element_type": "FILE_UPLOAD", "is_required": true, "title": "Upload a proof of funds document", "description": "You can upload your three (3) most recent bank statements, three (3) most recent payslips, your most recent tax return, proof of company ownership, trading exchange statement, sale of property, or proof of inheritance.", "placeholder": null, "choices": null, "max_files": 3, "answer": { "files": [ "/media/ocr/", "/media/ocr/" ] }, "required_if": null, "repeatable_config": null }, { "uuid": "9503b486-7cb8-4c3b-a97d-4b64926a5a47", "value": "question_10", "element_type": "LONG_TEXT", "is_required": false, "title": "Would you like to add any details to help us expedite our review of the documents you submitted?", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null } ] } ], "status": "Approved" } ], "aml_screenings": [ { "node_id": "feature_aml_1", "status": "In Review", "total_hits": 1, "entity_type": "person", "hits": [ { "id": "hit_7c1e9a40b2d35f86e0a4c912", "url": "https://news.example.org/articles/sample", "match": false, "score": 0.73, "target": null, "caption": "Javier Ejemplo Modelo", "datasets": [ "PEP" ], "features": null, "rca_name": "", "last_seen": "2025-06-13T00:00:00", "risk_view": { "crimes": { "score": 0, "weightage": 20, "risk_level": "Low", "risk_scores": {} }, "countries": { "score": 0, "weightage": 30, "risk_level": "Low", "risk_scores": {} }, "categories": { "score": 100, "weightage": 50, "risk_level": "High", "risk_scores": { "PEP": 100 } }, "custom_list": {} }, "first_seen": "2025-01-18T00:00:00", "properties": { "name": [ "Javier Ejemplo Modelo" ], "alias": [ "Javier Ejemplo Modelo", "David Azagra" ], "notes": [ "Spanish orchestra conductor" ], "title": null, "gender": [ "male" ], "height": null, "topics": null, "weight": null, "address": null, "country": null, "website": null, "eyeColor": null, "keywords": null, "lastName": [ "Ejemplo", "Modelo" ], "position": null, "religion": null, "birthDate": [ "1974" ], "education": [ "Tokyo Arts and Space (2012-2012)", "Saint Petersburg Conservatory (-2010)", "Comillas Pontifical University" ], "ethnicity": null, "firstName": [ "David" ], "hairColor": null, "weakAlias": null, "birthPlace": [ "Madrid" ], "modifiedAt": null, "wikidataId": null, "citizenship": null, "nationality": null }, "match_score": 98, "risk_score": 73, "review_status": "Unreviewed", "score_breakdown": { "name_score": 95, "name_weight": 60, "name_weight_normalized": 70.59, "name_contribution": 67.06, "dob_score": 100, "dob_weight": 25, "dob_weight_normalized": 29.41, "dob_contribution": 29.41, "country_score": 0, "country_weight": 15, "country_weight_normalized": 0, "country_contribution": 0, "document_number_match_type": "NEUTRAL", "document_number_effect": "No document number provided for screening", "total_score": 98 }, "pep_matches": [ { "aliases": [ "Javier Ejemplo Modelo", "David Azagra" ], "education": [ "Tokyo Arts and Space (2012-2012)", "Saint Petersburg Conservatory (-2010)", "Comillas Pontifical University" ], "list_name": "Wikidata", "publisher": "Wikidata", "source_url": "https://news.example.org/articles/sample", "description": "Wikidata is the structured data project of the Wikipedia community, providing fact-based information edited by humans and machines", "matched_name": "Javier Ejemplo Modelo", "pep_position": "", "date_of_birth": "1974", "other_sources": [], "place_of_birth": "Madrid" } ], "linked_entities": [ { "name": [ "Antonio Ejemplo" ], "active": [], "status": [], "details": [], "relation": [] } ], "warning_matches": [], "sanction_matches": [], "adverse_media_details": { "sentiment": "Moderately Negative", "entity_type": "person", "sentiment_score": -2, "adverse_keywords": { "fraud": 3, "juicio": 1, "delitos": 2, "imputado": 1, "impunidad": 1, "corruption": 2, "favoritism": 2, "privilegio": 1, "corrupción": 1, "persecution": 2, "desconfianza": 1, "desprestigio": 1, "fraude de ley": 2, "manipulación": 1, "investigación": 3, "prevaricación": 8, "trato de favor": 1, "irregularidades": 2, "crisis de confianza": 1, "tráfico de influencias": 8 } }, "adverse_media_matches": [ { "country": "spain", "summary": "Javier Ejemplo is implicated in legal violations related to favoritism and influence trafficking, leading to a negative portrayal in the article.", "headline": "La Diputación de Villaejemplo consolida la plaza a medida para el ex asesor de Moncloa amigo del \"hermanito\" de Ejemplo", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "fraud", "prevaricación", "tráfico de influencias", "irregularidades", "imputado" ], "sentiment_score": -2, "publication_date": "2025-06-10T20:46:38" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in legal issues regarding favoritism and corruption, leading to a negative portrayal in the article.", "headline": "La Diputación de Villaejemplo consolida la plaza a medida para el ex asesor de Moncloa amigo del \"hermanito\" de Ejemplo", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "fraud", "prevaricación", "tráfico de influencias", "irregularidades", "trato de favor" ], "sentiment_score": -2, "publication_date": "2025-06-10T20:46:38" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is mentioned in connection with Carlos Ficticio's corruption case, indicating his involvement in alleged influence peddling.", "headline": "España, paraíso del aforado", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "corrupción", "impunidad", "privilegio", "desconfianza", "manipulación", "fraude de ley" ], "sentiment_score": -2, "publication_date": "2025-06-10T05:05:34" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is implicated in the same investigation as Ficticio, which raises questions about his conduct and political ethics.", "headline": "Aforamientos: esa figura incómoda", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "investigación", "juicio", "fraude de ley", "desprestigio", "crisis de confianza", "delitos" ], "sentiment_score": -2, "publication_date": "2025-06-08T06:01:00" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in a legal investigation regarding irregularities in his hiring, which raises serious concerns about his conduct.", "headline": "La jueza del 'caso Javier Ejemplo' denuncia un «fraude de ley» en el aforamiento de Ficticio (Partido Ejemplo)", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "fraud", "irregularities", "prevaricación", "tráfico de influencias" ], "sentiment_score": -2, "publication_date": "2025-06-09T10:19:10" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is mentioned in connection with legal allegations of corruption, contributing to a negative perception.", "headline": "'Caso aforamiento': la letrada mayor de la Asamblea certifica a la juez que Ficticio es diputado desde antes de prometer su cargo en el Pleno", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias" ], "sentiment_score": -2, "publication_date": "2025-06-09T08:08:30" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is implicated in the same investigation as Ficticio, raising concerns about political corruption and influence.", "headline": "Aforamientos: esa figura incómoda", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "investigación" ], "sentiment_score": -2, "publication_date": "2025-06-08T06:01:00" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is implicated in the same investigation as Ficticio, which raises concerns about political misconduct.", "headline": "Aforamientos: esa figura incómoda", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "investigación", "delitos" ], "sentiment_score": -2, "publication_date": "2025-06-08T06:00:59" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in a case of favoritism and corruption, which casts a negative light on his character and actions.", "headline": "'Caso Javier Ejemplo': las asociaciones judiciales salen en defensa de la juez Luisa Inventada ante las \"presiones externas\" que sufre", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "favoritism", "corruption", "persecution" ], "sentiment_score": -2, "publication_date": "2025-06-06T10:08:15" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in a case of alleged favoritism and corruption, which casts a negative light on his character and actions.", "headline": "'Caso Javier Ejemplo': las asociaciones judiciales salen en defensa de la juez Luisa Inventada ante las \"presiones externas\" que sufre", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "favoritism", "corruption", "persecution" ], "sentiment_score": -2, "publication_date": "2025-06-06T08:08:15" } ], "additional_information": {} } ], "score": 80, "screened_data": { "full_name": "Javier Ejemplo Modelo", "nationality": "ES", "date_of_birth": "1974-01-01", "document_number": null }, "is_ongoing_monitoring_enabled": true, "next_ongoing_monitoring_bill_date": "2026-07-24", "last_ongoing_screening_at": "2026-09-12T04:03:11Z", "last_ongoing_screening_datasets_updated_at": "2026-09-11T06:00:00Z", "warnings": [ { "feature": "AML", "risk": "POSSIBLE_MATCH_FOUND", "additional_data": null, "log_type": "warning", "short_description": "Possible match found in AML screening", "long_description": "The Anti-Money Laundering (AML) screening process identified potential matches with watchlists or high-risk databases, requiring further review.", "node_id": "feature_aml_1" } ] } ], "ip_analyses": [ { "node_id": "feature_ip_1", "status": "Approved", "device_brand": "Apple", "device_model": "iPhone", "browser_family": "Mobile Safari", "os_family": "iOS", "platform": "mobile", "device_fingerprint": "didit-fp-a1b2c3d4e5f6g7h8", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Barcelona", "ip_city": "Barcelona", "latitude": 41.4022, "longitude": 2.1407, "ip_address": "83.50.226.71", "isp": null, "organization": null, "is_vpn_or_tor": false, "is_data_center": false, "time_zone": "Europe/Madrid", "time_zone_offset": "+0100", "ip": { "location": { "latitude": 40.2206327, "longitude": 1.5770097 }, "distance_from_id_document": 23.4, "distance_from_poa_document": 12.3 }, "id_document": { "location": { "latitude": 41.2706327, "longitude": 1.9770097 }, "distance_from_ip": 23.4, "distance_from_poa_document": 18.7 }, "poa_document": { "location": { "latitude": 41.2706327, "longitude": 1.9770097 }, "distance_from_ip": 12.3, "distance_from_id_document": 18.7 }, "warnings": [], "matches": [ { "session_id": "99999999-8888-7777-6666-555555555555", "session_number": 41205, "vendor_data": "22222222-2222-2222-2222-222222222222", "verification_date": "2024-07-20T10:15:30Z", "match_type": "ip_address", "match_source": "ip_address", "matched_value": "83.50.226.71", "status": "Approved", "is_blocklisted": false, "api_service": null, "source": "session", "device_info": { "device_brand": "Apple", "device_model": "iPhone", "browser_family": "Mobile Safari", "os_family": "iOS", "platform": "mobile", "device_fingerprint": "didit-fp-f9e8d7c6b5a40312" }, "location_info": { "ip_address": "83.50.226.71", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Barcelona", "ip_city": "Barcelona", "is_vpn_or_tor": false, "is_data_center": false }, "confidence": 0.0, "match_mode": "co_occurrence" }, { "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "session_number": 42830, "vendor_data": "33333333-3333-3333-3333-333333333333", "verification_date": "2024-06-30T18:22:05Z", "match_type": "device_fingerprint", "match_source": "recovered_high", "matched_value": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "Declined", "is_blocklisted": false, "api_service": null, "source": "session", "device_info": { "device_brand": "Samsung", "device_model": "SM-G991B", "browser_family": "Chrome Mobile", "os_family": "Android", "platform": "mobile", "device_fingerprint": null }, "location_info": { "ip_address": "83.50.231.18", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Madrid", "ip_city": "Madrid", "is_vpn_or_tor": false, "is_data_center": false }, "confidence": 1.0, "match_mode": "deterministic", "recovery_similarity": 0.9874, "tls_ja4_corroborated": true, "recovery_gate_reason": "hardware_root_match" } ] } ], "database_validations": [ { "node_id": "feature_db_validation_1", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "last_name": "De Lima", "first_name": "Fernando", "tax_number": "01234567890", "date_of_birth": "1980-01-01", "document_type": "ID", "expiration_date": "2030-01-01" }, "validations": [ { "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "outcome_code": "MATCH", "validation": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "source_data": { "identification_number": "01234567890", "first_name": "FERNANDO", "last_name": "DE LIMA", "date_of_birth": "1980-01-01", "gender": "M", "nationality": "BRA" } } ], "match_type": "full_match", "status": "Approved", "warnings": [] } ], "reviews": [ { "user": "compliance@example.com", "new_status": "Declined", "comment": "Possible match found in AML screening", "created_at": "2024-07-18T13:29:00.366811Z" } ], "created_at": "2024-07-24T08:54:25.443172Z", "expires_at": "2025-07-24T08:54:25.443172Z", "biometric_consent": { "required": false, "trigger": null, "status": "not_required", "given_at": null, "declined_at": null, "text_version": null, "text_hash": null, "locale": null, "policy_url": null, "step": null, "node_id": null, "ip_address": null, "ip_country_code": null, "ip_state": null, "ip_city": null, "user_agent": null, "detected_ip_address": "83.50.226.71", "detected_country_code": "ES", "detected_state": "ES-B", "detected_city": "Barcelona", "declared_state": null, "document_state": null, "jurisdictions": [], "retention_months": null, "reason": null, "decline_reason": null, "face_data_deleted_at": null } } }, "BusinessExample": { "summary": "Esempio di sessione aziendale (KYB)", "description": "Una decisione con `session_kind = \"business\"`: le sessioni KYB sostituiscono gli array delle funzionalità KYC con `registry_checks`, `document_verifications` e `key_people_checks`, condividendo al contempo `aml_screenings`, `phone_verifications`, `email_verifications`, `questionnaire_responses`, `ip_analyses`, `reviews` e l'involucro della sessione.", "value": { "session_id": "66666666-7777-8888-9999-000000000000", "session_kind": "business", "session_number": 31415, "session_url": "https://verify.didit.me/session/business123", "status": "In Review", "environment": "live", "workflow_id": "abababab-cdcd-efef-0101-232323232323", "features": [ "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE" ], "vendor_data": "merchant-001234", "metadata": null, "callback": "https://example.com/verification/callback", "registry_checks": [ { "status": "Approved", "node_id": "feature_kyb_registry_1", "data_resolved": true, "company": { "uuid": "dddd4444-eeee-5555-ffff-666677778888", "node_id": "feature_kyb_registry_1", "status": "Approved", "registry_status": "active", "data_resolved": true, "company_name": "ACME HOLDINGS LTD", "registration_number": "12345678", "country_code": "GB", "region": null, "company_type": "Private Limited Company", "incorporation_date": "2015-03-12", "registered_address": "1 Example Street, London, EC1A 1AA", "tax_number": null, "risk_level": null, "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": null, "nature_of_business": "62012 - Business and domestic software development", "registered_capital": "100 GBP", "registered_capital_amount": "100.00", "registered_capital_currency": "GBP", "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": "England and Wales", "financial_summary": null, "officers": [ { "uuid": "aaaa1111-bbbb-2222-cccc-333344445555", "name": "Jane Smith", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/session/abc123def456" } ], "beneficial_owners": [ { "uuid": "bbbb2222-cccc-3333-dddd-444455556666", "name": "John Doe", "first_name": "John", "last_name": "Doe", "entity_type": "person", "roles": [ "ubo", "shareholder" ], "ownership_min_shares": "50", "ownership_max_shares": "75", "is_active": true, "kyc_status": "Pending", "kyc_session_url": "https://verify.didit.me/session/def456ghi789", "effective_ownership_percent": 75.0 } ], "addresses": [ { "type": "registered", "address": "1 Example Street, London, EC1A 1AA", "country": "GB" } ], "industries": [ { "code": "62012", "description": "Business and domestic software development" } ], "accounts": null, "registry_data": {}, "user_provided_data": { "company_name": "ACME HOLDINGS", "registration_number": "12345678" }, "confirmed_by_user_at": "2026-06-10T12:01:30.000000Z", "last_console_edit_at": null, "is_editable": false }, "ownership_structure": { "shareholders": [ { "name": "John Doe", "first_name": "John", "last_name": "Doe", "date_of_birth": null, "country_of_birth": null, "company_name": null, "registration_number": null, "entity_type": "person", "nationality": null, "designation": null, "roles": [ "shareholder" ], "ownership_min_shares": "75", "ownership_max_shares": "75", "voting_min_shares": null, "voting_max_shares": null, "appointment_date": null, "is_active": true, "shareholding": { "share_class": "ORDINARY", "number_of_shares": 750.0, "currency": "GBP", "nominal_value": 1.0, "total_value": null, "percentage": 75.0 } } ], "beneficial_owners": [] }, "warnings": [] } ], "aml_screenings": null, "document_verifications": [ { "status": "In Review", "node_id": "feature_kyb_documents_1", "items": [ { "uuid": "eeee5555-ffff-6666-0000-777788889999", "document_type": "LEGAL_PRESENCE", "document_subtype": "CERTIFICATE_OF_INCORPORATION", "document_group": "LEGAL_PRESENCE", "file_url": "https:///kyb/certificate-of-incorporation.pdf", "original_filename": "certificate_of_incorporation.pdf", "file_size": 482133, "status": "Approved", "created_at": "2026-06-10T12:03:11.000000Z", "cross_check_result": { "critical": { "company_name": { "document": "ACME HOLDINGS LTD", "registry": "ACME HOLDINGS LTD", "score": 1.0, "match": true }, "registration_number": { "document": "12345678", "registry": "12345678", "match": true } }, "non_critical": {}, "people": {} }, "document_metadata": { "file_size": 482133, "content_type": "application/pdf", "creation_date": "2015-03-12T09:00:00", "modified_date": "2015-03-12T09:00:00", "creator": null, "producer": null, "software": null, "encryption": null, "is_signed": true, "is_tampered": false, "signature_info": null, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": false, "overlay_manipulation": null }, "description": null, "is_requested": false, "ocr_data": { "company_name": "ACME HOLDINGS LTD", "registration_number": "12345678", "incorporation_date": "2015-03-12" }, "is_console_upload": false, "is_confirmed": true }, { "uuid": "ffff6666-0000-7777-1111-888899990000", "document_type": "OWNERSHIP_STRUCTURE", "document_subtype": null, "document_group": "OWNERSHIP_STRUCTURE", "file_url": null, "original_filename": null, "file_size": null, "status": "Not Finished", "created_at": "2026-06-10T15:40:02.000000Z", "cross_check_result": null, "document_metadata": null, "description": "Please upload an up-to-date shareholder registry", "is_requested": true, "ocr_data": null, "is_console_upload": false, "is_confirmed": true } ], "groups": { "LEGAL_PRESENCE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }, "OWNERSHIP_STRUCTURE": { "total": 1, "approved": 0, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 1 } }, "required_groups": [ "LEGAL_PRESENCE", "OWNERSHIP_STRUCTURE" ], "warnings": [] } ], "key_people_checks": [ { "status": "In Review", "node_id": "feature_kyb_key_people_1", "registry": { "officers": [ { "uuid": "aaaa1111-bbbb-2222-cccc-333344445555", "name": "Jane Smith", "designation": "Director", "role": "director", "nationality": "British", "appointment_date": "2015-03-12", "termination_date": null, "is_active": true, "address": "1 Example Street, London, EC1A 1AA", "aml_status": "Approved", "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/session/abc123def456", "kyc_session_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb", "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "didit_internal_id": "99999999-0000-1111-2222-333333333333", "kyc_document_type": "P", "kyc_nationality": "GBR", "kyc_liveness_passed": true, "kyc_verified_at": "2026-06-10T14:22:31.123456Z", "kyc_aml_categories": { "sanctions": "clear", "pep": "clear", "adverse_media": "clear", "warnings": "clear" }, "kyc_notification_sent_at": "2026-06-09T09:00:00.000000Z" } ], "beneficial_owners": [ { "uuid": "bbbb2222-cccc-3333-dddd-444455556666", "name": "John Doe", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-05-04", "country_of_birth": null, "email": null, "company_name": null, "registration_number": null, "entity_type": "person", "nationality": "British", "designation": null, "roles": [ "ubo", "shareholder" ], "ownership_min_shares": "50", "ownership_max_shares": "75", "is_active": true, "aml_status": null, "kyc_status": "In Progress", "kyc_session_url": "https://verify.didit.me/session/def456ghi789", "kyc_session_id": "88888888-9999-aaaa-bbbb-cccccccccccc", "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" } ], "didit_internal_id": null, "kyc_document_type": null, "kyc_nationality": null, "kyc_liveness_passed": null, "kyc_verified_at": null, "kyc_aml_categories": null, "kyc_notification_sent_at": null, "child_beneficial_owners": [], "effective_ownership_percent": 75.0 } ] }, "submitted": { "parties": [ { "uuid": "cccc3333-dddd-4444-eeee-555566667777", "entity_type": "person", "source": "USER", "name": "John Doe", "first_name": "John", "last_name": "Doe", "company_name": null, "registration_number": null, "email": "john.doe@example.com", "nationality": "GBR", "phone_number": "+447700900123", "date_of_birth": "1980-05-04", "position": "Chief Executive Officer", "custom_fields": {}, "is_active": true, "is_skipped": false, "requires_verification": true, "roles": [ { "role": "ubo", "ownership_percent": 75.0, "voting_percent": 75.0 }, { "role": "director", "ownership_percent": null, "voting_percent": null } ], "kyc_session_id": "88888888-9999-aaaa-bbbb-cccccccccccc", "kyc_session_status": "In Progress", "kyc_session_url": "https://verify.didit.me/session/def456ghi789", "kyb_sub_session_id": null, "kyb_sub_session_status": null, "kyb_sub_session_url": null, "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" } ], "didit_internal_id": null } ] }, "ubo_kyc_summary": { "total": 1, "approved": 0, "flagged": 0, "pending": 1 }, "warnings": [] } ], "phone_verifications": null, "email_verifications": null, "questionnaire_responses": null, "ip_analyses": null, "reviews": [], "contact_details": null, "expected_details": { "company_name": "Tesco PLC", "registry_country": "GB", "registration_number": "00445790" }, "created_at": "2026-06-10T11:58:04.000000Z", "expires_at": "2026-06-24T11:58:04.000000Z" } } }, "schema": { "$ref": "#/components/schemas/SessionDecision" } } } }, "403": { "description": "Autenticazione o autorizzazione non riuscita. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`. Due stringhe `detail` distinguono le modalità di errore:\n\n- `\"Authentication credentials were not provided or are invalid.\"` — nessuna intestazione `x-api-key` (e nessun token `Authorization: Bearer`), oppure la credenziale fornita non ha superato l'introspezione (revocata, scaduta o malformata).\n- `\"You do not have permission to perform this action.\"` — la credenziale è valida ma non è autorizzata a leggere questa sessione: a un token Bearer dell'utente della console manca l'autorizzazione `read:sessions` o non può accedere all'applicazione proprietaria, oppure una chiave API appartiene a un'organizzazione diversa rispetto alla sessione.\n\nTieni presente che per un `sessionId` completamente sconosciuto l'endpoint risolve l'applicazione proprietaria prima di convalidare le credenziali, quindi una sessione mancante restituisce `404` anche quando la credenziale è mancante o non valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Authentication credentials were not provided or are invalid." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure introspezione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Insufficient permissions": { "summary": "Credenziale valida priva di read:sessions o dell'accesso all'applicazione proprietaria", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Sessione non trovata. Restituito quando nessuna sessione attiva corrisponde al `sessionId` fornito come sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB) — viene restituito anche per una sessione che è stata eliminata. Il body è il wrapper standard `{\"detail\": ...}`.\n\n**Due diverse stringhe `detail`.** Se il `sessionId` è sconosciuto sia come sessione KYC che KYB, la ricerca del proprietario pre-autenticazione fallisce e ricevi `{\"detail\": \"Not found.\"}` — questo avviene prima della validazione delle credenziali, quindi viene restituito anche per chiamate non autenticate. Se la sessione esiste ma non può essere recuperata nell'ambito dell'applicazione autenticata (ad esempio un record obsoleto o appena eliminato), la vista restituisce `{\"detail\": \"Session not found.\"}`. Entrambi indicano lo stesso risultato — la sessione non è accessibile — quindi effettua la verifica sul codice di stato `404` piuttosto che sulla stringa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Not found." } } }, "examples": { "Unknown session id": { "summary": "sessionId non è noto a questa applicazione", "value": { "detail": "Not found." } }, "Session not retrievable": { "summary": "La sessione esiste ma non è recuperabile per questa applicazione", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite di frequenza superato. Le richieste GET sono limitate a **600 al minuto per credenziale** (chiave API, token Bearer o indirizzo IP di origine se non autenticato). Esamina `Retry-After` / `X-RateLimit-Reset` e attendi prima di riprovare. Se raggiungi questo limite durante il polling delle decisioni, passa al webhook `status.updated` e recupera la decisione una sola volta per ciascun cambio di stato.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di riprovare la richiesta.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Numero massimo di richieste consentite nella finestra temporale corrente (600 per le richieste GET).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Timestamp Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1750000000 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Spiegazione di facile lettura del superamento del limite di frequenza.", "example": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } }, "examples": { "Throttled": { "summary": "Più di 600 richieste GET in un minuto dalla stessa credenziale", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica di cui vuoi recuperare la decisione. Corrisponde al `session_id` restituito da `POST /v3/session/`. Lo stesso percorso funziona sia per le sessioni di Verifica degli utenti (KYC) sia per quelle di Verifica aziendale (KYB): il server risolve l'ID per entrambi i tipi di sessione.\n\n**Deve essere un UUID valido.** La route trova corrispondenza solo con UUID corretti, pertanto un valore non conforme viene rifiutato dal router degli URL prima dell'esecuzione del codice dell'applicazione e la risposta è una pagina **HTML** `404` anziché il wrapper JSON `{\"detail\": ...}` mostrato di seguito. Valida il formato dell'UUID lato client per distinguere un errore di input da un autentico `404` per sessione mancante.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "include", "in": "query", "required": false, "description": "Elenco separato da virgole di sezioni di payload aggiuntive. Valori supportati: `events` e `resubmissions`, singolarmente o insieme (`events,resubmissions`). Quando viene passato `include=events`, la risposta contiene inoltre la cronologia degli eventi della sessione (`events`, compresi gli eventi di routing `WORKFLOW_BRANCH_EVALUATED` / `WORKFLOW_STATUS_NODE_REACHED` descritti nella pagina Recupera sessione), il registro completo delle attività (`activity_reviews`), i flag di blocklist (`blocklisted`), un `cost_breakdown` per sessione, i metadati del workflow (`workflow_type`, `workflow_version`, `workflow_version_id` e `workflow_terminal_node_id` - l'ultimo nodo di stato del workflow registrato che ha impostato uno stato della sessione, o `null` se non ne è stato registrato alcuno; provenienza storica che non viene cancellata da approvazioni, rifiuti o nuovi invii manuali ed è sostituita da un nodo di stato del workflow successivo) e i metadati della sessione (`api_service` — stringa o `null`, impostato solo per le sessioni API autonome; `session_type` — `API`, `HOSTED` o `MIGRATED`; `has_device_nfc_support` — booleano). Due campi cambiano rispetto alla struttura standard: il discriminatore di primo livello `session_kind` viene **omesso** (la struttura degli eventi esiste solo per le sessioni utente) e l'array `features` passa da stringhe semplici a oggetti `{feature, node_id}` — dove la funzionalità email viene indicata come `EMAIL` invece di `EMAIL_VERIFICATION`. Questa struttura estesa è utilizzata principalmente dalla Console Didit; la maggior parte delle integrazioni API dovrebbe omettere il parametro. **Limitazione KYB:** `include=events` si applica solo alle sessioni utente (KYC). Le sessioni aziendali (`session_kind = \"business\"`) restituiscono sempre la struttura standard della decisione aziendale — `events`, `activity_reviews`, `blocklisted`, `cost_breakdown` e i metadati aggiuntivi `workflow_*`/della sessione non vengono mai restituiti per le sessioni aziendali, e il loro array `features` rimane un semplice array di stringhe. Con `include=resubmissions` (sia per le sessioni utente che aziendali), la risposta contiene anche `resubmissions`: una voce per ciascuna richiesta di nuovo invio, dalla più vecchia alla più recente, ciascuna con `number`, `created_at`, `previous_status`, `nodes`, `reasons`, `requested_by` e `results` (ciò che i passaggi reinviati hanno restituito prima della richiesta, sotto le stesse chiavi e nella stessa struttura dei risultati attuali). Ciascun elemento di `cost_breakdown` include `usage_type`, `price`, `details` e `created_at`: un passaggio reinviato che viene eseguito nuovamente viene fatturato come nuovo elemento.", "schema": { "type": "string", "enum": [ "events", "resubmissions", "events,resubmissions" ], "example": "events" } } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/decision/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Accept: application/json'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.retrieve_decision(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.retrieveDecision(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.RetrieveDecision(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsRetrieveDecisionParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().retrieveDecision(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->retrieveDecision('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.retrieve_decision(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.RetrieveDecisionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/delete/": { "delete": { "summary": "Elimina una sessione di verifica (KYC o KYB)", "description": "Elimina una singola sessione di verifica, Verifica degli utenti (KYC) o Verifica aziendale (KYB), tramite il suo `session_id`. L'id viene risolto prima rispetto alle sessioni KYC, poi a quelle KYB, quindi entrambi i tipi vengono eliminati tramite questo unico URL.\n\n**Cosa viene eliminato:**\n- La sessione e ogni tentativo di verifica che contiene, inclusi i risultati sostituiti da un nuovo invio: la decisione, i dati estratti, tutti i record delle funzionalità correlate (verifica dell'identità, volto, rilevamento della vitalità, confronto facciale, AML, controlli sui registri, analisi IP e così via), le relative revisioni e il suo registro delle attività.\n- Tutti i file archiviati appartenenti alla sessione: foto fronte/retro dei documenti (varianti intere, ritagliate e con oscuramento per la privacy), video di acquisizione dei documenti, ritagli del ritratto, immagini del ritratto e della firma dal chip NFC, immagini di riferimento del volto, video di rilevamento della vitalità, immagini sorgente/destinazione per il confronto facciale, documenti di Prova di residenza e qualsiasi file aggiuntivo caricato (KYC); documenti aziendali e file aggiuntivi caricati (KYB). Documenti di Firma elettronica, PDF firmati, PDF probatori e immagini delle firme (KYC e KYB): i relativi percorsi di download smettono di funzionare. Gli URL dei contenuti multimediali emessi in precedenza (`https:///...`) smettono di risolversi.\n- I dati del volto della sessione. Anche il relativo embedding facciale viene eliminato, a meno che tu non scelga di conservare un modello privo di immagini (vedi **Dati biometrici del volto**).\n- Le consegne dei webhook ancora in coda per la sessione e i relativi tentativi. I webhook già consegnati non sono interessati.\n- Per una sessione di Verifica aziendale (KYB): le verifiche create per le sue persone chiave (KYC) e i suoi proprietari aziendali (KYB), in modo ricorsivo, indicate come `deleted_child_verifications`. Una verifica a cui è solo collegata, come un KYC approvato esistente che ha riutilizzato, non viene eliminata.\n\nLa sessione scompare immediatamente da ogni endpoint di lettura: `GET /v3/session/{sessionId}/decision/` restituisce `404` e `GET /v3/sessions/` smette di includerla nell'elenco. Il monitoraggio AML continuo e il monitoraggio del registro KYB avviati dalle verifiche eliminate si interrompono.\n\n**Cosa non viene modificato:** le voci della blocklist create a partire da questa sessione (volto o documento) **non** vengono rimosse; gestiscile tramite gli endpoint della blocklist. I token di condivisione emessi per la sessione non vengono revocati, ma non c'è più nulla che possano importare: un'importazione con uno di essi restituisce `400` con `{\"share_token\": [\"Original session does not exist.\"]}`. I crediti già consumati **non** vengono rimborsati. L'entità genitore User o Business **non** viene eliminata; usa `POST /v3/users/delete/` o `POST /v3/businesses/delete/` per queste entità. Se il ritratto del profilo dell'User proveniva da questa sessione, il ritratto viene rimosso insieme ad essa.\n\n**Dati biometrici del volto:** per impostazione predefinita, l'embedding facciale della sessione viene eliminato con la sessione (`face_retention_outcome: deleted`). Un'applicazione che ha scelto la conservazione del modello biometrico (`face_retention_policy: retain_until_user_deleted` su `PATCH /v3/webhook/`), o una richiesta con `retain_face_embeddings: true`, conserva un unico modello biometrico facciale gestito separatamente e privo di immagini ancorato all'User della sessione (`retained_with_user`), in modo che il rilevamento dei duplicati, Ricerca facciale e l'autenticazione biometrica continuino a funzionare. Il modello non contiene mai l'immagine del volto, contenuti multimediali, campi di identità, la decisione o l'id della sessione eliminata; si tratta di dati biometrici eliminati a `biometric_template_expires_at`, oppure prima in caso di eliminazione dell'User, cancellazione per motivi di privacy o eliminazione esplicita tramite `/v3/biometric-templates/`. Una sessione senza un User collegato non può conservare un modello (`ineligible_no_vendor_user`). Invia `deletion_instruction: privacy_erasure` per le richieste degli interessati: elimina definitivamente ogni modello conservato per quell'User e non ne conserva mai uno nuovo.\n\n**Irreversibile:** l'eliminazione è permanente e non esiste alcun endpoint di ripristino. Esporta tutto ciò di cui hai bisogno (ad esempio un PDF della decisione) prima di chiamarlo.\n\n**Effetti collaterali:** non viene emesso alcun webhook per le eliminazioni.\n\n**Risposta:** `200 OK` una volta completata l'eliminazione, con un corpo JSON che riporta `face_retention_outcome`, la scadenza del modello conservato e, per una sessione KYB, `deleted_child_verifications`. Le versioni precedenti di questo endpoint restituivano `204 No Content`; aggiorna i client che verificano `204`. Conserva il tuo `instruction_id` nel tuo registro di cancellazione.\n\n**Idempotenza:** non idempotente a livello HTTP: la prima chiamata restituisce `200`; se ripetuta restituisce `404` perché la sessione non viene più risolta. Dopo un `503` la sessione è ancora presente; ripeti la stessa richiesta per completarne l'eliminazione.\n\n**Autenticazione:** invia la chiave API della tua applicazione nell'intestazione `x-api-key`; la sessione deve appartenere a tale applicazione. Anche i token di accesso utente della console (`Authorization: Bearer ...`) possono chiamare questo endpoint quando dispongono dell'autorizzazione `delete:sessions`. Gli errori di autenticazione e di autorizzazione restituiscono entrambi `403`; questa API non restituisce mai `401`.\n\n**Limite di frequenza:** budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`.\n\nPer eliminare in blocco le sessioni KYC in base al loro `session_number` numerico, usa invece `POST /v3/sessions/delete/`.\n\n**Report normativi depositati:** se i dati selezionati si trovano in un report normativo finalizzato, l'intera richiesta viene rifiutata con `409` e nulla viene eliminato. Il corpo utilizza `code: in_filed_report` e indica ciascun report con `uuid`, `report_number`, `report_type` e `case_uuid`. Elimina i report, quindi ripeti la richiesta.", "operationId": "delete_v3_session_by_id", "x-didit-sdk": { "resource": "sessions", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID (`session_id`) della sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB) da eliminare, come restituito al momento della creazione della sessione. Deve essere un UUID canonico separato da trattini: un valore che non è un UUID non corrisponde al percorso e restituisce `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "responses": { "200": { "description": "Sessione eliminata. Il corpo riporta cosa è successo ai dati biometrici facciali della sessione e, per una sessione KYB, quante verifiche create da essa sono state eliminate insieme ad essa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "La sessione eliminata." }, "session_number": { "type": "integer", "nullable": true, "description": "Il numero della sessione eliminata." }, "face_retention_outcome": { "type": "string", "enum": [ "retained_with_user", "deleted", "none", "ineligible_no_vendor_user" ], "description": "Cosa è successo ai dati biometrici facciali della sessione. `deleted`: l'embedding facciale è stato eliminato insieme alla sessione (impostazione predefinita). `retained_with_user`: la sessione viene eliminata e un modello biometrico senza immagini rimane associato all'Utente; vedi `biometric_template_uuid`. `none`: la sessione non aveva alcun embedding facciale (ad esempio una sessione KYB o una sessione KYC senza selfie per la prova di vita). `ineligible_no_vendor_user`: la conservazione era stata richiesta ma la sessione non ha alcun Utente collegato, quindi l'embedding è stato eliminato con la sessione. Un errore dello store biometrico non viene mai segnalato tramite questo campo su questo endpoint: restituisce `503` e la sessione non viene eliminata." }, "biometric_template_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del modello biometrico conservato quando `face_retention_outcome` è `retained_with_user`; `null` altrimenti. Gestiscilo tramite `/v3/biometric-templates/{template_uuid}/`." }, "biometric_template_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il modello biometrico conservato viene eliminato, se `face_retention_outcome` è `retained_with_user`; `null` quando nessun modello viene conservato." }, "deleted_child_verifications": { "type": "integer", "description": "Per una sessione di Verifica aziendale (KYB): quante verifiche ha creato (le sessioni KYC delle sue persone chiave e le sessioni KYB dei suoi proprietari aziendali, ricorsivamente) che sono state eliminate insieme ad essa. Sempre `0` per una sessione KYC." } } }, "examples": { "Deleted (default)": { "value": { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1024, "face_retention_outcome": "deleted", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } }, "Retained with User": { "value": { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1024, "face_retention_outcome": "retained_with_user", "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "biometric_template_expires_at": "2027-10-09T10:15:00Z", "deleted_child_verifications": 0 } }, "Ineligible: no User": { "summary": "Conservazione richiesta per una sessione creata senza vendor_data", "value": { "session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c", "session_number": 1031, "face_retention_outcome": "ineligible_no_vendor_user", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } }, "KYB session": { "value": { "session_id": "0f3c9b7e-2d1a-4e5f-8c6b-7a9d8e1f2c3b", "session_number": 88, "face_retention_outcome": "none", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 3 }, "summary": "Una verifica aziendale eliminata insieme alle tre verifiche create per le relative persone chiave" } } } } }, "400": { "description": "Errore di validazione — nulla viene eliminato.", "content": { "application/json": { "examples": { "Privacy erasure cannot retain": { "value": { "retain_face_embeddings": [ "Privacy erasure cannot retain biometric templates." ] } }, "No finite retention duration": { "summary": "Conservazione richiesta senza face_retention_days nella richiesta o nell'applicazione", "value": { "detail": "A finite biometric-template retention duration is required." } } } } } }, "403": { "description": "Errore di autenticazione o di autorizzazione. Anche una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`. Eccezione: quando il `sessionId` non corrisponde a una sessione attiva, la ricerca del proprietario prima dell'autenticazione restituisce prima `404`, anche con credenziali mancanti o non valide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione x-api-key, oppure la chiave non è valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Insufficient permission": { "summary": "Token utente senza delete:sessions, o credenziali per un'applicazione che non possiede la sessione", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Non esiste alcuna sessione KYC o KYB attiva con questo `session_id` — l'id è sconosciuto o la sessione è già stata eliminata (la ripetizione di un'eliminazione riuscita porta a questo risultato).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not Found": { "summary": "Sessione sconosciuta o già eliminata", "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza di scrittura condiviso superato (300 richieste POST/PATCH/DELETE al minuto per chiave API). Esamina `Retry-After` e le intestazioni di risposta `X-RateLimit-*` prima di effettuare un nuovo tentativo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Budget di scrittura esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } }, "503": { "description": "Impossibile completare l'eliminazione perché un servizio di archiviazione, uno store biometrico o un provider di monitoraggio non era disponibile. La sessione è ancora presente; ripeti la stessa richiesta finché non restituisce `200`. Alcuni dei suoi file archiviati o il suo embedding facciale potrebbero essere già stati eliminati, quindi non farvi affidamento dopo un `503`. I nuovi tentativi convergono su un singolo modello.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Session deletion unavailable": { "summary": "Un servizio di archiviazione o un provider di monitoraggio non era disponibile", "value": { "detail": "The session could not be deleted because a storage service or a monitoring provider is unavailable. The session is still in place; repeat the request to finish deleting it." } }, "Biometric store unavailable": { "summary": "Un archivio biometrico non era disponibile durante la conservazione o l'eliminazione definitiva di un modello", "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } }, "409": { "description": "La sessione fa parte di un report normativo finalizzato. Non viene eliminato nulla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl (default policy)", "source": "curl -X DELETE \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "curl", "label": "curl (retain template)", "source": "curl -X DELETE \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"retain_face_embeddings\": true, \"face_retention_days\": 365}'" }, { "lang": "curl", "label": "curl (privacy erasure)", "source": "curl -X DELETE \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"deletion_instruction\": \"privacy_erasure\", \"instruction_id\": \"dsar-2026-0142\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.delete(\n \"11111111-2222-3333-4444-555555555555\",\n retain_face_embeddings=True,\n face_retention_days=365,\n instruction_id=\"post-approval-cleanup-2026-08\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.delete(\"11111111-2222-3333-4444-555555555555\", {\n retain_face_embeddings: true,\n face_retention_days: 365,\n instruction_id: \"post-approval-cleanup-2026-08\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsDeleteParams{\n\tRetainFaceEmbeddings: didit.Bool(true),\n\tFaceRetentionDays: didit.Int(365),\n\tInstructionID: didit.String(\"post-approval-cleanup-2026-08\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().delete(\"11111111-2222-3333-4444-555555555555\", SessionsDeleteParams.builder()\n .retainFaceEmbeddings(true)\n .faceRetentionDays(365L)\n .instructionId(\"post-approval-cleanup-2026-08\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->delete('11111111-2222-3333-4444-555555555555', [\n 'retain_face_embeddings' => true,\n 'face_retention_days' => 365,\n 'instruction_id' => 'post-approval-cleanup-2026-08',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.delete(\n \"11111111-2222-3333-4444-555555555555\",\n retain_face_embeddings: true,\n face_retention_days: 365,\n instruction_id: \"post-approval-cleanup-2026-08\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsDeleteParams\n{\n RetainFaceEmbeddings = true,\n FaceRetentionDays = 365,\n InstructionId = \"post-approval-cleanup-2026-08\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": false, "description": "Opzionale. Ometti interamente il corpo per seguire la politica di conservazione dell'applicazione con un'eliminazione operativa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "retain_face_embeddings": { "type": "boolean", "nullable": true, "description": "Esegui l'override della `face_retention_policy` dell'applicazione per questa eliminazione. `true` mantiene un modello biometrico facciale privo di immagini associato all'Utente della sessione dopo l'eliminazione della sessione; `false` elimina l'embedding facciale insieme alla sessione; ometti o imposta su `null` per seguire la politica dell'applicazione. Ignorato per le sessioni KYB e per le sessioni senza un embedding facciale.", "example": true }, "face_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Periodo di conservazione limitato, in giorni, per un modello conservato. Obbligatorio quando un modello viene conservato, a meno che l'applicazione non imposti già `face_retention_days`. Il campo `expires_at` del modello corrisponde al valore più anticipato tra questa durata, la finestra generale di conservazione dei dati dell'applicazione e `face_retention_deadline`.", "example": 365 }, "face_retention_deadline": { "type": "string", "format": "date-time", "description": "Scadenza definitiva opzionale per un modello conservato. Deve essere nel futuro.", "example": "2027-08-28T00:00:00Z" }, "deletion_instruction": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ], "default": "operational_session_delete", "description": "La classe di istruzione che stai fornendo. `operational_session_delete` elimina la sessione e conserva un modello solo quando la policy o `retain_face_embeddings` lo prevede. `privacy_erasure` elimina definitivamente ogni modello biometrico conservato e associato all'Utente della sessione prima di eliminarla, non può essere sovrascritta dalla policy dell'applicazione e non può essere combinata con `retain_face_embeddings: true` (`400`).", "example": "operational_session_delete" }, "instruction_id": { "type": "string", "maxLength": 255, "description": "Il tuo riferimento permanente per questa istruzione di eliminazione (ad esempio l'ID di un ticket di cancellazione). Registrato nel registro di audit e su qualsiasi modello conservato. Generato da Didit se omesso.", "example": "dsar-2026-0142" } } }, "examples": { "Retain a biometric template": { "summary": "Elimina la sessione, conserva un modello privo di immagini per 365 giorni", "value": { "retain_face_embeddings": true, "face_retention_days": 365, "instruction_id": "post-approval-cleanup-2026-08" } }, "Force deletion on an opted-in application": { "summary": "Elimina l'embedding facciale indipendentemente dalla policy dell'applicazione", "value": { "retain_face_embeddings": false } }, "Privacy erasure": { "summary": "Richiesta dell'interessato: elimina la sessione ed elimina definitivamente ogni modello conservato per quella persona", "value": { "deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142" } } } } } } } }, "/v3/session/{sessionId}/generate-pdf/": { "get": { "summary": "Scarica un report PDF per una sessione di verifica", "description": "Genera ed esegue il download di un report PDF pronto per la compliance per una sessione di verifica completata. Lo stesso percorso gestisce sia sessioni di Verifica degli utenti (KYC) sia di Verifica aziendale (KYB) — il server risolve il `sessionId` per entrambi i tipi di sessione e seleziona il modello di report corrispondente.\n\n**Stati idonei.** La sessione deve avere già uno stato finale o revisionabile:\n\n- Sessioni KYC: `Approved`, `Declined`, `In Review` o `Kyc Expired`.\n- Sessioni KYB: `Approved`, `Declined` o `In Review`.\n\nQualsiasi altro stato (`Not Started`, `In Progress`, `Expired`, `Abandoned`, …) restituisce `403` con una stringa `detail` esplicativa — consulta la risposta `403` di seguito.\n\n**Cosa contiene il report.** Il PDF riflette la visualizzazione della sessione nella console al momento della richiesta:\n\n- **KYC** — stato aggregato della sessione, lista degli avvisi e una sezione per ciascuna funzionalità eseguita: Verifica dell'identità (immagini dei documenti e campi estratti), NFC, Rilevamento della vitalità, Confronto facciale, Verifica email, Verifica telefonica, Prova di residenza, risposte ai Questionari, Validazione su database, Screening AML e Analisi IP — seguiti dai tag della sessione, dall'attività di revisione nella console (commenti e cambi di stato) e dalla cronologia degli eventi della sessione.\n- **KYB** — verifiche nei registri (dati aziendali), screening AML, verifiche dei documenti aziendali, verifiche sulle persone chiave, risposte ai questionari, verifiche telefono/email, analisi IP e cronologia degli eventi della sessione, seguiti da tag e attività di revisione.\n\n**Personalizzazione del brand.** Se la tua applicazione dispone di personalizzazione white label, il report viene generato con il tuo logo e i link all'URL della tua informativa sulla privacy; in caso contrario include il brand di Didit. I report vengono generati in inglese — non è presente un parametro per la lingua.\n\n**Nessuna memorizzazione nella cache.** Ogni chiamata rigenera il PDF a partire dai dati correnti della sessione, pertanto un report generato dopo una revisione manuale riflette la decisione del revisore. Due chiamate per la stessa sessione possono produrre file con differenze a livello di byte — archivia il file scaricato se necessiti di una copia immutabile.\n\n**Latenza.** La generazione scarica ogni immagine archiviata (fronte/retro dei documenti, selfie, file aggiuntivi) prima di comporre il PDF, quindi le sessioni con molti contenuti multimediali possono richiedere diversi secondi. Utilizza un timeout di lettura lato client generoso (consigliati 60 s) e trasmetti il corpo in streaming su disco.\n\n**Barra finale.** Il percorso canonico termina con una barra finale (`…/generate-pdf/`). Una richiesta priva della barra viene gestita direttamente con la stessa risposta — non viene effettuato alcun reindirizzamento `301`, quindi nessun client deve seguire i reindirizzamenti e `curl` non necessita di `-L`. Utilizza l'URL con la barra come negli esempi.\n\nSe hai bisogno dei dati sottostanti in formato JSON invece di un report generato, usa `GET /v3/session/{sessionId}/decision/`. Per tutte le sessioni per cui è possibile generare un report di un utente in un unico documento, usa `GET /v3/users/{vendor_data}/generate-pdf/`.", "operationId": "get_v3_session_generate_pdf", "x-didit-sdk": { "resource": "sessions", "method": "generate_pdf", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB) da visualizzare — il `session_id` restituito da `POST /v3/session/`. Lo stesso percorso funziona per entrambi i tipi di sessione; usa il nome file nell'intestazione `Content-Disposition` della risposta per verificare quale tipo di report hai ricevuto.\n\n**Deve essere un UUID ben formato e in caratteri minuscoli.** Il percorso accetta solo UUID validi, quindi un valore non corretto viene rifiutato dal router degli URL prima che venga eseguito il codice dell'applicazione e la risposta è una pagina **HTML** `404` invece dell'envelope JSON `{\"detail\": ...}` mostrato sotto. Il convertitore di UUID del percorso accetta solo il formato canonico in minuscolo — gli UUID esadecimali in maiuscolo vengono rifiutati con l'errore HTML 404.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "responses": { "200": { "description": "Il documento PDF renderizzato, restituito direttamente come binario `application/pdf` — non sono presenti wrapper JSON né reindirizzamenti tramite URL di download. Il corpo inizia con i byte magici `%PDF` (PDF 1.7). Salvalo in un file `.pdf` o trasmettilo in streaming al tuo chiamante.", "headers": { "Content-Disposition": { "description": "`attachment; filename=session_{sessionId}.pdf` per le sessioni KYC, `attachment; filename=business_{sessionId}.pdf` per le sessioni KYB — il prefisso indica quale modello di report è stato generato.", "schema": { "type": "string", "example": "attachment; filename=session_11111111-2222-3333-4444-555555555555.pdf" } }, "Content-Length": { "description": "Dimensione totale del PDF in byte; il corpo non è frammentato in blocchi.", "schema": { "type": "integer", "example": 25191 } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Errore di autenticazione, autorizzazione o stato della sessione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`. Distingui le modalità di errore tramite la stringa `detail`:\n\n- `\"Authentication credentials were not provided or are invalid.\"` — nessuna intestazione `x-api-key` (e nessun token `Authorization: Bearer`), oppure la credenziale fornita non ha superato l'introspezione (revocata, scaduta o non valida).\n- `\"You do not have permission to perform this action.\"` — la credenziale è valida ma non può leggere questa sessione: a un token Bearer di un utente della console manca l'autorizzazione `read:sessions` o non può accedere all'applicazione proprietaria, oppure una chiave API appartiene a un'organizzazione diversa rispetto alla sessione.\n- `\"You can only generate a PDF for sessions in review, declined, approved or kyc expired\"` — la sessione KYC esiste ma non è ancora in uno stato idoneo (ad esempio `Not Started` o `In Progress`). Attendi il webhook `status.updated` prima di richiedere il report.\n- `\"You can only generate a PDF for sessions in review, declined or approved\"` — stessa condizione per le sessioni KYB.\n\nNota che per un `sessionId` del tutto sconosciuto l'endpoint individua l'applicazione proprietaria prima di convalidare le credenziali, quindi una sessione mancante restituisce `404` anche quando la credenziale è mancante o non valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You can only generate a PDF for sessions in review, declined, approved or kyc expired" } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure introspezione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Insufficient permissions": { "summary": "Credenziale valida priva di read:sessions o dell'accesso all'applicazione proprietaria", "value": { "detail": "You do not have permission to perform this action." } }, "KYC session not finished": { "summary": "Sessione KYC ancora Non avviata / In corso", "value": { "detail": "You can only generate a PDF for sessions in review, declined, approved or kyc expired" } }, "KYB session not finished": { "summary": "Sessione KYB ancora Non avviata / In corso", "value": { "detail": "You can only generate a PDF for sessions in review, declined or approved" } } } } } }, "404": { "description": "Non esiste alcuna sessione attiva con questo `sessionId` — non è mai stata creata o è stata eliminata. La risoluzione del proprietario avviene prima della convalida delle credenziali, quindi questo `404` viene restituito anche per le richieste non autenticate. A seconda di quale ricerca non va a buon fine, la stringa `detail` è `\"Not found.\"` (il caso più comune) o `\"Session not found.\"`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Not found." } } }, "examples": { "Unknown session": { "summary": "sessionId non corrisponde ad alcuna sessione KYC o KYB", "value": { "detail": "Not found." } }, "Recently deleted session": { "summary": "La sessione è stata eliminata tra una ricerca e l'altra", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite di frequenza superato. La generazione di PDF ha un limite dedicato di **50 richieste al minuto per credenziale** (chiave API, token Bearer o IP di origine se non autenticato), oltre al limite globale di 600 richieste GET al minuto. Attendi i secondi indicati in `Retry-After` (riportati anche nelle intestazioni `X-RateLimit-*`), poi riprova. I report non vengono memorizzati in cache lato server, pertanto scarica ciascun report una sola volta e archivia il file invece di recuperarlo nuovamente.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di riprovare la richiesta.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Numero massimo di generazioni di PDF consentite nella finestra temporale corrente (50).", "schema": { "type": "integer", "example": 50 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Timestamp Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1750000000 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Spiegazione di facile lettura del superamento del limite di frequenza.", "example": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } }, "examples": { "Throttled": { "summary": "Più di 50 generazioni di PDF in un minuto dalla stessa credenziale", "value": { "detail": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --fail \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/generate-pdf/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.generate_pdf(\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.generatePdf(\"11111111-2222-3333-4444-555555555555\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.GeneratePDF(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().generatePdf(\"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->generatePdf('11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.generate_pdf(\"11111111-2222-3333-4444-555555555555\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.GeneratePdfAsync(\"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/session/{sessionId}/sandbox/arm/": { "post": { "summary": "Attiva uno scenario sandbox su una sessione", "description": "Salva uno scenario sandbox su una sessione `Not Started` ed estende i relativi valori magici inclusi (email, telefono o campi `expected_details`) sulla sessione, in modo che i provider simulati riproducano l'esito dello scenario una volta avviato il flusso. Questo è l'endpoint chiamato dal selettore di scenari pre-flusso nell'interfaccia utente di verifica ospitata di Didit quando un tester sceglie un esito prima di iniziare l'acquisizione. Puoi creare il tuo selettore personalizzato su di esso o chiamarlo direttamente da un ambiente di test sandbox.\n\nAutenticati con il `Session-Token` della sessione stessa (restituito in `session_token` da [Create Session](/it/sessions-api/create-session)), non con la chiave `x-api-key` della tua applicazione: questo endpoint è pensato per essere chiamato dal client, non dal tuo backend. Uno scenario viene accettato solo mentre lo `status` è `Not Started`. Chiamandolo di nuovo mentre è ancora `Not Started`, la sessione viene riarmata: scambia i valori magici del nuovo scenario e cancella solo i valori scritti dallo scenario *precedente*, quindi qualsiasi valore già digitato a mano dall'utente (email, nome, ecc.) viene preservato. L'attivazione di una sessione che ha superato lo stato `Not Started` o che appartiene a un'applicazione di produzione (non sandbox) viene rifiutata.\n\nConsulta [Sandbox & Test Data](/it/integration/sandbox-testing) per il catalogo completo degli scenari e per gli altri due modi di guidare un esito: `sandbox_scenario` alla creazione della sessione e digitando direttamente i valori magici.", "operationId": "post_v3_session_sandbox_arm", "x-didit-sdk": { "resource": "sessions", "method": "arm_sandbox", "auth": "device_token", "server": false }, "tags": [ "Sessions" ], "security": [ { "SessionTokenAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica sandbox da attivare. Deve corrispondere alla sessione codificata nel Session-Token utilizzato per l'autenticazione.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scenario" ], "properties": { "scenario": { "type": "string", "description": "Slug dello scenario da attivare. Consulta il catalogo su GET /v1/sandbox/scenarios/ o la tabella degli scenari in [Sandbox & Test Data](/it/integration/sandbox-testing).", "example": "decline_document_expired" } } }, "examples": { "Arm": { "summary": "Attiva lo scenario AML di corrispondenza PEP", "value": { "scenario": "decline_aml_hit" } } } } } }, "responses": { "200": { "description": "Scenario attivato. I suoi valori magici si trovano ora nella sessione. `status` riflette lo stato corrente della sessione, che questa chiamata non modifica mai: in caso di successo è sempre `Not Started`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "scenario": { "type": "string", "description": "Lo slug dello scenario attivato (riproduce la richiesta)." }, "status": { "type": "string", "example": "Not Started" } } }, "examples": { "Armed": { "summary": "Scenario attivato su una sessione Not Started", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "scenario": "decline_aml_hit", "status": "Not Started" } } } } } }, "400": { "description": "Errore di validazione: slug dello scenario sconosciuto, oppure la sessione è già avanzata oltre `Not Started`.", "content": { "application/json": { "examples": { "Unknown Scenario": { "summary": "lo scenario non è presente nel catalogo", "value": { "scenario": [ "Unknown sandbox scenario: 'not-a-real-scenario'." ] } }, "Already Started": { "summary": "La sessione è avanzata oltre Not Started", "value": [ "Scenario can only be armed before the verification starts." ] } } } } }, "404": { "description": "Il Session-Token non corrisponde a questo `session_id`, oppure la sessione appartiene a un'applicazione di produzione (non-sandbox).", "content": { "application/json": { "examples": { "Not Found": { "summary": "Sessione live, oppure mancata corrispondenza tra session_id / token", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/sandbox/arm/ \\\n -H 'Session-Token: YOUR_SESSION_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"scenario\": \"decline_aml_hit\"\n }'" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/sandbox/arm/\",\n headers={\n \"Session-Token\": \"YOUR_SESSION_TOKEN\",\n \"Content-Type\": \"application/json\",\n },\n json={\"scenario\": \"decline_aml_hit\"},\n)\nresponse.raise_for_status()\nprint(response.json()) # {'session_id': '...', 'scenario': 'decline_aml_hit', 'status': 'Not Started'}" }, { "lang": "javascript", "label": "JavaScript", "source": "const response = await fetch(\n 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/sandbox/arm/',\n {\n method: 'POST',\n headers: {\n 'Session-Token': sessionToken,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ scenario: 'decline_aml_hit' }),\n },\n);\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst { session_id, scenario, status } = await response.json();" } ] } }, "/v3/session/{sessionId}/update-status/": { "patch": { "summary": "Approva, rifiuta o richiedi un nuovo invio per una sessione di verifica", "description": "Sovrascrivi manualmente la decisione finale di una sessione di verifica KYC o KYB. Imposta `new_status` su `Approved` o `Declined` per registrare una decisione manuale, oppure su `Resubmitted` per cancellare passaggi di verifica specifici e consentire all'utente di ripeterli tramite lo stesso URL di verifica. L'endpoint accetta sia ID di sessione utente (KYC) sia aziendali (KYB).\n\nChiamalo una volta che la sessione ha raggiunto uno stato revisionabile: lo stato attuale deve essere `Approved`, `Declined`, `In Review`, `Kyc Expired`, `Abandoned` o `Resubmitted`. Le sessioni che sono ancora `Not Started`, `In Progress` o `Awaiting User`, oppure che si sono concluse come `Expired`, restituiscono `400`. La tua chiave API deve avere l'autorizzazione `write:sessions` (una chiave API con ambito limitato necessita dell'accesso in scrittura alle decisioni). Il controllo sullo stato idoneo viene eseguito prima della validazione del corpo, quindi una sessione non idonea restituisce l'errore `Wrong Current Status` anche quando il payload non è valido.\n\nPer `Resubmitted`, passa `nodes_to_resubmit` per scegliere quali passaggi del workflow l'utente deve ripetere, oppure omettilo per selezionare automaticamente i tentativi di funzionalità esistenti in uno stato che consente il nuovo invio (`Declined`, `In Review`, `Not Finished`, `Expired`). Le funzionalità mai tentate non vengono selezionate automaticamente: elencale esplicitamente in `nodes_to_resubmit`, altrimenti la richiesta restituirà `400` se nessun tentativo registrato richiede un nuovo invio. I risultati precedenti dei passaggi selezionati vengono spostati nella cronologia del nuovo invio (restituita da Get Decision con `include=resubmissions`), i passaggi vengono riordinati per corrispondere al grafo del workflow, la finestra di scadenza della sessione viene riavviata e l'URL di verifica originale torna utilizzabile. I passaggi solo backend (`AML`, `DATABASE_VALIDATION`, `IP_ANALYSIS`) in cima all'elenco vengono eseguiti immediatamente senza interazione dell'utente; se ogni passaggio inviato nuovamente è solo backend, la sessione viene finalizzata nuovamente all'interno della stessa richiesta. `KYB_REGISTRY` e `KYB_KEY_PEOPLE` non possono essere inviati nuovamente in modo diretto: invia nuovamente le sessioni KYC figlie pertinenti e la sessione aziendale genitore verrà ricalcolata automaticamente.\n\nOgni chiamata che modifica lo stato attiva il [webhook](/it/integration/webhooks) `status.updated` una volta confermata la modifica e aggiunge una voce di attività (con l'attribuzione dell'autore e il tuo `comment`) alle `reviews` della sessione, visibile in [Get Decision](#get-/v3/session/-sessionId-/decision/) e nella cronologia attività della console. Vengono aggiornati anche gli aggregati del profilo utente collegati ai `vendor_data` della sessione. Rifiutare disabilita il monitoraggio AML continuo per la sessione; riapprovare lo riabilita (da `Resubmitted`, `Declined` o `Kyc Expired`) quando il monitoraggio è attivato nel workflow. Approvare o rifiutare un KYC figlio che appartiene a un controllo delle persone chiave KYB ricalcola lo stato della sessione aziendale genitore. Imposta `send_email: true` (con `email_address`) per notificare l'utente: un avviso di stato per `Approved`/`Declined`, o un'email di nuovo invio contenente il link di verifica e i motivi passaggio per passaggio per `Resubmitted`. Per verificare prima l'email, visualizzane l'anteprima con [Preview Decision Email](/it/sessions-api/preview-decision-email) (`Approved`, `Declined`) o [Preview Resubmission Email](/it/sessions-api/preview-resubmission) (`Resubmitted`) e passa il suo `preview_token` come `email_preview_token`: l'aggiornamento invierà esattamente l'email visualizzata in anteprima, oppure restituirà `409` prima di apportare qualsiasi modifica se l'email o la sessione sono cambiate rispetto all'anteprima o se la ricevuta ha più di 15 minuti.\n\nRipetere `Approved` o `Declined` su una sessione che ha già quello stato non modifica nulla e restituisce `200`: nessun webhook, nessuna voce di attività e nessuna email. Ripetere `Resubmitted` restituisce `400` (`The new status is the same as the current status.`). Credenziali mancanti o non valide e autorizzazioni mancanti restituiscono `403`; una chiave API con ambito limitato scaduta restituisce `401`.", "operationId": "patch_v3_session_update_status", "x-didit-sdk": { "resource": "sessions", "method": "update_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica da aggiornare. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB): il servizio risolve l'ID per entrambi i tipi di sessione.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string", "description": "Stato di destinazione. `Approved` e `Declined` registrano una decisione manuale definitiva (ciascuna può anche revocare l'altra). `Resubmitted` azzera i passaggi selezionati e rimanda la sessione all'utente. Qualsiasi altro valore restituisce `400`.", "enum": [ "Approved", "Declined", "Resubmitted" ], "example": "Approved" }, "comment": { "type": "string", "description": "Motivo della modifica in formato testo libero, memorizzato nella traccia di revisione della sessione e restituito nell'array `reviews` di [Get Decision](#get-/v3/session/-sessionId-/decision/). Ad esempio `Duplicated user`.", "example": "All checks passed manual review" }, "nodes_to_resubmit": { "type": "array", "description": "Passaggi del workflow che l'utente deve ripetere. Viene preso in considerazione solo quando `new_status` è `Resubmitted`. Per `Approved`/`Declined` le voci vengono comunque convalidate a livello di schema (un valore `feature` non valido restituisce `400`), ma le voci conformi allo schema vengono semanticamente ignorate. Se omesso, il server seleziona automaticamente i tentativi esistenti di OCR, Rilevamento della vitalità, Confronto facciale, Prova di residenza, Verifica telefonica, Verifica email, Screening AML, Validazione su database e Questionari il cui stato è `Declined`, `In Review`, `Not Finished` o `Expired` (i tentativi relativi a NFC, analisi IP, stima dell'età, ricerca facciale e documenti KYB non vengono mai selezionati automaticamente; i tentativi sul volto diversi dal confronto facciale vengono selezionati come `LIVENESS`) — le funzionalità che l'utente non ha mai tentato (nessun tentativo registrato) NON vengono selezionate, quindi una sessione con zero tentativi restituisce `400` (\"No features found that need resubmission\") anche se nulla è stato approvato; in tal caso, passa esplicitamente `nodes_to_resubmit`. I passaggi vengono eseguiti nell'ordine del grafo del workflow indipendentemente dall'ordine con cui li invii. `KYB_REGISTRY`, `KYB_KEY_PEOPLE` e l'alias `KYB` vengono rifiutati con `400` — tali controlli padre vengono ricalcolati a partire dalle relative sessioni KYC figlie.", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "Identificativo del nodo così come appare nella definizione del workflow della sessione (ad esempio `feature_ocr`, `feature_liveness`).", "example": "feature_ocr" }, "feature": { "type": "string", "description": "Tipo di funzionalità del nodo. Gli alias `ID_VERIFICATION`, `POA`, `PHONE` ed `EMAIL` vengono normalizzati lato server in `OCR`, `PROOF_OF_ADDRESS`, `PHONE_VERIFICATION` ed `EMAIL_VERIFICATION`. `KYB_REGISTRY`, `KYB_KEY_PEOPLE` e `KYB` superano la convalida dello schema ma vengono sempre rifiutati con l'errore di regola di business `400` mostrato negli esempi.", "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_DOCUMENTS", "ID_VERIFICATION", "POA", "PHONE", "EMAIL", "KYB_REGISTRY", "KYB_KEY_PEOPLE", "KYB", "GEOLOCATION" ], "example": "OCR" } } } }, "send_email": { "type": "boolean", "description": "Indica se inviare un'email all'utente in merito alla modifica. Richiede `email_address`. Per `Approved`/`Declined` l'utente riceve una notifica di stato; per `Resubmitted` l'email include il link di verifica e i motivi del nuovo invio specifici per ciascun passaggio.", "default": false, "example": false }, "email_address": { "type": "string", "format": "email", "description": "Destinatario dell'email di notifica. **Obbligatorio quando `send_email` è `true`**; se omesso restituisce `400`.", "example": "user@example.com" }, "email_language": { "type": "string", "description": "Lingua per l'email di notifica. Accetta qualsiasi stringa a livello di schema; i codici non supportati ripiegano silenziosamente sull'inglese (`en`).", "default": "en", "example": "en" }, "email_preview_token": { "type": "string", "writeOnly": true, "minLength": 1, "maxLength": 512, "description": "Ricevuta opzionale da [Preview Decision Email](/it/sessions-api/preview-decision-email) (per `Approved` e `Declined`) o da [Preview Resubmission Email](/it/sessions-api/preview-resubmission) (per `Resubmitted`): il relativo `preview_token`. Valida solo con `send_email: true`; in sua assenza la richiesta restituisce `400`. Il destinatario, la lingua, lo stato della sessione, il mittente e l'email (e, per un nuovo invio, i passaggi selezionati) devono comunque corrispondere all'anteprima, e la ricevuta scade dopo 15 minuti. In caso contrario, la richiesta restituisce `409` prima che la sessione venga modificata o che venga inviata un'email. Le integrazioni esistenti possono omettere questo campo." } } }, "examples": { "Approve Session": { "summary": "Approva una sessione dopo la revisione manuale", "value": { "new_status": "Approved", "comment": "All checks passed manual review" } }, "Decline Session": { "summary": "Rifiuta una sessione", "value": { "new_status": "Declined", "comment": "Suspected fraud" } }, "Resubmit Specific Steps": { "summary": "Richiedi nuovo invio per i passaggi scelti, con email", "value": { "new_status": "Resubmitted", "nodes_to_resubmit": [ { "node_id": "feature_ocr", "feature": "OCR" }, { "node_id": "feature_liveness", "feature": "LIVENESS" } ], "send_email": true, "email_address": "user@example.com", "email_language": "en" } }, "Resubmit Auto-select": { "summary": "Richiedi nuovo invio (selezione automatica dei passaggi non approvati)", "value": { "new_status": "Resubmitted" } }, "Approve With Previewed Email": { "summary": "Approva e invia l'email restituita da Preview Decision Email", "value": { "new_status": "Approved", "send_email": true, "email_address": "person@example.com", "email_language": "en", "email_preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } } } } }, "responses": { "200": { "description": "Stato aggiornato. La risposta contiene solo il `session_id`; recupera la sessione aggiornata tramite [Get Decision](#get-/v3/session/-sessionId-/decision/). Il webhook `status.updated` viene attivato dopo il commit della modifica. Ripetere `Approved` o `Declined` restituisce lo stesso corpo e non modifica nulla.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "UUID della sessione aggiornata." } } }, "examples": { "Updated": { "summary": "Restituito indistintamente per Approvata, Rifiutata e Reinviata", "value": { "session_id": "3472fb7c-8f7c-4d1a-9cf4-cf3d74ce1a60" } } } } } }, "400": { "description": "Errore di validazione. Gli errori di campo arrivano come `{\"\": [\"\"]}` (alcuni rifiuti delle regole di business utilizzano invece un valore stringa: `{\"nodes_to_resubmit\": \"\"}`), gli errori di transizione tra stati come `{\"detail\": \"\"}`, e l'errore per lo stesso stato come un semplice array JSON.", "content": { "application/json": { "examples": { "Wrong Current Status": { "summary": "La sessione non si trova in uno stato aggiornabile", "value": { "detail": "Only sessions with status Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted can be updated. Current status: In Progress" } }, "Invalid Status Value": { "summary": "new_status è uno stato di sessione valido ma non è uno tra Approved/Declined/Resubmitted", "value": { "new_status": [ "You can only update the status to 'Approved', 'Declined', or 'Resubmitted'." ] } }, "Missing new_status": { "summary": "Campo obbligatorio omesso", "value": { "new_status": [ "This field is required." ] } }, "Same Status": { "summary": "Nuovo invio richiesto su una sessione già reinviata", "value": [ "The new status is the same as the current status." ] }, "Email Address Required": { "summary": "send_email true senza email_address", "value": { "email_address": [ "Email address is required when send_email is true." ] } }, "Non-resubmittable Feature": { "summary": "Il nuovo invio ha come obiettivo un controllo padre KYB", "value": { "nodes_to_resubmit": "The following features cannot be resubmitted directly: KYB_REGISTRY. Resubmit the relevant child KYC sessions instead; the parent will recompute automatically." } }, "Nothing To Resubmit": { "summary": "La selezione automatica non ha trovato funzionalità non approvate", "value": { "nodes_to_resubmit": "No features found that need resubmission. All features are already approved." } }, "Invalid Feature Choice": { "summary": "Funzionalità sconosciuta in nodes_to_resubmit", "value": { "nodes_to_resubmit": [ { "feature": [ "\"BOGUS\" is not a valid choice. Valid choices are: OCR, OCR_BACK, NFC, AML, FACE, LIVENESS, FACE_MATCH, IP_ANALYSIS, AGE_ESTIMATION, PROOF_OF_ADDRESS, PHONE_VERIFICATION, EMAIL_VERIFICATION, FACE_SEARCH, DATABASE_VALIDATION, QUESTIONNAIRE, KYB_REGISTRY, KYB_DOCUMENTS, KYB_KEY_PEOPLE, ID_VERIFICATION, POA, PHONE, EMAIL, KYB" ] } ] } }, "Invalid Status Value (not a status at all)": { "summary": "new_status non è un valore valido di StatusChoices", "value": { "new_status": [ "\"Bogus\" is not a valid choice." ] } }, "Preview Receipt Without Email": { "summary": "email_preview_token inviato senza send_email: true", "value": { "email_preview_token": [ "A preview receipt is only valid when the email is sent." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chiave API con ambito oltre la sua data di scadenza", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenziali mancanti o autorizzazioni insufficienti, oppure un `session_id` che appartiene a un'altra applicazione.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "La chiave API non dispone dell'autorizzazione write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Non esiste alcuna sessione KYC o KYB con questo `session_id` (anche le sessioni eliminate restituiscono `404`).", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id sconosciuto", "value": { "detail": "Not found." } } } } } }, "429": { "description": "Un nuovo invio mirato esclusivamente a funzionalità solo backend (AML, DATABASE_VALIDATION, IP_ANALYSIS) è stato ripetuto entro la finestra di cooldown di 30 secondi; una ripetizione immediata non può modificare l'esito. Attendi e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Backend-only resubmit throttled": { "value": { "detail": "This session was already resubmitted for backend-only features within the last 30 seconds; repeating it cannot change the outcome. Wait before resubmitting again." } } } } } }, "409": { "description": "L'anteprima dell'email è cambiata o è scaduta. Genera una nuova anteprima prima di confermare; non viene apportata alcuna modifica alla sessione né eseguita alcuna consegna dell'email.", "content": { "application/json": { "examples": { "Preview Changed": { "summary": "La ricevuta non corrisponde più o è più vecchia di 15 minuti", "value": { "detail": "This email preview changed or expired. Preview the message again before confirming." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"new_status\": \"Approved\",\n \"comment\": \"All checks passed manual review\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_status(\n \"11111111-2222-3333-4444-555555555555\",\n new_status=\"Approved\",\n comment=\"All checks passed manual review\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateStatus(\"11111111-2222-3333-4444-555555555555\", {\n new_status: \"Approved\",\n comment: \"All checks passed manual review\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateStatusParams{\n\tNewStatus: \"Approved\",\n\tComment: didit.String(\"All checks passed manual review\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateStatus(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateStatusParams.builder()\n .newStatus(SessionsUpdateStatusParams.NewStatus.of(\"Approved\"))\n .comment(\"All checks passed manual review\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateStatus('11111111-2222-3333-4444-555555555555', [\n 'new_status' => 'Approved',\n 'comment' => 'All checks passed manual review',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_status(\n \"11111111-2222-3333-4444-555555555555\",\n new_status: \"Approved\",\n comment: \"All checks passed manual review\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateStatusParams\n{\n NewStatus = \"Approved\",\n Comment = \"All checks passed manual review\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/": { "post": { "summary": "Verifica dell'identità (OCR del documento + controlli antifrode)", "description": "Esegui l'OCR di un documento d'identità e i controlli antifrode sul documento in un'unica chiamata: restituisce i campi estratti del titolare, la MRZ analizzata, uno `status` `Approved`/`Declined`/`In Review` e un elenco `warnings` che spiega ogni problema riscontrato. Supporta 14,000+ tipi di documento da 220+ paesi e territori.\n\n**Come funziona.** Invia il `front_image` del documento (obbligatorio) e, per i documenti a due lati, il `back_image`. Carica foto non ritagliate con tutti e quattro gli angoli del documento visibili: il servizio rileva, allinea e ritaglia il documento autonomamente, quindi non ritagliarlo preventivamente. Il documento viene classificato automaticamente (non devi mai dichiarare il paese o il tipo di documento), la zona visiva viene letta tramite OCR e vengono decodificati la MRZ e gli eventuali codici a barre. I controlli incrociati convalidano quindi le date, i formati dei numeri e le cifre di controllo della MRZ, confrontando la zona visiva con la MRZ. Con `perform_document_liveness=true`, le immagini vengono inoltre analizzate per rilevare riproduzioni su schermo, copie stampate e manipolazioni del ritratto.\n\n**Logica decisionale.** Lo `status` è `Approved` a meno che almeno un avviso non determini un rifiuto. I rischi di frode e di errore grave portano sempre a un rifiuto: `DOCUMENT_EXPIRED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, oltre agli errori di estrazione (`NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`, `DOCUMENT_NUMBER_NOT_DETECTED`). (`PORTRAIT_IMAGE_NOT_DETECTED`, `INVALID_DATE` e `MRZ_NOT_DETECTED` esistono nelle sessioni dei workflow ma non vengono mai generati da questo endpoint autonomo. `COULD_NOT_DETECT_DOCUMENT_TYPE` viene restituito qui quando l'immagine frontale non corrisponde con elevata affidabilità al modello di un documento ufficiale noto, e rifiuta la richiesta.) Tre gruppi di rischio sono configurabili per richiesta tramite `invalid_mrz_action`, `inconsistent_data_action` ed `expiration_date_not_detected_action` (`DECLINE` o `NO_ACTION`). Tutti gli altri avvisi (ad es. `POSSIBLE_DUPLICATED_USER`) sono informativi e non causano mai un rifiuto da soli. Quando `perform_document_liveness=true` (il valore predefinito) e il controllo di contraffazione non restituisce un punteggio utilizzabile (il provider non è riuscito, ha risposto con uno stato diverso da 200 o ha risposto con HTTP 200 con `status=\"ERR\"`), la chiamata restituisce `200` con `status: \"In Review\"` e un avviso `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: \"warning\"`) invece di `Approved`: un controllo non eseguito non dimostra che il documento sia autentico. Questa escalation non è configurabile e non sovrascrive mai un `Declined`; con `perform_document_liveness=false` il controllo viene ignorato e lo stato segue gli avvisi rimanenti come in precedenza. Un documento che non può essere elaborato affatto restituisce `400` con `{\"error\": \"COULD_NOT_RECOGNIZE_DOCUMENT\"}`; un documento leggibile ma problematico restituisce `200` con `status: \"Declined\"`: controlla sempre `id_verification.status` e `id_verification.warnings`, non solo il codice HTTP.\n\n**Fatturazione.** Ciascuna risposta `200` consuma un credito dell'API di Verifica dell'identità (pagato con il credito del tuo piano o con il saldo di ricarica). Quando il saldo dell'organizzazione non copre la chiamata, l'endpoint restituisce `403` con l'errore di crediti insufficienti prima di qualsiasi elaborazione delle immagini.\n\n**Persistenza della sessione (`save_api_request`, predefinito `true`).** Quando è `true`, la chiamata viene salvata come sessione di tipo API: compare nella Business Console, il `request_id` restituito è un vero e proprio ID di sessione che puoi passare a `GET /v3/session/{sessionId}/decision/`, le immagini ritagliate del documento/ritratto vengono archiviate e restituite come URL multimediali temporanei (`https:///ocr/...`), e viene inviato un webhook `status.updated` agli endpoint webhook configurati. Quando è `false`, non viene memorizzato nulla, `request_id` è un UUID di correlazione monouso e `portrait_image`/`front_image`/`back_image` vengono restituiti inline come stringhe JPEG con codifica base64.\n\n**Sandbox.** Le chiavi API di sandbox ignorano qualsiasi elaborazione e fatturazione: dopo la validazione della richiesta (un input non valido restituisce comunque `400`), l'endpoint restituisce un payload fittizio statico `Approved` (una carta d'identità fittizia degli Stati Uniti per un \"Sandbox User\"), non viene salvata alcuna sessione e non viene consumato alcun credito.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`): questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il suo superamento restituisce `429`.", "operationId": "post_v3id-verification", "x-didit-sdk": { "resource": "id_verification", "method": "verify", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "front_image" ], "properties": { "front_image": { "type": "string", "format": "binary", "description": "Fronte del documento d'identità. Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `webp`, `pdf`. Dimensione massima di caricamento: **10 MB** (i file più grandi vengono rifiutati con `400`). I PDF vengono convertiti in immagine prima dell'OCR; i PDF crittografati richiedono `front_image_password`. Le immagini vengono compresse automaticamente a ~0.5 MB e viene applicato l'orientamento EXIF. Carica l'acquisizione completa e non ritagliata, con tutti e quattro gli angoli del documento visibili." }, "front_image_password": { "type": "string", "description": "Password per decrittografare `front_image` quando è un PDF crittografato. L'invio di un PDF crittografato senza password (o con una errata) restituisce `400`.", "writeOnly": true }, "back_image": { "type": "string", "format": "binary", "description": "Retro del documento: invialo ogni volta che il documento ne dispone (molte carte d'identità presentano la MRZ o un codice a barre sul retro; ometterlo lascia semplicemente vuoti la MRZ e i campi del retro nella risposta; questo endpoint non genera un avviso di MRZ mancante). Stesso formato e limiti di dimensione di `front_image`. Se omesso, `back_image` e i campi del retro risultano `null` nella risposta." }, "back_image_password": { "type": "string", "description": "Password per decrittografare `back_image` quando è un PDF crittografato.", "writeOnly": true }, "perform_document_liveness": { "type": "boolean", "default": true, "description": "Esegue lo screening di entrambe le immagini per rilevare frodi di presentazione: riproduzioni da schermo (`SCREEN_CAPTURE_DETECTED`), copie stampate (`PRINTED_COPY_DETECTED`) e manipolazione del ritratto (`PORTRAIT_MANIPULATION_DETECTED`). Ognuna di queste comporta il rifiuto automatico. Abilitato per impostazione predefinita; imposta su `false` per saltare lo screening antifrode e ridurre la latenza. Quando è abilitato e il provider non restituisce alcun punteggio utilizzabile, la risposta è `In Review` con un avviso `DOCUMENT_LIVENESS_NOT_COMPUTED` anziché `Approved`.", "example": true }, "minimum_age": { "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 120, "description": "Accettato e convalidato (1–120) ma **attualmente non applicato** da questo endpoint — non produce mai un avviso `MINIMUM_AGE_NOT_MET` da questo campo. Applica le regole sull'età a partire da `date_of_birth`/`age` restituiti, oppure utilizza un workflow di sessione di verifica con restrizioni di età." }, "expiration_date_not_detected_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Cosa fare quando non è possibile leggere alcuna data di scadenza (`EXPIRATION_DATE_NOT_DETECTED`). Il valore predefinito è `NO_ACTION` perché molti documenti di identità non riportano alcuna data di scadenza stampata. Nota: una data di scadenza *rilevata e trascorsa* comporta sempre il rifiuto (`DOCUMENT_EXPIRED`), indipendentemente da questa opzione." }, "invalid_mrz_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "DECLINE", "description": "Cosa fare quando la MRZ estratta non supera la convalida delle cifre di controllo (`MRZ_VALIDATION_FAILED`). Una MRZ mancante non genera alcun avviso su questo endpoint. Rilevante solo per i documenti che contengono una MRZ. `REVIEW` non è supportato su questo endpoint e restituisce `400`." }, "inconsistent_data_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "DECLINE", "description": "Cosa fare quando i dati estratti sono internamente incoerenti: `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` (la zona visiva non concorda con la MRZ) o `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`." }, "critical_field_occlusion_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "DECLINE", "description": "Cosa fare quando un campo stampato critico è stato fisicamente coperto nell'acquisizione (`CRITICAL_FIELD_OCCLUSION_DETECTED`) - un numero di identità, un nome, la data di nascita o la data di scadenza. Rifiuta per impostazione predefinita, come gli altri rischi di integrità del documento di questo endpoint: coprire i numeri rispetto ai quali viene riconciliato un report è l'aspetto tipico di un documento oscurato. Il valore letto per un campo coperto viene comunque escluso dall'estrazione, quindi l'avviso `*_NOT_DETECTED` corrispondente di solito lo accompagna. `REVIEW` non è supportato su questo endpoint e restituisce `400`." }, "document_or_personal_number_format_mismatch_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Cosa fare quando un numero non corrisponde al formato utilizzato dall'autorità emittente per quel tipo di documento (`DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH`). Il valore predefinito è `NO_ACTION`, che segnala l'avviso senza modificare lo stato. `REVIEW` non è supportato su questo endpoint e restituisce `400`." }, "preferred_characters": { "type": "string", "enum": [ "latin", "non_latin" ], "default": "latin", "description": "Sistema di scrittura preferito per i campi nome/indirizzo sui documenti che stampano sia testo in caratteri latini sia in caratteri non latini (arabo, cirillico, CJK, …). `latin` restituisce valori traslitterati/latini; `non_latin` preferisce il sistema di scrittura nativo." }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando è `true` (predefinito), rende persistente la chiamata come sessione di tipo API — visibile nella Business Console, recuperabile tramite `GET /v3/session/{sessionId}/decision/` utilizzando il `request_id` restituito, notificata tramite un webhook `status.updated`, e con le immagini del documento restituite come URL multimediali. Quando è `false`, non viene memorizzato nulla, `request_id` è un UUID temporaneo e le immagini vengono restituite inline come stringhe JPEG in base64.", "example": true }, "vendor_data": { "type": "string", "description": "Stringa opaca opzionale (il tuo ID utente interno, email, UUID...) memorizzata nella sessione persistita e restituita nella risposta. Usala per correlare le chiamate API con i tuoi record e per filtrare le sessioni in un secondo momento.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON (ad es. `metadata={\"flow\":\"onboarding\"}`): viene interpretato come oggetto.", "example": { "flow": "onboarding" } } } }, "example": { "front_image": "(binary JPEG/PNG/PDF of the document front)", "back_image": "(binary JPEG/PNG/PDF of the document back)", "perform_document_liveness": true, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "onboarding" } } } } }, "responses": { "200": { "description": "Documento elaborato. `id_verification.status` è `Approved`, `Declined` o `In Review`; ogni problema rilevato è dettagliato in `id_verification.warnings`. Viene restituito `In Review` quando un controllo del rilevamento della vitalità del documento richiesto non ha prodotto alcun risultato utilizzabile (`DOCUMENT_LIVENESS_NOT_COMPUTED`). Un documento problematico restituisce comunque `200` con `status: \"Declined\"` — esamina il corpo, non solo il codice HTTP. Quando `save_api_request=true`, `request_id` è l'ID di sessione persistito e i campi immagine sono URL multimediali di breve durata; con `save_api_request=false` sono stringhe JPEG base64 inline.", "content": { "application/json": { "examples": { "Approved": { "summary": "Carta d'identità fronte-retro letta chiaramente (salvata — immagini come URL dei contenuti multimediali)", "value": { "request_id": "11d219ed-d59c-4b1d-8d65-9b933f12d5b8", "id_verification": { "status": "Approved", "document_type": "Identity Card", "document_subtype": "ID_CARD_GENERIC", "document_number": "CBX164224", "personal_number": "20446581H", "portrait_image": "https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=...", "front_image": "https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=...", "back_image": "https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=...", "front_image_camera_front": null, "back_image_camera_front": null, "front_image_camera_front_face_match_score": null, "back_image_camera_front_face_match_score": null, "front_image_quality_score": { "focus_score": 78.0, "brightness_score": 83.2, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 40.7, "overall_score": 70.2 }, "back_image_quality_score": { "focus_score": 100.0, "brightness_score": 95.6, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 43.0, "overall_score": 84.4 }, "date_of_birth": "1980-01-13", "age": 46, "expiration_date": "2032-03-31", "date_of_issue": "2022-03-31", "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "Julio Francisco", "last_name": "Fores Sena", "full_name": "Julio Francisco Fores Sena", "gender": "M", "address": "Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife", "formatted_address": "Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain", "place_of_birth": "Valencia, Valencia", "marital_status": "UNKNOWN", "nationality": "ESP", "extra_fields": { "first_surname": "Fores", "second_surname": "Sena" }, "mrz": { "surname": "FORES SENA", "name": "JULIO FRANCISCO", "country": "ESP", "nationality": "ESP", "birth_date": "800113", "expiry_date": "320331", "sex": "M", "document_type": "ID", "document_number": "CBX164224", "optional_data": "20446581H", "optional_data_2": "", "birth_date_hash": "9", "expiry_date_hash": "8", "document_number_hash": "3", "final_hash": "3", "personal_number": "20446581H", "warnings": [], "errors": [], "mrz_type": "TD1", "mrz_string": "IDESPCBX164224320446581H<<<<<<\n8001139M3203318ESP<<<<<<<<<<<3\nFORES/ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-portrait_image-1d9a.jpg?signature=...", "front_image": "https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-front_image-5c2b.jpg?signature=...", "back_image": null, "front_image_camera_front": null, "back_image_camera_front": null, "front_image_camera_front_face_match_score": null, "back_image_camera_front_face_match_score": null, "front_image_quality_score": { "focus_score": 100.0, "brightness_score": 95.7, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 22.2, "overall_score": 79.3 }, "back_image_quality_score": null, "date_of_birth": "1997-01-30", "age": 29, "expiration_date": "2025-11-26", "date_of_issue": null, "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "Lucia", "last_name": "Marin Castro", "full_name": "Lucia Marin Castro", "gender": "F", "address": null, "formatted_address": null, "place_of_birth": null, "marital_status": "UNKNOWN", "nationality": "ESP", "extra_fields": { "first_surname": "Marin", "second_surname": "Castro" }, "mrz": {}, "parsed_address": null, "warnings": [ { "risk": "DOCUMENT_EXPIRED", "feature": "ID_VERIFICATION", "additional_data": null, "log_type": "error", "short_description": "Document expired", "long_description": "The document's expiration date has passed, rendering it no longer valid for use." } ], "barcodes": [] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:25:48.117204+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo." }, "id_verification": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "`Approved` quando nessun avviso si traduce in un rifiuto e il controllo di vitalità del documento richiesto ha prodotto un risultato utilizzabile; `In Review` quando tale controllo richiesto non ha prodotto alcun risultato utilizzabile (`DOCUMENT_LIVENESS_NOT_COMPUTED`); `Declined` quando un avviso si traduce in un rifiuto: l'elenco `warnings` ne spiega il motivo." }, "document_type": { "type": "string", "nullable": true, "description": "Nome visualizzato del tipo di documento rilevato: `Identity Card`, `Passport`, `Driver's License`, `Residence Permit`, `Health Insurance Card` o `Tax Card`. `null` quando non è stato possibile classificare il documento.", "example": "Identity Card" }, "document_subtype": { "type": "string", "nullable": true, "description": "Sottotipo più dettagliato quando disponibile (ad es. `ID_CARD_GENERIC`, `EPASSPORT`).", "example": "ID_CARD_GENERIC" }, "document_number": { "type": "string", "nullable": true, "example": "CBX164224" }, "personal_number": { "type": "string", "nullable": true, "description": "Numero personale/nazionale secondario stampato su alcuni documenti.", "example": "20446581H" }, "portrait_image": { "type": "string", "nullable": true, "description": "Foto ritagliata del ritratto dal documento. Un URL multimediale a breve durata (`https:///ocr/...`) quando `save_api_request=true` (predefinito); una stringa JPEG inline codificata in base64 quando `save_api_request=false`. `null` se non è stato rilevato alcun ritratto." }, "front_image": { "type": "string", "nullable": true, "description": "Ritaglio allineato del fronte del documento. URL multimediale quando salvato, JPEG base64 inline altrimenti." }, "back_image": { "type": "string", "nullable": true, "description": "Ritaglio allineato del retro del documento. `null` quando non è stato caricato alcun `back_image`." }, "front_image_camera_front": { "type": "string", "nullable": true, "description": "Sempre `null` su questo endpoint (compilato solo nelle sessioni di verifica con acquisizione da fotocamera)." }, "back_image_camera_front": { "type": "string", "nullable": true, "description": "Sempre `null` su questo endpoint." }, "front_image_camera_front_face_match_score": { "type": "number", "nullable": true, "description": "Sempre `null` su questo endpoint." }, "back_image_camera_front_face_match_score": { "type": "number", "nullable": true, "description": "Sempre `null` su questo endpoint." }, "front_image_quality_score": { "type": "object", "nullable": true, "description": "Diagnostica della qualità di acquisizione per l'immagine caricata (`null` quando il lato non è stato fornito o il calcolo del punteggio non è riuscito). Tutti i punteggi vanno da 0 a 100.", "properties": { "focus_score": { "type": "number", "format": "float", "description": "Nitidezza del ritaglio del documento (più alta è, maggiore è la nitidezza)." }, "brightness_score": { "type": "number", "format": "float", "description": "Qualità dell'esposizione (più alta è migliore)." }, "brightness_issue": { "type": "string", "nullable": true, "description": "`ok` quando l'esposizione è adeguata, altrimenti il problema rilevato (ad es. troppo scura / troppo luminosa)." }, "is_document_fully_visible": { "type": "boolean", "nullable": true, "description": "Indica se tutti e quattro gli angoli del documento si trovano all'interno dell'inquadratura." }, "resolution_score": { "type": "number", "format": "float", "description": "Risoluzione effettiva dell'area del documento." }, "overall_score": { "type": "number", "format": "float", "description": "Punteggio di qualità aggregato." } } }, "back_image_quality_score": { "type": "object", "nullable": true, "description": "Diagnostica della qualità di acquisizione per l'immagine caricata (`null` quando il lato non è stato fornito o il calcolo del punteggio non è riuscito). Tutti i punteggi vanno da 0 a 100.", "properties": { "focus_score": { "type": "number", "format": "float", "description": "Nitidezza del ritaglio del documento (più alta è, maggiore è la nitidezza)." }, "brightness_score": { "type": "number", "format": "float", "description": "Qualità dell'esposizione (più alta è migliore)." }, "brightness_issue": { "type": "string", "nullable": true, "description": "`ok` quando l'esposizione è adeguata, altrimenti il problema rilevato (ad es. troppo scura / troppo luminosa)." }, "is_document_fully_visible": { "type": "boolean", "nullable": true, "description": "Indica se tutti e quattro gli angoli del documento si trovano all'interno dell'inquadratura." }, "resolution_score": { "type": "number", "format": "float", "description": "Risoluzione effettiva dell'area del documento." }, "overall_score": { "type": "number", "format": "float", "description": "Punteggio di qualità aggregato." } } }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "example": "1980-01-13" }, "age": { "type": "integer", "nullable": true, "description": "Età del titolare in anni, calcolata da `date_of_birth`.", "example": 46 }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "example": "2032-03-31" }, "date_of_issue": { "type": "string", "format": "date", "nullable": true, "example": "2022-03-31" }, "issuing_state": { "type": "string", "nullable": true, "description": "Paese di emissione (ISO 3166-1 alpha-3).", "example": "ESP" }, "issuing_state_name": { "type": "string", "nullable": true, "example": "Spain" }, "first_name": { "type": "string", "nullable": true, "example": "Julio Francisco" }, "last_name": { "type": "string", "nullable": true, "example": "Fores Sena" }, "full_name": { "type": "string", "nullable": true, "example": "Julio Francisco Fores Sena" }, "gender": { "type": "string", "nullable": true, "description": "`M`, `F` o `null` quando non stampato/rilevato.", "example": "M" }, "address": { "type": "string", "nullable": true, "description": "Indirizzo esattamente come stampato sul documento." }, "formatted_address": { "type": "string", "nullable": true, "description": "Versione geocodificata e normalizzata di `address`." }, "place_of_birth": { "type": "string", "nullable": true, "example": "Valencia, Valencia" }, "marital_status": { "type": "string", "nullable": true, "description": "`UNKNOWN` a meno che il documento non riporti lo stato civile.", "example": "UNKNOWN" }, "nationality": { "type": "string", "nullable": true, "description": "Nazionalità del titolare (ISO 3166-1 alpha-3).", "example": "ESP" }, "extra_fields": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Dati aggiuntivi specifici del documento privi di una colonna dedicata (ad es. `first_surname`/`second_surname` sui documenti di identità spagnoli, categorie di patente sulle patenti di guida)." }, "mrz": { "type": "object", "description": "Zona a lettura ottica analizzata. Un **oggetto vuoto** (`{}`) quando il documento non ha una MRZ o non è stato possibile leggerla — in tal caso controlla anche l'elenco `warnings`. Le date all'interno della MRZ utilizzano il formato grezzo `YYMMDD`.", "properties": { "surname": { "type": "string", "example": "FORES SENA" }, "name": { "type": "string", "example": "JULIO FRANCISCO" }, "country": { "type": "string", "description": "Paese di emissione (ISO 3166-1 alpha-3).", "example": "ESP" }, "nationality": { "type": "string", "description": "Nazionalità del titolare (ISO 3166-1 alpha-3).", "example": "ESP" }, "birth_date": { "type": "string", "description": "Data di nascita MRZ non elaborata (`YYMMDD`).", "example": "800113" }, "expiry_date": { "type": "string", "description": "Data di scadenza MRZ non elaborata (`YYMMDD`).", "example": "320331" }, "sex": { "type": "string", "example": "M" }, "document_type": { "type": "string", "description": "Codice del tipo di documento MRZ (ad es. `ID`, `P`).", "example": "ID" }, "document_number": { "type": "string", "example": "CBX164224" }, "optional_data": { "type": "string", "nullable": true, "example": "20446581H" }, "optional_data_2": { "type": "string", "nullable": true, "example": "" }, "birth_date_hash": { "type": "string", "description": "Cifra di controllo MRZ per la data di nascita.", "example": "9" }, "expiry_date_hash": { "type": "string", "description": "Cifra di controllo MRZ per la data di scadenza.", "example": "8" }, "document_number_hash": { "type": "string", "description": "Cifra di controllo MRZ per il numero del documento.", "example": "3" }, "final_hash": { "type": "string", "description": "Cifra di controllo MRZ composita.", "example": "3" }, "personal_number": { "type": "string", "nullable": true, "example": "20446581H" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Avvisi non fatali relativi all'analisi del codice MRZ." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Errori di parsing/cifra di controllo MRZ. Gli errori non vuoti vengono segnalati come avviso `MRZ_VALIDATION_FAILED`." }, "mrz_type": { "type": "string", "description": "Formato MRZ: `TD1` (carte d'identità, 3 righe), `TD2` o `TD3` (passaporti, 2 righe).", "example": "TD1" }, "mrz_string": { "type": "string", "description": "Testo MRZ non elaborato così come letto, righe separate da `\\n`." }, "mrz_key": { "type": "string", "description": "Chiave composita (numero del documento + cifre di controllo) utilizzata per i controlli incrociati." } } }, "parsed_address": { "type": "object", "nullable": true, "description": "Suddivisione geocodificata e strutturata di `address`. `null` se il documento non contiene alcun indirizzo o se non è stato possibile analizzarlo.", "properties": { "street_1": { "type": "string", "nullable": true, "example": "Avenida el Cardonal 52" }, "street_2": { "type": "string", "nullable": true, "example": "b" }, "city": { "type": "string", "nullable": true, "example": "La Laguna" }, "region": { "type": "string", "nullable": true, "example": "Canarias" }, "country": { "type": "string", "nullable": true, "description": "Codice paese ISO 3166-1 alpha-2.", "example": "ES" }, "postal_code": { "type": "string", "nullable": true, "example": "38108" }, "address_type": { "type": "string", "nullable": true, "example": "Avenida" }, "formatted_address": { "type": "string", "nullable": true, "description": "Stringa dell'indirizzo geocodificato canonico.", "example": "Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain" }, "raw_results": { "type": "object", "additionalProperties": true, "description": "Payload di geocodifica non elaborato (`address_components`, `geometry.location`, `place_id`, …) per utilizzi avanzati." }, "document_location": { "type": "object", "nullable": true, "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "description": "Coordinate geocodificate dell'indirizzo del documento." }, "label": { "type": "string", "nullable": true, "description": "Da quale campo del documento è stato letto l'indirizzo.", "example": "Spain Identity Card Address" }, "is_verified": { "type": "boolean", "description": "Indica se la geocodifica ha confermato l'esistenza dell'indirizzo." }, "category": { "type": "string", "nullable": true, "description": "Categoria dell'indirizzo (ad es. `Residential`, `Commercial`).", "example": "Residential" } } }, "warnings": { "type": "array", "description": "Vuoto in caso di approvazione senza anomalie. Ogni voce illustra un rischio rilevato; le voci con `log_type: \"error\"` impostano `status` su `Declined`, mentre `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: \"warning\"`) lo imposta su `In Review`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "description": "Codice di rischio leggibile dalla macchina. Rischi con rifiuto automatico: `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT` (solo 400, mai un avviso), `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`. Regolati dalle opzioni della richiesta: `MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED` (`invalid_mrz_action`), `DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` (`inconsistent_data_action`), `EXPIRATION_DATE_NOT_DETECTED` (`expiration_date_not_detected_action`). Altri rischi (es. `POSSIBLE_DUPLICATED_USER`) sono informativi. `DOCUMENT_LIVENESS_NOT_COMPUTED` viene generato quando `perform_document_liveness=true` ma il controllo di contraffazione non ha restituito alcun punteggio utilizzabile; imposta `status` su `In Review`. `COULD_NOT_DETECT_DOCUMENT_TYPE` viene restituito anche quando il fronte del documento non corrisponde con elevata affidabilità al modello di un documento ufficiale noto, ad esempio un documento modificato, generato al computer o con un modello non ancora supportato.", "example": "DOCUMENT_EXPIRED" }, "feature": { "type": "string", "enum": [ "ID_VERIFICATION" ], "description": "Funzionalità che ha generato l'avviso. Sempre `ID_VERIFICATION` su questo endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contesto aggiuntivo per alcuni rischi (ad es. `POSSIBLE_DUPLICATED_USER` include `duplicated_session_id`); `null` per la maggior parte." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravità. Gli avvisi `error` portano `status` a `Declined`; `warning` (solo `DOCUMENT_LIVENESS_NOT_COMPUTED`, quando il controllo anti-manomissione richiesto non ha prodotto un punteggio utilizzabile) porta `status` a `In Review`; le voci `information` sono informative e non modificano mai lo stato." }, "short_description": { "type": "string", "description": "Riepilogo del rischio su una riga leggibile dall'utente." }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura del rischio." } } } }, "barcodes": { "type": "array", "description": "Codici a barre decodificati dal documento (PDF417, QR, …). Vuoto se il documento non ne contiene o non è stato possibile leggerne alcuno.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo di codice a barre (ad es. `PDF417`, `QR_CODE`, `UNKNOWN`)." }, "position": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Posizione del codice a barre nell'immagine, quando disponibile." }, "data": { "type": "string", "description": "Payload decodificato." }, "data_raw": { "type": "string", "description": "Payload non elaborato (non decodificato), se diverso." }, "side": { "type": "string", "nullable": true, "description": "`front` o `back`." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, o `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco dell'oggetto `metadata` inviato, o `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp ISO 8601 (UTC) di generazione della risposta." } } } } } }, "400": { "description": "Errore di validazione o di elaborazione. I problemi a livello di campo restituiscono l'envelope standard di DRF (un array di messaggi per ciascun campo interessato). I problemi relativi a PDF crittografati restituiscono `{\"detail\": ...}`. Un'immagine del documento in cui non è possibile riconoscere alcun documento restituisce `{\"error\": \"COULD_NOT_RECOGNIZE_DOCUMENT\"}`. I caricamenti di PDF possono inoltre non riuscire con \"The submitted PDF file is corrupted or invalid.\" o con un errore di assenza di pagine.", "content": { "application/json": { "examples": { "Missing front image": { "summary": "`front_image` non incluso nei dati del modulo", "value": { "front_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Estensione del file diversa da tiff/jpg/jpeg/png/webp/pdf", "value": { "front_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf." ] } }, "File too large": { "summary": "Il caricamento supera il limite di 10 MB", "value": { "front_image": [ "File size should not exceed 10 MB" ] } }, "Invalid option value": { "summary": "Le opzioni accettano solo DECLINE o NO_ACTION", "value": { "invalid_mrz_action": [ "\"REVIEW\" is not a valid choice." ] } }, "Encrypted PDF": { "summary": "PDF caricato senza la password richiesta", "value": { "detail": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Wrong PDF password": { "summary": "`front_image_password` / `back_image_password` non decifra il PDF", "value": { "detail": "The PDF password is incorrect. Please provide the correct password." } }, "Document not recognized": { "summary": "Nessun documento d'identità rilevato nell'immagine", "value": { "error": "COULD_NOT_RECOGNIZE_DOCUMENT" } }, "PDF conversion failure": { "summary": "Impossibile convertire il PDF caricato in un'immagine", "value": { "error": "Failed to convert front image PDF." } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi elaborazione delle immagini.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/id-verification/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'front_image=@./id_front.jpg' \\\n -F 'back_image=@./id_back.jpg' \\\n -F 'perform_document_liveness=true' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_verification.verify(\n front_image=open(\"front_image.jpg\", \"rb\"),\n back_image=open(\"back_image.jpg\", \"rb\"),\n perform_document_liveness=True,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"onboarding\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idVerification.verify({\n front_image: await fileFromPath(\"front_image.jpg\"),\n back_image: await fileFromPath(\"back_image.jpg\"),\n perform_document_liveness: true,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"onboarding\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{\n\tFrontImage: didit.FileFromPath(\"front_image.jpg\"),\n\tBackImage: didit.Some(didit.FileFromPath(\"back_image.jpg\")),\n\tPerformDocumentLiveness: didit.Bool(true),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"onboarding\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.IdVerificationVerifyParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idVerification().verify(IdVerificationVerifyParams.builder()\n .frontImage(Path.of(\"front_image.jpg\"))\n .backImage(Path.of(\"back_image.jpg\"))\n .performDocumentLiveness(true)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"onboarding\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idVerification->verify([\n 'front_image' => File::fromPath('front_image.jpg'),\n 'back_image' => File::fromPath('back_image.jpg'),\n 'perform_document_liveness' => true,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'onboarding'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_verification.verify(\n front_image: Pathname(\"front_image.jpg\"),\n back_image: Pathname(\"back_image.jpg\"),\n perform_document_liveness: true,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"onboarding\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams\n{\n FrontImage = FileUpload.FromPath(\"front_image.jpg\"),\n BackImage = FileUpload.FromPath(\"back_image.jpg\"),\n PerformDocumentLiveness = true,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"onboarding\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/face-match/": { "post": { "summary": "Confronto facciale", "description": "Confronta due immagini di volti (1:1) e ottieni un punteggio (`score`) di somiglianza (0–100) oltre a uno stato (`status`) `Approved`/`Declined`.\n\n**Come funziona.** Entrambe le immagini vengono decodificate e analizzate da un modello biometrico (imposta `rotate_image=true` se le acquisizioni potrebbero essere ruotate o capovolte), quindi viene calcolato un punteggio di somiglianza tra i due volti. Un punteggio **strettamente superiore** a `face_match_score_decline_threshold` (predefinito `30`) restituisce `status: \"Approved\"`; un punteggio pari o inferiore restituisce `Declined` con un avviso `LOW_FACE_MATCH_SIMILARITY`. Se non è possibile calcolare il punteggio per nessuna coppia di volti, la chiamata restituisce comunque `200` con `status: \"Declined\"` e un avviso `NO_REFERENCE_IMAGE` — `score` è `null` sul percorso di salvataggio predefinito, o `0` con `save_api_request=false`. Per ottenere risultati ottimali, invia un unico volto nitido e rivolto frontalmente per immagine.\n\n**Fatturazione.** Ciascuna risposta `200` consuma un credito API di Confronto facciale (scalato dal credito del piano o dal saldo delle ricariche). Se il saldo dell'organizzazione non copre la chiamata, l'endpoint restituisce `403` con l'errore di crediti insufficienti prima di qualsiasi elaborazione delle immagini.\n\n**Persistenza della sessione (`save_api_request`, predefinito `true`).** Quando è `true`, la chiamata viene salvata come sessione di tipo API: compare nella Business Console, il `request_id` restituito è un ID di sessione reale che puoi passare a `GET /v3/session/{sessionId}/decision/`, entrambe le immagini vengono archiviate come immagini sorgente/destinazione del confronto facciale della sessione e viene emesso un webhook `status.updated` verso le tue destinazioni webhook configurate. Quando è `false`, non viene memorizzato nulla e `request_id` è un UUID di correlazione monouso che non può essere consultato in seguito.\n\n**Indice di ricerca facciale.** Questo endpoint non registra mai volti nel tuo indice di ricerca facciale e non esegue mai screening di blocklist o duplicati — usa `POST /v3/passive-liveness/` o `POST /v3/face-search/` per queste operazioni.\n\n**Sandbox.** Le chiavi API sandbox ignorano ogni elaborazione e fatturazione: dopo la validazione della richiesta (l'input malformato restituisce comunque `400`), l'endpoint restituisce un payload fittizio statico `Approved`, non viene salvata alcuna sessione e non viene consumato alcun credito.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Limite condiviso per le operazioni di scrittura di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`.", "operationId": "post_v3face-match", "x-didit-sdk": { "resource": "face_match", "method": "compare", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image", "ref_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "Immagine del volto dal vivo o candidata da verificare (es. un selfie). Invia una singola foto frontale con il volto del soggetto chiaramente visibile e ben illuminato. Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Dimensione massima di caricamento: **5 MB** (i file più grandi vengono rifiutati con `400`). Le immagini vengono compresse automaticamente a circa 0,5 MB prima dell'elaborazione, quindi risoluzioni molto elevate non migliorano la precisione." }, "ref_image": { "type": "string", "format": "binary", "description": "Immagine del volto di riferimento con cui effettuare il confronto (es. la fototessera di un documento d'identità o una foto registrata in precedenza). Stessi limiti di formato e dimensione di `user_image`." }, "face_match_score_decline_threshold": { "type": "number", "format": "float", "default": 30, "minimum": 0, "maximum": 100, "description": "Soglia di somiglianza (0–100) che determina lo `status` della risposta. Un punteggio calcolato **pari o inferiore** a questo valore imposta `status` su `Declined` e aggiunge un avviso `LOW_FACE_MATCH_SIMILARITY`; un punteggio rigorosamente superiore restituisce `Approved`. Il valore predefinito `30` è permissivo — aumentalo (ad es. `50`–`60`) per una verifica più rigorosa. I valori al di fuori di 0–100 restituiscono `400`.", "example": 50 }, "rotate_image": { "type": "boolean", "default": false, "description": "Quando è `true`, il servizio prova le immagini di input con incrementi di 90 gradi (0, 90, 180, 270) e utilizza l'orientamento che offre il miglior rilevamento del volto; utile per le acquisizioni da dispositivo mobile prive di orientamento EXIF. Aggiunge latenza, quindi attivalo solo se non puoi garantire immagini orientate correttamente.", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando è `true` (predefinito), rende persistente la chiamata come sessione di tipo API — visibile nella Business Console, recuperabile tramite `GET /v3/session/{sessionId}/decision/` utilizzando il `request_id` restituito, e notificata tramite un webhook `status.updated`. Quando è `false`, non viene memorizzato nulla e `request_id` è un UUID temporaneo utilizzabile solo per la correlazione della risposta.", "example": true }, "vendor_data": { "type": "string", "description": "Stringa opaca opzionale (il tuo ID utente interno, email, UUID...) memorizzata nella sessione persistita e restituita nella risposta. Usala per correlare le chiamate API con i tuoi record e per filtrare le sessioni in un secondo momento.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON (ad es. `metadata={\"flow\":\"login\"}`) — viene interpretato come oggetto.", "example": { "flow": "login", "device_id": "abc123" } } } }, "example": { "user_image": "(binary JPEG/PNG of the live selfie)", "ref_image": "(binary JPEG/PNG of the reference photo)", "face_match_score_decline_threshold": 50, "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "login" } } } } }, "responses": { "200": { "description": "Confronto facciale calcolato. `face_match.score` è un numero decimale compreso tra 0 e 100 (due cifre decimali); `status` è `Approved` quando il punteggio è strettamente superiore a `face_match_score_decline_threshold`, altrimenti `Declined` con un avviso esplicativo. Una coppia con bassa somiglianza o non valutabile restituisce comunque `200`: esamina `face_match.status` e `face_match.warnings`, non solo il codice HTTP. Quando `save_api_request=true`, `request_id` è l'ID della sessione salvata.", "content": { "application/json": { "examples": { "Approved": { "summary": "Stessa persona — punteggio superiore alla soglia", "value": { "request_id": "f9f5a777-8002-44c6-baaf-128bcfd6e226", "face_match": { "status": "Approved", "score": 99.41, "user_image": { "entities": [ { "bbox": [ 661, 728, 1688, 2188 ], "confidence": 0.732973, "age": 26.91, "gender": "male", "race": null } ], "best_angle": 0 }, "ref_image": { "entities": [ { "bbox": [ 653, 745, 1691, 2185 ], "confidence": 0.722082, "age": 27.0, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": "user-123", "metadata": { "flow": "login" }, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Declined - low similarity": { "summary": "Punteggio pari o inferiore alla soglia di rifiuto", "value": { "request_id": "7cdda24e-311a-46d3-a3bb-e5d9b564ce73", "face_match": { "status": "Declined", "score": 24.87, "user_image": { "entities": [ { "bbox": [ 661, 728, 1688, 2188 ], "confidence": 0.732973, "age": 26.91, "gender": "male", "race": null } ], "best_angle": 0 }, "ref_image": { "entities": [ { "bbox": [ 156, 234, 679, 898 ], "confidence": 0.717775, "age": 41.2, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [ { "risk": "LOW_FACE_MATCH_SIMILARITY", "feature": "FACEMATCH", "additional_data": null, "log_type": "error", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:08:19.859116+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo." }, "face_match": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Approved` quando il punteggio di somiglianza è strettamente superiore a `face_match_score_decline_threshold` ed è stato possibile calcolare un punteggio; `Declined` in caso contrario (un avviso ne spiega il motivo)." }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Punteggio di somiglianza da 0 a 100 — la confidenza del modello che entrambe le immagini ritraggano la stessa persona. Arrotondato a due decimali solo quando `save_api_request` è true; con `save_api_request=false` viene restituito il float non elaborato. `null` quando non è stato possibile calcolare il punteggio per nessuna coppia di volti (con il valore predefinito `save_api_request=true`); con `save_api_request=false` la stessa condizione può presentarsi come `score: 0`. In entrambi i casi è presente un avviso `NO_REFERENCE_IMAGE` e `status` è `Declined`.", "example": 99.41 }, "user_image": { "type": "object", "description": "Risultati del rilevamento facciale per le immagini analizzate.", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Riquadro di delimitazione del volto rilevato come coordinate in pixel `[x_min, y_min, x_max, y_max]` nell'immagine elaborata.", "example": [ 661, 728, 1688, 2188 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Affidabilità del rilevamento facciale (0–1).", "example": 0.732973 }, "age": { "type": "number", "format": "float", "description": "Età stimata dal modello per il volto rilevato, in anni. Solo a scopo informativo: non influisce sulla decisione del confronto facciale.", "example": 26.91 }, "gender": { "type": "string", "description": "Genere previsto dal modello per il volto rilevato (`male` o `female`). Solo a scopo informativo.", "example": "male" }, "race": { "type": "string", "nullable": true, "description": "Campo riservato — sempre `null` nelle risposte di questo endpoint.", "example": null } } }, "description": "Una voce per ogni volto rilevato." }, "best_angle": { "type": "integer", "description": "Rotazione (gradi: 0, 90, 180 o 270) che ha prodotto il miglior rilevamento del volto. Diversa da zero solo quando `rotate_image=true` ha corretto l'orientamento.", "example": 0 } } }, "ref_image": { "type": "object", "description": "Risultati del rilevamento facciale per l'immagine di riferimento, con la stessa struttura di `user_image`.", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Riquadro di delimitazione del volto rilevato come coordinate in pixel `[x_min, y_min, x_max, y_max]` nell'immagine elaborata.", "example": [ 661, 728, 1688, 2188 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Affidabilità del rilevamento facciale (0–1).", "example": 0.732973 }, "age": { "type": "number", "format": "float", "description": "Età stimata dal modello per il volto rilevato, in anni. Solo a scopo informativo: non influisce sulla decisione del confronto facciale.", "example": 26.91 }, "gender": { "type": "string", "description": "Genere previsto dal modello per il volto rilevato (`male` o `female`). Solo a scopo informativo.", "example": "male" }, "race": { "type": "string", "nullable": true, "description": "Campo riservato — sempre `null` nelle risposte di questo endpoint.", "example": null } } }, "description": "Una voce per ogni volto rilevato." }, "best_angle": { "type": "integer", "example": 0 } } }, "warnings": { "type": "array", "description": "Vuoto in caso di approvazione senza anomalie. `NO_REFERENCE_IMAGE` (`error`): impossibile valutare alcuna coppia di volti; `LOW_FACE_MATCH_SIMILARITY` (`error`): punteggio pari o inferiore alla soglia di rifiuto. Ciascuno di questi imposta `status` su `Declined`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "NO_REFERENCE_IMAGE", "LOW_FACE_MATCH_SIMILARITY" ], "description": "Codice di rischio leggibile dalla macchina." }, "feature": { "type": "string", "enum": [ "FACEMATCH" ], "description": "Funzionalità che ha generato l'avviso. Sempre `FACEMATCH` su questo endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Sempre `null` per gli avvisi relativi al confronto facciale." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravità. Gli avvisi `error` portano `status` a `Declined`; le voci `warning` e `information` sono informative e non determinano mai un rifiuto da sole." }, "short_description": { "type": "string", "description": "Riepilogo del rischio su una riga leggibile dall'utente." }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura del rischio." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, o `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco dell'oggetto `metadata` inviato, o `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp ISO 8601 (UTC) di generazione della risposta, ad es. `2026-06-12T01:04:42.763237+00:00`." } } } } } }, "400": { "description": "Errore di validazione. Restituito quando un'immagine obbligatoria è mancante, supera 5 MB, ha un'estensione non supportata o quando un'opzione è fuori intervallo. Il corpo è l'envelope standard degli errori di campo di DRF: un array di messaggi per ciascun campo interessato.", "content": { "application/json": { "examples": { "Missing required image": { "summary": "`ref_image` (o `user_image`) non inclusa nei dati del modulo", "value": { "ref_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Estensione del file diversa da tiff/jpg/jpeg/png/webp", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "Il caricamento supera il limite di 5 MB", "value": { "user_image": [ "File size should not exceed 5 MB" ] } }, "Threshold out of range": { "summary": "`face_match_score_decline_threshold` al di fuori di 0–100", "value": { "face_match_score_decline_threshold": [ "Ensure this value is less than or equal to 100." ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi elaborazione delle immagini.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/face-match/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'ref_image=@./id_portrait.jpg' \\\n -F 'face_match_score_decline_threshold=50' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.face_match.compare(\n user_image=open(\"user_image.jpg\", \"rb\"),\n ref_image=open(\"ref_image.jpg\", \"rb\"),\n face_match_score_decline_threshold=50.0,\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"login\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.faceMatch.compare({\n user_image: await fileFromPath(\"user_image.jpg\"),\n ref_image: await fileFromPath(\"ref_image.jpg\"),\n face_match_score_decline_threshold: 50.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"login\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.FaceMatchCompareParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.faceMatch().compare(FaceMatchCompareParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .refImage(Path.of(\"ref_image.jpg\"))\n .faceMatchScoreDeclineThreshold(50.0)\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"login\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "faceMatch->compare([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'ref_image' => File::fromPath('ref_image.jpg'),\n 'face_match_score_decline_threshold' => 50.0,\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'login'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.face_match.compare(\n user_image: Pathname(\"user_image.jpg\"),\n ref_image: Pathname(\"ref_image.jpg\"),\n face_match_score_decline_threshold: 50.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"login\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FaceMatch.CompareAsync(new FaceMatchCompareParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n RefImage = FileUpload.FromPath(\"ref_image.jpg\"),\n FaceMatchScoreDeclineThreshold = 50.0,\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"login\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/age-estimation/": { "post": { "summary": "Stima dell'età (età del volto + vitalità passiva)", "description": "Stima l'età di una persona a partire da una singola foto del volto ed esegue un controllo passivo di rilevamento della vitalità nella stessa chiamata — restituisce l'`age_estimation` prevista dal modello (in anni), uno `score` di vitalità (0–100) e uno `status` `Approved`/`Declined`. L'età è **prevista dal modello in base al volto, non verificata rispetto a un documento** — utilizzala per controlli sull'età minima e verifiche a basso attrito, non come prova legale dell'età.\n\n**Come funziona.** L'immagine viene analizzata alla ricerca di volti (imposta `rotate_image=true` se le acquisizioni potrebbero essere ruotate o capovolte); ogni volto rilevato riceve un'età stimata e il volto più grande nell'inquadratura determina `age_estimation`. Parallelamente, un modello passivo di rilevamento della vitalità valuta con un punteggio se la foto mostra una persona reale (senza richiedere alcuna interazione all'utente) e rileva attacchi di presentazione (foto di foto, schermi, maschere). Per ottenere i migliori risultati, invia un unico volto chiaro, frontale e ben illuminato per immagine.\n\n**Logica di decisione.** Qualsiasi avviso comporta un rifiuto: `status` è `Approved` solo quando l'array `warnings` è vuoto. Uno `score` di vitalità pari o inferiore a `face_liveness_score_decline_threshold` (predefinito `30`) aggiunge `LOW_LIVENESS_SCORE`; un attacco rilevato aggiunge `LIVENESS_FACE_ATTACK`; nessun volto trovato dal modello di vitalità aggiunge `NO_FACE_DETECTED`; nessuna età del volto stimabile aggiunge `AGE_NOT_DETECTED` (`age_estimation` è `null`); un'età stimata inferiore a `age_estimation_decline_threshold` (predefinito `18`) aggiunge `AGE_BELOW_MINIMUM`. Le età prossime alla soglia impostata richiedono un fallback alla verifica basata su documenti — il margine di errore del modello aumenta per i volti vicini al limite.\n\n**Fatturazione.** Ogni risposta `200` consuma un credito API di Stima dell'età (scalato dai crediti del piano o dal saldo di ricarica). Quando il saldo dell'organizzazione non è sufficiente a coprire la chiamata, l'endpoint restituisce `403` con l'errore di crediti insufficienti prima di qualsiasi elaborazione dell'immagine.\n\n**Persistenza della sessione (`save_api_request`, predefinito `true`).** Quando è `true`, la chiamata viene salvata come sessione di tipo API: appare nella Business Console, il `request_id` restituito è un ID sessione reale che puoi passare a `GET /v3/session/{sessionId}/decision/` (il risultato viene esposto lì in `liveness_checks[]`, con `features: [\"AGE_ESTIMATION\"]`), il ritaglio del volto e l'immagine di riferimento vengono archiviati, l'embedding facciale viene aggiunto all'indice dei volti della tua applicazione (utilizzato per la ricerca facciale e il rilevamento dei duplicati) e viene generato un webhook `status.updated`. Quando è `false`, non viene memorizzato nulla e `request_id` è un UUID di correlazione una tantum che non può essere cercato in seguito.\n\n**Sandbox.** Le chiavi API sandbox ignorano qualsiasi elaborazione e fatturazione: dopo la validazione della richiesta (l'input non valido restituisce comunque `400`), l'endpoint restituisce un payload mock statico `Approved` (`age_estimation: 30`, nessun avviso), nessuna sessione viene salvata e non viene consumato alcun credito.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget condiviso di scrittura di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`.", "operationId": "post_v3age-estimation", "x-didit-sdk": { "resource": "age_estimation", "method": "estimate", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "Foto del volto da analizzare (ad es. un selfie). Invia una singola foto frontale con il volto del soggetto chiaramente visibile e ben illuminato. Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `webp` (nessun PDF). Dimensione massima di caricamento: **5 MB** (i file più grandi vengono rifiutati con `400`). Le immagini vengono compresse automaticamente a circa 0,3 MB prima dell'elaborazione, pertanto risoluzioni molto elevate non migliorano l'accuratezza." }, "face_liveness_score_decline_threshold": { "type": "number", "format": "float", "default": 30, "minimum": 0, "maximum": 100, "description": "Soglia di rilevamento della vitalità (0–100). Un punteggio (`score`) di vitalità **pari o inferiore** a questo valore aggiunge un avviso `LOW_LIVENESS_SCORE` e rifiuta. Aumentala per un livello anti-spoofing più restrittivo; i valori non compresi tra 0 e 100 restituiscono `400`.", "example": 30 }, "age_estimation_decline_threshold": { "type": "integer", "default": 18, "minimum": 0, "maximum": 100, "description": "Età stimata minima accettabile in anni. Un'età stimata **inferiore** a questo valore aggiunge un avviso `AGE_BELOW_MINIMUM` e rifiuta la verifica. Imposta `0` per disattivare il controllo dell'età (la chiamata eseguirà quindi solo rilevamento della vitalità + stima dell'età senza una decisione basata sull'età).", "example": 18 }, "rotate_image": { "type": "boolean", "default": false, "description": "Quando è `true`, il servizio prova l'immagine di input con incrementi di 90 gradi (0, 90, 180, 270) e utilizza l'orientamento che offre il miglior rilevamento del volto; utile per le acquisizioni da dispositivo mobile prive di orientamento EXIF. Aggiunge latenza, quindi attivalo solo se non puoi garantire immagini orientate correttamente.", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando è `true` (predefinito), rende persistente la chiamata come sessione di tipo API — visibile nella Business Console, recuperabile tramite `GET /v3/session/{sessionId}/decision/` utilizzando il `request_id` restituito, notificata tramite un webhook `status.updated`, e con il volto rilevato aggiunto all'indice dei volti della tua applicazione. Quando è `false`, non viene memorizzato nulla e `request_id` è un UUID temporaneo utilizzabile solo per la correlazione della risposta.", "example": true }, "vendor_data": { "type": "string", "description": "Stringa opaca opzionale (il tuo ID utente interno, email, UUID...) memorizzata nella sessione persistita e restituita nella risposta. Usala per correlare le chiamate API con i tuoi record e per filtrare le sessioni in un secondo momento.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON (ad es. `metadata={\"flow\":\"age-gate\"}`): viene interpretato come oggetto.", "example": { "flow": "age-gate" } } } }, "example": { "user_image": "(binary JPEG/PNG of the selfie)", "face_liveness_score_decline_threshold": 30, "age_estimation_decline_threshold": 18, "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "age-gate" } } } } }, "responses": { "200": { "description": "Stima dell'età e vitalità passiva completate. `age_estimation.age_estimation` è l'età prevista dal modello in anni del volto più grande rilevato (`null` se assente); `age_estimation.score` è il punteggio di vitalità passiva (0–100); `status` è `Approved` solo quando `warnings` è vuoto. Un'acquisizione di un minore o contraffatta restituisce comunque `200` con `status: \"Declined\"` — ispeziona il corpo della risposta, non solo il codice HTTP. Quando `save_api_request=true`, `request_id` è l'ID di sessione persistito.", "content": { "application/json": { "examples": { "Approved": { "summary": "Volto adulto dal vivo — entrambi i controlli superati", "value": { "request_id": "0c40ba43-64ab-4e2e-b4b8-7d1f12f81bc1", "age_estimation": { "status": "Approved", "method": "PASSIVE", "score": 97.5, "user_image": { "entities": [ { "age": 27.33, "bbox": [ 40, 40, 100, 100 ], "confidence": 0.7177750468254089, "gender": "male" } ], "best_angle": 0 }, "age_estimation": 27.33, "warnings": [] }, "vendor_data": "user-123", "metadata": { "flow": "age-gate" }, "created_at": "2026-06-12T02:24:11.512941+00:00" } }, "Declined - age below threshold": { "summary": "Età stimata inferiore a `age_estimation_decline_threshold`", "value": { "request_id": "9be41a6f-2f4e-4f57-92f4-b3a4f6f0a1c2", "age_estimation": { "status": "Declined", "method": "PASSIVE", "score": 95.0, "user_image": { "entities": [ { "age": 16.5, "bbox": [ 40, 40, 100, 100 ], "confidence": 0.7177750468254089, "gender": "female" } ], "best_angle": 0 }, "age_estimation": 16.5, "warnings": [ { "risk": "AGE_BELOW_MINIMUM", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Age below minimum", "long_description": "The age of the face is below the minimum age threshold for the application." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:26:40.118332+00:00" } }, "Declined - liveness too low": { "summary": "Punteggio di rilevamento della vitalità pari o inferiore alla soglia di rifiuto (possibile spoofing)", "value": { "request_id": "5f6f2f1f-7c4f-43b9-8d62-0a8f4c2d9e77", "age_estimation": { "status": "Declined", "method": "PASSIVE", "score": 5.0, "user_image": { "entities": [ { "age": 25.0, "bbox": [ 40, 40, 100, 100 ], "confidence": 0.7177750468254089, "gender": "male" } ], "best_angle": 0 }, "age_estimation": 25.0, "warnings": [ { "risk": "LOW_LIVENESS_SCORE", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Low liveness score", "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:27:02.901547+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo." }, "age_estimation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Approved` quando non è stato generato alcun avviso; altrimenti `Declined` (ogni avviso generato da questo endpoint comporta un rifiuto)." }, "method": { "type": "string", "enum": [ "PASSIVE" ], "description": "Metodo di rilevamento della vitalità. Sempre `PASSIVE` su questo endpoint (immagine singola, nessuna verifica interattiva dell'utente)." }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Punteggio del rilevamento passivo della vitalità da 0 a 100: il livello di affidabilità del modello che la foto mostri una persona viva. Confrontato con `face_liveness_score_decline_threshold`; se pari o inferiore, la chiamata viene rifiutata con `LOW_LIVENESS_SCORE`. È `null` quando il modello di rilevamento della vitalità non restituisce alcuna affidabilità: la chiamata viene comunque rifiutata con `LOW_LIVENESS_SCORE` poiché null viene trattato come 0 per il confronto con la soglia.", "example": 97.5 }, "user_image": { "type": "object", "description": "Risultati del rilevamento facciale per l'immagine analizzata.", "properties": { "entities": { "type": "array", "description": "Una voce per ogni volto rilevato. Vuoto se non è stato trovato alcun volto (in tal caso `age_estimation` è `null` e viene aggiunto un avviso `AGE_NOT_DETECTED`).", "items": { "type": "object", "properties": { "age": { "type": "number", "format": "float", "description": "Età stimata dal modello per questo volto, in anni.", "example": 27.33 }, "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Riquadro di delimitazione del volto rilevato come coordinate in pixel `[x_min, y_min, x_max, y_max]` nell'immagine elaborata.", "example": [ 40, 40, 100, 100 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Affidabilità del rilevamento facciale (0–1).", "example": 0.7177750468254089 }, "gender": { "type": "string", "description": "Genere previsto dal modello per il volto rilevato (`male` o `female`). Solo a scopo informativo.", "example": "male" } } } }, "best_angle": { "type": "integer", "nullable": true, "description": "Rotazione (gradi: 0, 90, 180 o 270) che ha prodotto il miglior rilevamento del volto. Diversa da zero solo quando `rotate_image=true` ha corretto l'orientamento.", "example": 0 } } }, "age_estimation": { "type": "number", "format": "float", "nullable": true, "description": "Età stimata dal modello in anni per il volto rilevato **più grande**. `null` quando non è stato possibile stimare l'età del volto (viene aggiunto un avviso `AGE_NOT_DETECTED` e la chiamata viene rifiutata).", "example": 27.33 }, "warnings": { "type": "array", "description": "Vuoto in caso di approvazione senza anomalie. Qualsiasi voce imposta `status` su `Declined`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "NO_FACE_DETECTED", "LOW_LIVENESS_SCORE", "LIVENESS_FACE_ATTACK", "AGE_NOT_DETECTED", "AGE_BELOW_MINIMUM" ], "description": "Codice di rischio leggibile dalla macchina. `NO_FACE_DETECTED` — il modello di vitalità non ha rilevato alcun volto; `LOW_LIVENESS_SCORE` — `score` di vitalità pari o inferiore a `face_liveness_score_decline_threshold`; `LIVENESS_FACE_ATTACK` — è stato rilevato un attacco di presentazione (foto/schermo/maschera); `AGE_NOT_DETECTED` — non è stato possibile stimare l'età del volto; `AGE_BELOW_MINIMUM` — età stimata inferiore a `age_estimation_decline_threshold`. `NO_FACE_DETECTED` e `LOW_LIVENESS_SCORE` si escludono a vicenda: se non viene trovato alcun volto, viene emesso solo `NO_FACE_DETECTED`." }, "feature": { "type": "string", "enum": [ "LIVENESS" ], "description": "Funzionalità che ha generato l'avviso. Sempre `LIVENESS` su questo endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Sempre `null` per gli avvisi relativi alla stima dell'età." }, "log_type": { "type": "string", "enum": [ "error" ], "description": "Gravità. Ogni avviso generato da questo endpoint è un `error` e imposta `status` su `Declined`." }, "short_description": { "type": "string", "description": "Riepilogo del rischio su una riga leggibile dall'utente." }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura del rischio." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, o `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco dell'oggetto `metadata` inviato, o `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp ISO 8601 (UTC) di generazione della risposta." } } } } } }, "400": { "description": "Errore di validazione. Restituito quando `user_image` è mancante, supera 5 MB, ha un'estensione non supportata o quando una soglia è fuori intervallo. Il corpo è l'envelope standard degli errori di campo di DRF: un array di messaggi per ciascun campo interessato.", "content": { "application/json": { "examples": { "Missing user image": { "summary": "`user_image` non incluso nei dati del modulo", "value": { "user_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Estensione del file diversa da tiff/jpg/jpeg/png/webp", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "Il caricamento supera il limite di 5 MB", "value": { "user_image": [ "File size should not exceed 5 MB" ] } }, "Threshold out of range": { "summary": "`face_liveness_score_decline_threshold` al di fuori di 0–100", "value": { "face_liveness_score_decline_threshold": [ "Ensure this value is less than or equal to 100." ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi elaborazione delle immagini.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/age-estimation/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'age_estimation_decline_threshold=18' \\\n -F 'face_liveness_score_decline_threshold=30' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.age_estimation.estimate(\n user_image=open(\"user_image.jpg\", \"rb\"),\n face_liveness_score_decline_threshold=30.0,\n age_estimation_decline_threshold=18,\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"age-gate\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.ageEstimation.estimate({\n user_image: await fileFromPath(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n age_estimation_decline_threshold: 18,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"age-gate\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AgeEstimation.Estimate(ctx, didit.AgeEstimationEstimateParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tAgeEstimationDeclineThreshold: didit.Int(18),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"age-gate\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.AgeEstimationEstimateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.ageEstimation().estimate(AgeEstimationEstimateParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .faceLivenessScoreDeclineThreshold(30.0)\n .ageEstimationDeclineThreshold(18L)\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"age-gate\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "ageEstimation->estimate([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'face_liveness_score_decline_threshold' => 30.0,\n 'age_estimation_decline_threshold' => 18,\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'age-gate'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.age_estimation.estimate(\n user_image: Pathname(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n age_estimation_decline_threshold: 18,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"age-gate\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.AgeEstimation.EstimateAsync(new AgeEstimationEstimateParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n FaceLivenessScoreDeclineThreshold = 30.0,\n AgeEstimationDeclineThreshold = 18,\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"age-gate\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/poa/": { "post": { "summary": "Prova di residenza (OCR documento + controlli indirizzo)", "description": "Estrai e convalida un documento di Prova di residenza — bollette delle utenze, estratti conto bancari e documenti rilasciati dal governo — in un'unica chiamata. Restituisce l'emittente, le date di emissione/scadenza, il nome dell'intestatario, l'indirizzo grezzo e analizzato/geocodificato, uno `status` `Approved`/`Declined` e un elenco `warnings` che illustra ogni problema riscontrato.\n\n**Latenza.** L'estrazione è basata su LLM: le chiamate tipiche richiedono **5–15 secondi**, i PDF multipagina fino a **~30 secondi**. Configura un timeout del client di **almeno 45 secondi** e non effettuare un nuovo tentativo prima del completamento della chiamata.\n\n**Come funziona.** Il documento (immagine o PDF, fino a 15 MB; i PDF crittografati richiedono `document_password`) viene classificato in un tipo e sottotipo di documento (ad es. `UTILITY_BILL` / `WATER_BILL`), e l'emittente, le date, il nome dell'intestatario e l'indirizzo vengono estratti tramite estrazione basata su LLM. L'indirizzo viene analizzato e geocodificato in `poa_parsed_address`. Le analisi forensi su PDF/EXIF verificano la presenza di manomissioni — modifiche successive alla firma digitale, editor PDF noti, manipolazione del testo in sovrimpressione, riesportazioni sospette — segnalando `SUSPECTED_DOCUMENT_MANIPULATION` o `DOCUMENT_METADATA_MISMATCH`. Un campo di testo cancellato e riscritto con un altro font, nei casi in cui il file stesso non contenga prove sull'eventuale modifica del contenuto, genera `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. L'anzianità del documento viene convalidata rispetto a `poa_document_age_months`, e la lingua rispetto a `poa_languages_allowed`. Se passi `expected_address`, `expected_country` o `expected_first_name`/`expected_last_name`, i valori estratti vengono confrontati e le discrepanze vengono segnalate.\n\n**Logica di decisione.** `status` è `Approved` a meno che almeno un avviso non si risolva in un rifiuto. Gli errori critici comportano sempre un rifiuto: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, oltre a `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` (non configurabili su questo endpoint). Cinque gruppi di rischio sono configurabili per richiesta tramite le opzioni `poa_*_action` (`DECLINE` o `NO_ACTION`, tutte impostate in modo predefinito su `DECLINE`). `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` e `UNPARSABLE_OR_INVALID_ADDRESS` sono informativi su questo endpoint e non comportano mai un rifiuto. Un documento che non può essere elaborato affatto restituisce `400`; un documento leggibile ma problematico restituisce `200` con `status: \"Declined\"` — esamina sempre `poa.status` e `poa.warnings`, non solo il codice HTTP.\n\n**Fatturazione.** Ogni risposta `200` consuma un credito API di Prova di residenza (scalato dai crediti del tuo piano o dal saldo delle ricariche). Quando il saldo dell'organizzazione non è sufficiente a coprire la chiamata, l'endpoint restituisce `403` con l'errore di credito insufficiente prima di qualsiasi elaborazione del documento.\n\n**Persistenza della sessione (`save_api_request`, default `true`).** Quando è `true`, la chiamata viene salvata come sessione di tipo API: appare nella Business Console, il documento caricato viene archiviato, il `request_id` restituito è un vero ID sessione che puoi passare a `GET /v3/session/{sessionId}/decision/` (la decisione espone inoltre `document_file` e le analisi forensi di `document_metadata`, che questa risposta omette) e viene emesso un webhook `status.updated`. Quando è `false`, nulla viene archiviato e `request_id` è un UUID di correlazione monouso che non può essere cercato in seguito.\n\n**Sandbox.** Le chiavi API sandbox ignorano qualsiasi elaborazione e fatturazione: dopo la convalida della richiesta (l'input malformato restituisce comunque `400`), l'endpoint restituisce un payload fittizio statico `Approved` (una bolletta elettrica fittizia di \"Sandbox Power Co.\"), nessuna sessione viene salvata e non viene consumato alcun credito.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`.\n\nNota: `FUTURE_ISSUE_DATE` e `POOR_DOCUMENT_QUALITY` sono presenti nelle sessioni di workflow ma non vengono mai generati da questo endpoint autonomo — un documento con data futura non viene rifiutato automaticamente in questo caso.", "operationId": "post_v3poa", "x-didit-sdk": { "resource": "proof_of_address", "method": "verify", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "document" ], "properties": { "document": { "type": "string", "format": "binary", "description": "Il documento di Prova di residenza. Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`. Dimensione massima di caricamento: **15 MB** (i file più grandi vengono rifiutati con `400`). I PDF multipagina sono supportati (è prevista una latenza maggiore); i PDF crittografati richiedono `document_password`. Le immagini vengono compresse automaticamente prima dell'elaborazione." }, "document_password": { "type": "string", "description": "Password per decrittografare `document` quando è un PDF crittografato. L'invio di un PDF crittografato senza password (o con una errata) restituisce `400`.", "writeOnly": true }, "expected_address": { "type": "string", "description": "Indirizzo da verificare a fronte del documento. Viene geocodificato e confrontato con l'indirizzo estratto; una mancata corrispondenza (o un indirizzo previsto che non può essere geocodificato/verificato) aggiunge `ADDRESS_MISMATCH_WITH_PROVIDED`, regolato da `poa_address_mismatch_action`. La forma geocodificata viene restituita in `expected_details_formatted_address` / `expected_details_parsed_address`.", "example": "Av. Monseñor Tavella 1291, Salta, Argentina" }, "expected_country": { "type": "string", "description": "Paese da verificare rispetto al documento (codice ISO 3166-1, ad es. `ARG` o `AR`). Una mancata corrispondenza con il paese del documento aggiunge `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, regolata da `poa_address_mismatch_action`.", "example": "ARG" }, "expected_first_name": { "type": "string", "description": "Nome da verificare a fronte di `name_on_document` (confronto fuzzy, tiene conto della traslitterazione). Un punteggio inferiore alla soglia di corrispondenza aggiunge `NAME_MISMATCH_WITH_PROVIDED`, gestito da `poa_address_mismatch_action`.", "example": "Sophia" }, "expected_last_name": { "type": "string", "description": "Cognome da verificare rispetto a `name_on_document`, combinato con `expected_first_name` per il punteggio di corrispondenza.", "example": "Martinez" }, "poa_languages_allowed": { "type": "string", "description": "Elenco separato da virgole delle lingue dei documenti accettate come codici ISO 639-1 (ad es. `en,es,fr`). Se omesso o vuoto, vengono accettate **tutte le 51 lingue supportate**. Un documento in una lingua non inclusa nell'elenco aggiunge `UNSUPPORTED_DOCUMENT_LANGUAGE` (regolato da `poa_unsupported_language_action`); un codice sconosciuto nell'elenco restituisce `400` con l'insieme completo dei codici supportati.", "example": "en,es" }, "poa_document_age_months": { "type": "string", "description": "Coppie `key:value` separate da virgole che impostano l'età massima del documento in mesi per ciascun tipo di documento — chiavi: `utility_bill`, `bank_statement`, `government_issued_document`, `other_poa_document`; valori: `1`–`120`, oppure `-1` per illimitato (nessun controllo dell'età). Valori predefiniti se omesso: `utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`. Un documento più vecchio del relativo limite viene rifiutato con `POA_DOCUMENT_EXPIRED`. **Attenzione:** quando fornisci questo campo, elenca *ogni* tipo che accetti: i tipi omessi vengono considerati non accettati (`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` informativo) e il loro controllo dell'età viene saltato.", "example": "utility_bill:3,bank_statement:6" }, "poa_name_mismatch_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "Accettato ma **attualmente non applicato** — gli avvisi di mancata corrispondenza del nome (`NAME_MISMATCH_WITH_PROVIDED`) seguono invece `poa_address_mismatch_action`. Imposta `poa_address_mismatch_action` per controllare il comportamento di mancata corrispondenza sia del nome che dell'indirizzo." }, "poa_document_issues_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "Cosa fare in caso di problemi di integrità del file — in pratica questo endpoint genera solo `DOCUMENT_METADATA_MISMATCH`." }, "poa_document_authenticity_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "Cosa fare quando si sospetta una manipolazione del documento (`SUSPECTED_DOCUMENT_MANIPULATION`) — ad esempio se il PDF è stato modificato dopo la firma digitale, elaborato da un editor PDF noto, mostra una manipolazione del testo in sovrimpressione o presenta date EXIF incoerenti. Regola anche `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (un campo di testo ridigitato per il quale il file non può dimostrare se sia stato modificato o meno): `DECLINE` rifiuta anche questo, `NO_ACTION` lo mantiene come avviso." }, "poa_unsupported_language_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "Cosa fare quando la lingua del documento è al di fuori di `poa_languages_allowed` (`UNSUPPORTED_DOCUMENT_LANGUAGE`)." }, "poa_address_mismatch_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "Cosa fare quando i dettagli estratti non concordano con i campi `expected_*`: `ADDRESS_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_WITH_PROVIDED` e `POA_COUNTRY_MISMATCH_WITH_PROVIDED` seguono tutti questa azione." }, "poa_issuer_not_identified_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "Cosa fare quando non è possibile identificare alcuna azienda/organizzazione emittente sul documento (`ISSUER_NOT_IDENTIFIED`)." }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando è `true` (predefinito), rende persistente la chiamata come sessione di tipo API — visibile nella Business Console, recuperabile tramite `GET /v3/session/{sessionId}/decision/` utilizzando il `request_id` restituito, notificata tramite un webhook `status.updated`, e con il documento caricato che viene archiviato. Quando è `false`, non viene memorizzato nulla e `request_id` è un UUID temporaneo utilizzabile solo per la correlazione della risposta.", "example": true }, "vendor_data": { "type": "string", "description": "Stringa opaca opzionale (il tuo ID utente interno, email, UUID...) memorizzata nella sessione persistita e restituita nella risposta. Usala per correlare le chiamate API con i tuoi record e per filtrare le sessioni in un secondo momento.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON (ad es. `metadata={\"flow\":\"onboarding\"}`): viene interpretato come oggetto.", "example": { "flow": "onboarding" } } } }, "example": { "document": "(binary JPEG/PNG/PDF of the utility bill or bank statement)", "expected_address": "Av. Monseñor Tavella 1291, Salta, Argentina", "expected_country": "ARG", "expected_first_name": "Sophia", "expected_last_name": "Martinez", "poa_languages_allowed": "en,es", "save_api_request": true, "vendor_data": "user-123" } } } }, "responses": { "200": { "description": "Documento elaborato. `poa.status` è `Approved` o `Declined`; ogni problema rilevato è dettagliato in `poa.warnings`. Un documento scaduto, non corrispondente o sospetto restituisce comunque `200` con `status: \"Declined\"` — esamina il corpo, non solo il codice HTTP. Quando `save_api_request=true`, `request_id` è l'ID di sessione persistito.", "content": { "application/json": { "examples": { "Approved": { "summary": "Bolletta di utenza letta correttamente, nessun controllo dei dettagli previsti", "value": { "request_id": "4b523a8d-ed32-45e4-8aa8-a89eda459d88", "poa": { "issuing_state": "ARG", "document_type": "UTILITY_BILL", "document_subtype": "WATER_BILL", "document_language": "es", "issuer": "Aguas del Norte", "issue_date": "2026-04-10", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA", "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina", "poa_parsed_address": { "street_1": "Avenida Monseñor Tavella 1291", "street_2": "b", "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208682, "longitude": -65.4130954 } }, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "name_on_document": "OESTE EMBOTELLADORA S.A.", "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "LA EMBOTELLADORA DEL NORTE SA" ] }, "detected_codes": [ { "type": "QR_CODE", "page_number": 1, "position": [ [ 820, 1120 ], [ 1002, 1120 ], [ 1002, 1302 ], [ 820, 1302 ] ], "x": 820, "y": 1120, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==", "parsed_payload": "https://aguasdelnorte.com/factura/998811" }, { "type": "CODE_128", "page_number": 1, "position": [ [ 112, 1480 ], [ 560, 1480 ], [ 560, 1540 ], [ 112, 1540 ] ], "x": 112, "y": 1480, "width": 448, "height": 60, "page_width": 1190, "page_height": 1684, "raw_payload": "MDA5OTg4MTEwMDA0Mg==", "parsed_payload": "0099881100042" } ], "status": "Approved", "warnings": [] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:29:02.439655+00:00" } }, "Declined - document too old": { "summary": "Data di emissione antecedente rispetto al parametro `poa_document_age_months` consentito", "value": { "request_id": "f61681b8-9422-4378-ac3e-04c6a247fb45", "poa": { "issuing_state": "ARG", "document_type": "UTILITY_BILL", "document_subtype": "WATER_BILL", "document_language": "es", "issuer": "Aguas del Norte", "issue_date": "2021-02-10", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA", "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina", "poa_parsed_address": { "street_1": "Avenida Monseñor Tavella 1291", "street_2": "b", "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208682, "longitude": -65.4130954 } }, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "name_on_document": "OESTE EMBOTELLADORA S.A.", "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "LA EMBOTELLADORA DEL NORTE SA" ] }, "status": "Declined", "warnings": [ { "risk": "POA_DOCUMENT_EXPIRED", "feature": "PROOF_OF_ADDRESS", "additional_data": { "expiration_reason": "age_window", "max_age_months": 3, "document_subtype": "WATER_BILL", "document_type": "UTILITY_BILL", "issue_date": "2021-02-10" }, "log_type": "error", "short_description": "Document expired", "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:23:02.165493+00:00" } }, "Declined - name mismatch": { "summary": "`expected_first_name`/`expected_last_name` non corrispondono a `name_on_document`", "value": { "request_id": "0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21", "poa": { "issuing_state": "ARG", "document_type": "UTILITY_BILL", "document_subtype": "WATER_BILL", "document_language": "es", "issuer": "Aguas del Norte", "issue_date": "2021-02-10", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA", "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina", "poa_parsed_address": { "street_1": "Avenida Monseñor Tavella 1291", "street_2": "b", "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208682, "longitude": -65.4130954 } }, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "name_on_document": "OESTE EMBOTELLADORA S.A.", "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "LA EMBOTELLADORA DEL NORTE SA" ] }, "status": "Declined", "warnings": [ { "risk": "NAME_MISMATCH_WITH_PROVIDED", "feature": "PROOF_OF_ADDRESS", "additional_data": null, "log_type": "error", "short_description": "Name mismatch with provided information", "long_description": "The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:27:21.330172+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo." }, "poa": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Approved` quando nessun avviso si traduce in un rifiuto; altrimenti `Declined`: l'elenco `warnings` ne spiega il motivo." }, "issuing_state": { "type": "string", "nullable": true, "description": "Paese in cui è stato rilasciato il documento, come estratto dal documento stesso — di solito ISO 3166-1 alpha-3 (ad es. `ARG`).", "example": "ARG" }, "document_type": { "type": "string", "enum": [ "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" ], "description": "Categoria del documento rilevata. `UNKNOWN` indica che il documento non ha potuto essere classificato come una Prova di residenza accettabile e viene rifiutata automaticamente con `INVALID_DOCUMENT_TYPE`. Mai null: gli errori di classificazione ripiegano su `UNKNOWN`." }, "document_subtype": { "type": "string", "description": "Classificazione più dettagliata all'interno di `document_type` — ad es. `ELECTRICITY_BILL`, `WATER_BILL`, `GAS_BILL`, `INTERNET_BILL`, `PHONE_BILL` (bollette delle utenze); `ACCOUNT_STATEMENT`, `CREDIT_CARD_STATEMENT` (estratti conto bancari); `TAX_ASSESSMENT`, `RESIDENCY_CERTIFICATE` (documenti governativi). `UNKNOWN` quando non è stato possibile determinare alcun sottotipo. Mai nullo — gli errori di classificazione ricadono su `UNKNOWN`.", "example": "WATER_BILL" }, "document_language": { "type": "string", "nullable": true, "description": "Lingua del documento rilevata (ISO 639-1).", "example": "es" }, "issuer": { "type": "string", "nullable": true, "description": "Azienda o organizzazione che ha emesso il documento. `null` aggiunge `ISSUER_NOT_IDENTIFIED`.", "example": "Aguas del Norte" }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "Data di emissione del documento (`YYYY-MM-DD`). `null` quando non è stato possibile estrarla — comporta il rifiuto con `UNABLE_TO_EXTRACT_ISSUE_DATE` su questo endpoint.", "example": "2021-02-10" }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "Data di scadenza/validità esplicita stampata sul documento, se presente. Indipendente dal controllo dell'età `poa_document_age_months`." }, "poa_address": { "type": "string", "nullable": true, "description": "Indirizzo esattamente come stampato sul documento. `null` comporta il rifiuto automatico con `MISSING_ADDRESS_INFORMATION`." }, "poa_formatted_address": { "type": "string", "nullable": true, "description": "Versione normalizzata e geocodificata di `poa_address`.", "example": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina" }, "poa_parsed_address": { "type": "object", "nullable": true, "description": "Suddivisione geocodificata e strutturata dell'indirizzo del documento. `null` se non è stato possibile analizzare l'indirizzo.", "properties": { "street_1": { "type": "string", "nullable": true, "example": "Avenida Monseñor Tavella 1291" }, "street_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true, "example": "Salta" }, "region": { "type": "string", "nullable": true, "example": "Salta" }, "country": { "type": "string", "nullable": true, "description": "Codice paese ISO 3166-1 alpha-2.", "example": "AR" }, "postal_code": { "type": "string", "nullable": true, "example": "A4400" }, "document_location": { "type": "object", "nullable": true, "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "description": "Coordinate geocodificate dell'indirizzo del documento." } } }, "expected_details_address": { "type": "string", "nullable": true, "description": "Eco dello `expected_address` inviato, o `null`." }, "expected_details_formatted_address": { "type": "string", "nullable": true, "description": "Versione geocodificata e normalizzata di `expected_address`; `null` quando non fornita o non geocodificabile." }, "expected_details_parsed_address": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Risultato completo della geocodifica per `expected_address` (via/città/regione/paese/codice postale più l'output grezzo del geocoder e un flag `is_verified`). `null` quando `expected_address` non è stato fornito." }, "name_on_document": { "type": "string", "nullable": true, "description": "Nome del titolare principale estratto dal documento; confrontato con `expected_first_name`/`expected_last_name` se forniti. Se `null`, viene rifiutato con `POA_NAME_NOT_DETECTED` su questo endpoint.", "example": "OESTE EMBOTELLADORA S.A." }, "extra_fields": { "type": "object", "description": "Dati aggiuntivi specifici del documento. I campi bancari sono compilati per gli estratti conto bancari quando stampati sul documento; `null` altrimenti.", "properties": { "bank_account_number": { "type": "string", "nullable": true }, "bank_iban": { "type": "string", "nullable": true }, "bank_sort_code": { "type": "string", "nullable": true }, "bank_routing_number": { "type": "string", "nullable": true }, "bank_swift_bic": { "type": "string", "nullable": true }, "bank_branch_name": { "type": "string", "nullable": true }, "bank_branch_address": { "type": "string", "nullable": true }, "document_phone_number": { "type": "string", "nullable": true, "description": "Numero di telefono di contatto stampato sul documento." }, "additional_names": { "type": "array", "items": { "type": "string" }, "description": "Altri nominativi di intestatari rilevati sul documento (es. cointestatari del conto, nominativi precedenti del conto)." } } }, "warnings": { "type": "array", "description": "Vuoto in caso di approvazione senza anomalie. Ogni voce illustra un rischio rilevato; le voci con `log_type: \"error\"` impostano `status` su `Declined`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "description": "Codice di rischio leggibile dalla macchina. Sempre rifiutati: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, oltre a `UNABLE_TO_EXTRACT_ISSUE_DATE` e `POA_NAME_NOT_DETECTED` (impostati su rifiuto per questo endpoint). Regolati dalle opzioni della richiesta: `NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED` (`poa_address_mismatch_action`), `POOR_DOCUMENT_QUALITY` (mai generato da questo endpoint) / `DOCUMENT_METADATA_MISMATCH` (`poa_document_issues_action`), `SUSPECTED_DOCUMENT_MANIPULATION` e `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (`poa_document_authenticity_action`), `UNSUPPORTED_DOCUMENT_LANGUAGE` (`poa_unsupported_language_action`), `ISSUER_NOT_IDENTIFIED` (`poa_issuer_not_identified_action`). Informativi su questo endpoint: `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNPARSABLE_OR_INVALID_ADDRESS`.", "example": "POA_DOCUMENT_EXPIRED" }, "feature": { "type": "string", "enum": [ "PROOF_OF_ADDRESS" ], "description": "Funzionalità che ha generato l'avviso. Sempre `PROOF_OF_ADDRESS` su questo endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contesto aggiuntivo per alcuni rischi — ad es. `POA_DOCUMENT_EXPIRED` include `expiration_reason` (`printed_expiration` o `age_window`), `document_type`, `document_subtype` e `issue_date`, più `expiration_date` nel percorso `printed_expiration` o `max_age_months` nel percorso `age_window`; `SUSPECTED_DOCUMENT_MANIPULATION` include `reason` e `detection_method`; `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` include `reason`, `detection_method` (`unproven_text_replacement`), `replaced_text`, `manipulated_regions` e `manipulated_blocks`. `null` per la maggior parte dei rischi." }, "log_type": { "type": "string", "enum": [ "error", "information" ], "description": "Gravità. Gli avvisi `error` portano `status` a `Declined`; le voci `information` sono informative e non determinano mai un rifiuto da sole. (`warning` non viene prodotto da questo endpoint — le sue opzioni accettano solo `DECLINE` o `NO_ACTION`.)" }, "short_description": { "type": "string", "description": "Riepilogo del rischio su una riga leggibile dall'utente." }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura del rischio." } } } }, "detected_codes": { "type": "array", "description": "Codici QR e codici a barre rilevati in ogni pagina elaborata del documento. Vuoto se non ne viene trovato nessuno. Un codice QR individuato ma non decodificabile ha `parsed_payload: null`.", "items": { "$ref": "#/components/schemas/DocumentAIDetectedCode" } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, o `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco dell'oggetto `metadata` inviato, o `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp ISO 8601 (UTC) di generazione della risposta." } } } } } }, "400": { "description": "Errore di validazione o di elaborazione. I problemi a livello di campo restituiscono l'envelope standard di DRF (un array di messaggi per ciascun campo interessato). I problemi relativi a PDF crittografati restituiscono `{\"detail\": ...}`. Un documento che la pipeline di estrazione non riesce a elaborare restituisce `{\"error\": [\"Error extracting POA information\"]}`.", "content": { "application/json": { "examples": { "Missing document": { "summary": "`document` non incluso nei dati del modulo", "value": { "document": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Estensione del file diversa da tiff/jpg/jpeg/png/pdf/webp", "value": { "document": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp." ] } }, "File too large": { "summary": "Il caricamento supera il limite di 15 MB", "value": { "document": [ "File size should not exceed 15 MB" ] } }, "Encrypted PDF": { "summary": "PDF caricato senza la password richiesta", "value": { "detail": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Wrong PDF password": { "summary": "`document_password` non decifra il PDF", "value": { "detail": "The PDF password is incorrect. Please provide the correct password." } }, "Invalid language code": { "summary": "`poa_languages_allowed` contiene un codice non supportato", "value": { "poa_languages_allowed": [ "Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']." ] } }, "Invalid document age value": { "summary": "valore di `poa_document_age_months` non compreso tra 1 e 120 / -1", "value": { "poa_document_age_months": [ "Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120." ] } }, "Extraction failure": { "summary": "Impossibile elaborare il documento tramite la pipeline di estrazione", "value": { "error": [ "Error extracting POA information" ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi elaborazione dei documenti.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/poa/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'document=@./utility-bill.pdf' \\\n -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \\\n -F 'expected_country=ARG' \\\n -F 'expected_first_name=Sophia' \\\n -F 'expected_last_name=Martinez' \\\n -F 'poa_languages_allowed=en,es' \\\n -F 'vendor_data=user-123' \\\n --max-time 45" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.proof_of_address.verify(\n document=open(\"document.pdf\", \"rb\"),\n expected_address=\"Av. Monseñor Tavella 1291, Salta, Argentina\",\n expected_country=\"ARG\",\n expected_first_name=\"Sophia\",\n expected_last_name=\"Martinez\",\n poa_languages_allowed=\"en,es\",\n save_api_request=True,\n vendor_data=\"user-123\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.proofOfAddress.verify({\n document: await fileFromPath(\"document.pdf\"),\n expected_address: \"Av. Monseñor Tavella 1291, Salta, Argentina\",\n expected_country: \"ARG\",\n expected_first_name: \"Sophia\",\n expected_last_name: \"Martinez\",\n poa_languages_allowed: \"en,es\",\n save_api_request: true,\n vendor_data: \"user-123\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.ProofOfAddressVerifyParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder()\n .document(Path.of(\"document.pdf\"))\n .expectedAddress(\"Av. Monseñor Tavella 1291, Salta, Argentina\")\n .expectedCountry(\"ARG\")\n .expectedFirstName(\"Sophia\")\n .expectedLastName(\"Martinez\")\n .poaLanguagesAllowed(\"en,es\")\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "proofOfAddress->verify([\n 'document' => File::fromPath('document.pdf'),\n 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina',\n 'expected_country' => 'ARG',\n 'expected_first_name' => 'Sophia',\n 'expected_last_name' => 'Martinez',\n 'poa_languages_allowed' => 'en,es',\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.proof_of_address.verify(\n document: Pathname(\"document.pdf\"),\n expected_address: \"Av. Monseñor Tavella 1291, Salta, Argentina\",\n expected_country: \"ARG\",\n expected_first_name: \"Sophia\",\n expected_last_name: \"Martinez\",\n poa_languages_allowed: \"en,es\",\n save_api_request: true,\n vendor_data: \"user-123\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams\n{\n Document = FileUpload.FromPath(\"document.pdf\"),\n ExpectedAddress = \"Av. Monseñor Tavella 1291, Salta, Argentina\",\n ExpectedCountry = \"ARG\",\n ExpectedFirstName = \"Sophia\",\n ExpectedLastName = \"Martinez\",\n PoaLanguagesAllowed = \"en,es\",\n SaveApiRequest = true,\n VendorData = \"user-123\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/document-ai/": { "post": { "summary": "Document AI (estrazione di campi personalizzati + verifiche di manomissione)", "description": "Estrai i campi definiti da **te** da qualsiasi documento di supporto — buste paga, prova dei fondi, lettere sull'origine del patrimonio, dichiarazioni fiscali, contratti, fatture — in un'unica chiamata. Invia il file insieme a una definizione di `fields` (chiave, nome, istruzione di estrazione, tipo) e ricevi valori tipizzati (`text`, `number`, `date` nel formato `YYYY-MM-DD`), un punteggio opzionale di corrispondenza del nome rispetto alla persona o all'azienda prevista, segnali di manomissione PDF/EXIF, uno `status` pari a `Approved`/`Declined`/`In Review` e un elenco `warnings` che spiega ogni problema riscontrato. Questa è la controparte server-to-server del passaggio di workflow Document AI ospitato (vedi `/core-technology/document-ai/overview`); utilizza il modello di estrazione predefinito di Didit e non espone la selezione del provider.\n\n**Latenza.** L'estrazione è basata su LLM: le chiamate tipiche richiedono **5–15 secondi**, i PDF multipagina fino a **~30 secondi**. Configura un timeout del client di **almeno 45 secondi** e non effettuare un nuovo tentativo prima del completamento della chiamata.\n\n**Formato della richiesta.** Solo `multipart/form-data`. `fields` è **una singola stringa di array codificata in JSON** (1–30 elementi, massimo 16 KB); gli array di moduli in stile parentesi quadre vengono rifiutati con `400`. Ogni elemento è `{key, name, instruction, type, required, is_full_name}` — `key` è la chiave JSON restituita (`^[a-z0-9_]{1,64}$`, univoca), `instruction` indica al modello cosa leggere, `type` è `text` (predefinito) | `number` | `date`, `required` genera `DOCUMENT_AI_MISSING_REQUIRED_FIELDS` quando il valore non può essere letto e al massimo un campo può impostare `is_full_name: true` per contrassegnare il valore da confrontare con il nome previsto.\n\n**Corrispondenza del nome.** Passa `expected_first_name` + `expected_last_name` (persona) **oppure** `expected_company_name` (+ l'opzionale `expected_company_country`) — non entrambi. Il valore del campo `is_full_name` (o, se nessuno è contrassegnato, il primo campo di testo la cui chiave sembra un nome) viene confrontato in modo approssimativo; `name_match_score` (0–100) e `name_on_document` vengono sempre restituiti quando entrambi i lati esistono, e un punteggio inferiore a `document_ai_name_match_score_threshold` (predefinito 80) aggiunge `DOCUMENT_AI_NAME_MISMATCH`, regolato da `document_ai_name_mismatch_action`.\n\n**Logica decisionale.** Ogni rischio è mappato a un'azione configurabile: `DECLINE` → `status: \"Declined\"`, `REVIEW` → `status: \"In Review\"`, `NO_ACTION` → solo informativo. I valori predefiniti rispecchiano il passaggio del workflow: documento illeggibile `REVIEW`, campi obbligatori mancanti `REVIEW`, sospetta manipolazione `DECLINE`, mancata corrispondenza del nome `NO_ACTION`, file non supportato `REVIEW`. Un documento che non può essere elaborato affatto restituisce `400`; un documento leggibile ma problematico restituisce `200` con `Declined`/`In Review` — verifica sempre `document_ai.status` e `document_ai.warnings`, non solo il codice HTTP.\n\n**Fatturazione.** Ogni risposta `200` consuma un credito API Document AI — **$0.20 per documento** al prezzo di listino, scalati dal credito del tuo piano o dal saldo ricaricato. Quando il saldo dell'organizzazione non può coprire la chiamata, l'endpoint restituisce `403` prima di qualsiasi elaborazione. Le chiavi API sandbox restituiscono una risposta simulata deterministica e non vengono addebitate.\n\n**Persistenza.** Con `save_api_request=true` (predefinito) la chiamata viene memorizzata come sessione di tipo API: il documento, i valori estratti, le definizioni dei campi e lo snapshot della corrispondenza del nome vengono conservati, la sessione compare nella Business Console e `request_id` funziona con `GET /v3/session/{sessionId}/decision/`.", "operationId": "post_v3document-ai", "x-didit-sdk": { "resource": "document_ai", "method": "analyze", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "document", "fields" ], "properties": { "document": { "type": "string", "format": "binary", "description": "Il documento da leggere. Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`, `zip`. Dimensione massima di caricamento: **30 MB** (i file più grandi vengono rifiutati con un `400`). I PDF multipagina sono supportati (prevedere una latenza maggiore); i PDF crittografati vengono rifiutati con un `400`. Le immagini vengono compresse automaticamente prima dell'elaborazione." }, "fields": { "type": "string", "description": "Una stringa contenente un array codificato in JSON con **1–30** definizioni di campo (massimo 16 KB). Ogni elemento: `key` (obbligatorio, `^[a-z0-9_]{1,64}$`, univoco — la chiave restituita in `extracted_data`), `name` (≤100 caratteri, mostrato nei messaggi), `instruction` (≤500 caratteri, ciò che il modello deve leggere), `type` (`text` predefinito | `number` | `date`), `required` (booleano, predefinito `false`), `is_full_name` (booleano, predefinito `false`, al massimo uno per richiesta). Gli array di form in stile parentesi quadre, JSON non valido, chiavi duplicate o più di un `is_full_name` restituiscono `400` prima di qualsiasi elaborazione o fatturazione.", "example": "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]" }, "expected_first_name": { "type": "string", "description": "Nome da verificare rispetto al campo del nome del documento (confronto fuzzy, tiene conto della traslitterazione). Da utilizzare insieme a `expected_last_name`; non può essere combinato con `expected_company_name`.", "example": "Sophia" }, "expected_last_name": { "type": "string", "description": "Cognome da verificare rispetto al campo del nome del documento, combinato con `expected_first_name` per `name_match_score`.", "example": "Martinez" }, "expected_company_name": { "type": "string", "description": "Ragione sociale da verificare rispetto al campo del nome del documento (per documenti aziendali). Non può essere combinata con `expected_first_name` / `expected_last_name` (nessun valore di esempio intenzionalmente: l'esempio di richiesta generato utilizza i campi della persona fisica; sostituiscili con questo quando verifichi un documento aziendale)." }, "expected_company_country": { "type": "string", "description": "Codice paese opzionale ISO 3166-1 alpha-2 (due lettere ASCII, ad es. `FR`) che regola la normalizzazione del nome dell'azienda per `expected_company_name`. Utilizzato solo con `expected_company_name`." }, "document_ai_name_match_score_threshold": { "type": "integer", "minimum": 0, "maximum": 100, "default": 80, "description": "Valore minimo di `name_match_score` (0–100) affinché il nome sia considerato corrispondente. Un punteggio inferiore aggiunge `DOCUMENT_AI_NAME_MISMATCH`, regolato da `document_ai_name_mismatch_action`.", "example": 80 }, "document_ai_unreadable_document_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "REVIEW", "description": "Cosa fare quando non è stato possibile leggere alcun campo dal documento (`DOCUMENT_AI_UNREADABLE_DOCUMENT`)." }, "document_ai_missing_required_fields_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "REVIEW", "description": "Cosa fare quando non è stato possibile leggere almeno un campo `required` (`DOCUMENT_AI_MISSING_REQUIRED_FIELDS`; `additional_data.missing_fields` li elenca)." }, "document_ai_document_tampering_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "DECLINE", "description": "Cosa fare quando l'analisi forense di PDF/EXIF sospetta una manipolazione — modificato dopo la firma digitale, editor PDF noto, manipolazione del testo in sovrimpressione, riesportazione sospetta, anomalie dell'immagine (`DOCUMENT_AI_SUSPECTED_MANIPULATION`)." }, "document_ai_name_mismatch_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "NO_ACTION", "description": "Cosa fare quando `name_match_score` è inferiore alla soglia (`DOCUMENT_AI_NAME_MISMATCH`)." }, "document_ai_unsupported_file_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "REVIEW", "description": "Cosa fare quando il caricamento è vuoto o non è un file elaborabile (`DOCUMENT_AI_UNSUPPORTED_FILE`)." }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando è `true` (predefinito), rende persistente la chiamata come sessione di tipo API — visibile nella Business Console, recuperabile tramite `GET /v3/session/{sessionId}/decision/` utilizzando il `request_id` restituito, con il documento caricato, i valori estratti, le definizioni dei campi e lo snapshot di corrispondenza dei nomi archiviati. Quando è `false`, non viene memorizzato nulla e `request_id` è un UUID temporaneo utilizzabile solo per la correlazione della risposta; la chiamata viene comunque fatturata.", "example": true }, "vendor_data": { "type": "string", "description": "Stringa opaca opzionale (il tuo ID utente interno, email, UUID...) memorizzata nella sessione persistita e restituita nella risposta. Usala per correlare le chiamate API con i tuoi record e per filtrare le sessioni in un secondo momento.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON (ad es. `metadata={\"flow\":\"onboarding\"}`): viene interpretato come oggetto.", "example": { "flow": "onboarding" } } } } } } }, "responses": { "200": { "description": "Documento elaborato. `document_ai.status` è `Approved`, `Declined` o `In Review`; ogni problema rilevato è dettagliato in `document_ai.warnings`. Un documento problematico restituisce comunque `200` — esamina il corpo, non solo il codice HTTP. Quando `save_api_request=true`, `request_id` è l'ID di sessione persistito.", "content": { "application/json": { "examples": { "Approved": { "summary": "Busta paga letta correttamente, nome corrispondente", "value": { "request_id": "9d6a3b1e-2f0c-4a8e-9b7d-1c2e3f4a5b6c", "document_ai": { "status": "Approved", "extracted_data": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": 3120.5, "pay_date": "2026-07-31" }, "detected_codes": [ { "type": "CODE_128", "page_number": 1, "position": [ [ 96, 456 ], [ 96, 616 ], [ 1012, 611 ], [ 1015, 456 ] ], "x": 96, "y": 456, "width": 919, "height": 160, "page_width": 1200, "page_height": 1700, "raw_payload": "SU5WLTIwMjYtMDA0Mg==", "parsed_payload": "INV-2026-0042" } ], "fields": [ { "key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false }, { "key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true }, { "key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false }, { "key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false } ], "name_match_score": 100.0, "name_on_document": "Sophia Martinez", "warnings": [] }, "vendor_data": "user-123", "metadata": { "flow": "onboarding" }, "created_at": "2026-08-19T16:40:12.318Z" } }, "In Review — missing required field": { "summary": "Impossibile leggere `net_pay`; azione predefinita REVIEW", "value": { "request_id": "3f2a9c7b-5d4e-4b1a-8c6f-0e9d8c7b6a5f", "document_ai": { "status": "In Review", "extracted_data": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": null, "pay_date": "2026-07-31" }, "detected_codes": [], "fields": [ { "key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false }, { "key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true }, { "key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false }, { "key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false } ], "name_match_score": 100.0, "name_on_document": "Sophia Martinez", "warnings": [ { "risk": "DOCUMENT_AI_MISSING_REQUIRED_FIELDS", "feature": "DOCUMENT_AI", "additional_data": { "missing_fields": [ "Net pay" ] }, "log_type": "warning", "short_description": "Required fields could not be extracted", "long_description": "One or more fields configured as required could not be extracted from the uploaded document." } ] }, "vendor_data": null, "metadata": null, "created_at": "2026-08-19T16:41:05.002Z" } }, "Declined — suspected manipulation": { "summary": "L'analisi forense del PDF ha rilevato un editor noto; azione predefinita DECLINE", "value": { "request_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "document_ai": { "status": "Declined", "extracted_data": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": 3120.5, "pay_date": "2026-07-31" }, "detected_codes": [], "fields": [ { "key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false }, { "key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true }, { "key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false }, { "key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false } ], "name_match_score": null, "name_on_document": "Sophia Martinez", "warnings": [ { "risk": "DOCUMENT_AI_SUSPECTED_MANIPULATION", "feature": "DOCUMENT_AI", "additional_data": { "detection_method": "known_editor", "processed_by_known_editor": "ilovepdf" }, "log_type": "error", "short_description": "Suspected document manipulation", "long_description": "The system detected signs of potential manipulation or editing in the uploaded document." } ] }, "vendor_data": null, "metadata": null, "created_at": "2026-08-19T16:42:40.771Z" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo." }, "document_ai": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "`Approved` quando nessun avviso si traduce in un rifiuto o in una revisione; `Declined` quando almeno un rischio corrisponde a `DECLINE`; altrimenti `In Review` quando almeno uno corrisponde a `REVIEW`. L'elenco `warnings` ne spiega il motivo." }, "extracted_data": { "type": "object", "additionalProperties": true, "description": "Una voce per ogni chiave di campo richiesta. I valori sono tipizzati in base al `type` del campo — stringhe per `text`, numeri per `number`, stringhe `YYYY-MM-DD` per `date` — oppure `null` quando non è stato possibile leggere il valore.", "example": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": 3120.5, "pay_date": "2026-07-31" } }, "detected_codes": { "type": "array", "description": "Codici QR e codici a barre rilevati in ogni pagina elaborata. Vuoto se non ne viene trovato nessuno. Un codice QR individuato ma non decodificabile ha `parsed_payload: null`.", "items": { "$ref": "#/components/schemas/DocumentAIDetectedCode" } }, "fields": { "type": "array", "description": "Le definizioni dei campi normalizzate usate per questa estrazione, restituite come eco (memorizzate anche con la sessione quando `save_api_request=true`).", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "instruction": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date" ] }, "required": { "type": "boolean" }, "is_full_name": { "type": "boolean" } } } }, "name_match_score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "description": "Somiglianza approssimativa (0–100) tra `name_on_document` e il nome atteso della persona/azienda. Restituita ogni volta che esistono sia un valore per il nome sia un nome atteso, sia per le corrispondenze **sia** per le non corrispondenze; `null` altrimenti.", "example": 96.0 }, "name_on_document": { "type": "string", "nullable": true, "description": "Il valore del nome estratto dal documento (il campo `is_full_name` o il primo campo di testo simile a un nome) confrontato con il nome previsto. `null` se nessun valore del nome era disponibile.", "example": "Sophia Martinez" }, "warnings": { "type": "array", "description": "Vuoto in caso di approvazione senza anomalie. Ogni voce illustra un rischio rilevato; le voci con `log_type: \"error\"` impostano `status` su `Declined`, le voci con `log_type: \"warning\"` lo impostano su `In Review`.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "DOCUMENT_AI_UNREADABLE_DOCUMENT", "DOCUMENT_AI_MISSING_REQUIRED_FIELDS", "DOCUMENT_AI_SUSPECTED_MANIPULATION", "DOCUMENT_AI_NAME_MISMATCH", "DOCUMENT_AI_UNSUPPORTED_FILE" ], "description": "Codice di rischio leggibile dalla macchina. Ognuno è regolato dalla corrispondente opzione di richiesta `document_ai_*_action`.", "example": "DOCUMENT_AI_MISSING_REQUIRED_FIELDS" }, "feature": { "type": "string", "enum": [ "DOCUMENT_AI" ], "description": "Funzionalità che ha generato l'avviso. Sempre `DOCUMENT_AI` su questo endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contesto aggiuntivo per il rischio: `{\"missing_fields\": [\"Net pay\"]}` per i campi obbligatori mancanti, `{\"name_on_document\", \"score\", \"threshold\"}` per una mancata corrispondenza del nome e il riscontro forense (`detection_method`, dettagli del produttore/editor) per sospetta manipolazione. `null` quando non c'è nulla da aggiungere.", "example": { "missing_fields": [ "Net pay" ] } }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravità derivata dall'azione configurata: `error` (DECLINE), `warning` (REVIEW), `information` (NO_ACTION)." }, "short_description": { "type": "string", "description": "Sintesi su una riga leggibile dall'utente per il rischio.", "example": "Required fields could not be extracted" }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura, interpolata con `additional_data` ove pertinente." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, o `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco dell'oggetto `metadata` inviato, o `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando la richiesta è stata elaborata (UTC, ISO 8601)." } } } } } }, "400": { "description": "Errore di validazione o di elaborazione. I problemi a livello di campo restituiscono l'envelope standard di DRF (un array di messaggi per ciascun campo interessato). I documenti crittografati o illeggibili e gli errori di estrazione restituiscono `{\"error\": ...}`.", "content": { "application/json": { "examples": { "Missing document": { "summary": "`document` non incluso nei dati del modulo", "value": { "document": [ "No file was submitted." ] } }, "Invalid fields payload": { "summary": "`fields` non è un'unica stringa contenente un array codificato in JSON", "value": { "fields": [ "fields must be a valid JSON array string." ] } }, "Duplicate field keys": { "summary": "Due elementi condividono la stessa `key`", "value": { "fields": [ "Every fields item must have a unique key." ] } }, "Conflicting expectations": { "summary": "Dati attesi per persona e azienda inviati insieme", "value": { "non_field_errors": [ "Provide either person expected-name fields or expected_company_name, not both." ] } }, "Invalid metadata": { "summary": "`metadata` non è un oggetto JSON (o contiene un carattere NUL)", "value": { "metadata": [ "Metadata must be a JSON object." ] } }, "Oversized vendor_data": { "summary": "`vendor_data` supera il limite di 2.000 byte", "value": { "vendor_data": [ "vendor_data is too long (maximum 2000 bytes)." ] } }, "Encrypted PDF": { "summary": "PDF protetto da password", "value": { "error": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Extraction failed": { "summary": "La pipeline di estrazione non ha potuto elaborare il documento", "value": { "error": [ "Error extracting Document AI information" ] } } }, "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti – e organizzazioni con fatturazione contrattuale il cui listino prezzi non include una voce per l'API Document AI – restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi elaborazione dei documenti.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } }, "Contract rate missing": { "summary": "Organizzazione con fatturazione a contratto il cui listino prezzi non include una voce per l'API Document AI", "value": { "error": "Document AI API is not included in your contract rate card. Contact support@didit.me to enable it." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "error": { "type": "string" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.document_ai.analyze(\n document=open(\"document.pdf\", \"rb\"),\n fields=\"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.documentAi.analyze({\n document: await fileFromPath(\"document.pdf\"),\n fields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DocumentAi.Analyze(ctx, didit.DocumentAiAnalyzeParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tFields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.DocumentAiAnalyzeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.documentAi().analyze(DocumentAiAnalyzeParams.builder()\n .document(Path.of(\"document.pdf\"))\n .fields(\"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "documentAi->analyze([\n 'document' => File::fromPath('document.pdf'),\n 'fields' => '[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.document_ai.analyze(\n document: Pathname(\"document.pdf\"),\n fields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.DocumentAi.AnalyzeAsync(new DocumentAiAnalyzeParams\n{\n Document = FileUpload.FromPath(\"document.pdf\"),\n Fields = \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/aml/": { "post": { "summary": "Screening AML (autonomo)", "operationId": "post_v3aml", "x-didit-sdk": { "resource": "aml", "method": "screen", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chiave opzionale di sicurezza per i nuovi tentativi, fino a 255 caratteri. Riutilizzare la stessa chiave con lo stesso corpo della richiesta restituisce la risposta originale senza eseguire né fatturare un secondo screening. Riutilizzare la chiave con un corpo diverso restituisce `409`.", "schema": { "type": "string", "maxLength": 255 } } ], "description": "Esegui lo screening di una persona o di un'azienda rispetto a dataset di PEP, sanzioni, avvisi/watchlist e notizie negative in un'unica chiamata.\n\n**Modello a due punteggi.** Ciascun hit include un `match_score` (0–100, affidabilità dell'identità) e un `risk_score` (0–100, rischio dell'entità). Gli hit il cui `match_score` è inferiore a `aml_match_score_threshold` (valore predefinito **93**) sono contrassegnati come `review_status: \"False Positive\"` e ignorati ai fini della valutazione del rischio; il `risk_score` più elevato tra gli hit rimanenti diventa `aml.score`. Lo stato finale `aml.status` segue le tue soglie: `score` > `aml_score_review_threshold` (valore predefinito **100**) → `Declined`; `score` > `aml_score_approve_threshold` (valore predefinito **80**) → `In Review`; altrimenti `Approved`. Ogni volta che `score` è diverso da zero e ≥ alla soglia di approvazione, viene aggiunto un avviso `POSSIBLE_MATCH_FOUND` (uno score pari esattamente a 0 non genera mai avvisi).\n\n**Pesi del punteggio di corrispondenza.** La somma di `aml_name_weight` + `aml_dob_weight` + `aml_country_weight` deve essere esattamente pari a 100 (valori predefiniti 60/25/15). I componenti assenti nella richiesta vengono rinormalizzati; un `document_number` corrispondente funge da chiave principale che sovrascrive `match_score` impostandolo a 100.\n\n**Latenza.** Gli screening standard si completano solitamente in pochi secondi. Con `include_adverse_media=true` l'API attende l'arricchimento con notizie negative (una pausa iniziale di circa 5 s più fino a ~25 s di polling) — configura un timeout lato client di **almeno 60 secondi**.\n\n**Persistenza.** `save_api_request` è impostato per impostazione predefinita su **true**: lo screening viene memorizzato come sessione (`request_id` funziona con `GET /v3/session/{sessionId}/decision/`), compare nella console, viene attivato un webhook `status.updated` e gli stati di revisione degli hit possono essere aggiornati in seguito. Con `save_api_request=false` non viene memorizzato nulla e `request_id` è un ID di correlazione transitorio. `include_ongoing_monitoring=true` continua a rieseguire lo screening del profilo e richiede `save_api_request=true` (imposto con un errore `400`).\n\n**Idempotenza.** Invia un'intestazione `Idempotency-Key` quando effettui un nuovo tentativo dopo un timeout o un errore transitorio. La chiave è limitata all'ambito della tua applicazione e al corpo esatto della richiesta. La prima richiesta completata memorizza la propria risposta; i successivi tentativi identici restituiscono la stessa risposta e non eseguono né fatturano un altro screening AML. Se la richiesta originale è ancora in esecuzione, riprova più tardi con la stessa chiave. Se la stessa chiave viene riutilizzata con un corpo differente, l'API restituisce `409`.\n\n**Fatturazione.** Viene addebitato un credito dell'API AML dopo il primo screening riuscito. Le risposte idempotenti riprodotte non vengono addebitate nuovamente; un saldo insufficiente restituisce `403` prima che venga eseguito qualsiasi nuovo screening.\n\n**Sandbox.** Le chiavi delle applicazioni sandbox ignorano del tutto lo screening e la fatturazione e restituiscono un risultato simulato — `Approved` con zero hit, a meno che non venga passato `sandbox_scenario`. `save_api_request` funziona esattamente come per le chiavi di produzione, quindi uno screening sandbox salvato può essere recuperato tramite `GET /v3/session/{sessionId}/decision/` e `GET /v3/session/{sessionId}/generate-pdf/`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "full_name" ], "properties": { "full_name": { "type": "string", "minLength": 2, "description": "Nome completo della persona o azienda da sottoporre a screening. Minimo **2 caratteri** (limite minimo imposto dal fornitore di screening). Un nome più corto o vuoto restituisce `400` su questo campo prima che venga eseguito qualsiasi screening, quindi non viene addebitato alcun costo.", "example": "Antonio Ejemplo Modelo" }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "default": "person", "description": "Tipo di entità da sottoporre a screening. Il valore predefinito è `person`." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data di nascita (persone) o data di costituzione (aziende), `YYYY-MM-DD`. Migliora la precisione della corrispondenza tramite il peso della data di nascita.", "example": "1972-02-29" }, "nationality": { "type": "string", "description": "Codice paese ISO 3166-1 **alpha-2** (ad es. `ES`). I codici non validi restituiscono `400`. Migliora la precisione della corrispondenza tramite il peso del paese.", "example": "ES" }, "document_number": { "type": "string", "description": "Numero del documento d'identità. Non ponderato — funge da chiave di riferimento: una corrispondenza esatta sovrascrive il `match_score` del riscontro portandolo a 100, mentre una netta mancata corrispondenza lo penalizza. Inviato al fornitore di screening come filtro di ricerca solo quando è di **2-50 caratteri**; un valore al di fuori di questo intervallo viene accettato e memorizzato, e lo screening viene comunque eseguito e fatturato, semplicemente senza restrizione per numero di documento." }, "aml_score_approve_threshold": { "type": "number", "minimum": 0, "maximum": 100, "default": 80, "description": "Soglia del punteggio di rischio pari o inferiore alla quale il risultato è `Approved`. Deve essere ≤ `aml_score_review_threshold` (altrimenti `400`)." }, "aml_score_review_threshold": { "type": "number", "minimum": 0, "maximum": 100, "default": 100, "description": "Soglia del punteggio di rischio al di sopra della quale il risultato è `Declined`. I punteggi compresi tra le due soglie generano `In Review`." }, "aml_name_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 60, "description": "Peso della somiglianza del nome nel punteggio di corrispondenza per singola occorrenza. I tre pesi devono dare come somma esattamente 100 (altrimenti `400`)." }, "aml_dob_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 25, "description": "Peso della data di nascita nel punteggio di corrispondenza per singola occorrenza." }, "aml_country_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 15, "description": "Peso del paese/nazionalità nel punteggio di corrispondenza per singola occorrenza." }, "aml_match_score_threshold": { "type": "integer", "minimum": 0, "maximum": 100, "default": 93, "description": "Soglia per hit: gli hit con `match_score` inferiore a questo valore sono `False Positive` (esclusi dalla valutazione del rischio); quelli pari o superiori sono possibili corrispondenze `Unreviewed`." }, "include_adverse_media": { "type": "boolean", "default": false, "description": "Cerca anche notizie negative sui media. Aggiunge fino a ~30 s di latenza durante la raccolta dei risultati; utilizza un timeout del client ≥60 s." }, "include_ongoing_monitoring": { "type": "boolean", "default": false, "description": "Continua a eseguire lo screening periodico di questo profilo e invia le modifiche tramite webhook. Richiede `save_api_request=true` (altrimenti `400`)." }, "save_api_request": { "type": "boolean", "default": true, "description": "Salva lo screening come sessione (visibilità nella console, endpoint della decisione, webhook, revisione dei riscontri). Imposta su `false` per un controllo senza stato." }, "vendor_data": { "type": "string", "description": "Il tuo identificatore per l'utente sottoposto a screening; restituito nella risposta e memorizzato con la sessione." }, "metadata": { "type": "object", "nullable": true, "description": "JSON a struttura libera memorizzato con la richiesta e restituito nella risposta." }, "sandbox_scenario": { "type": "string", "description": "Slug dello scenario solo per sandbox. Accettato solo quando la chiave API appartiene a un'applicazione in modalità sandbox; rifiutato nelle applicazioni di produzione. Uno screening autonomo non ha una sessione da preparare, quindi lo slug va inserito direttamente nella richiesta di screening: `decline_aml_hit` restituisce una corrispondenza con struttura identica a quella di produzione e conclude lo screening come `Declined`, `review_aml_possible_match` lo conclude come `In Review`, mentre uno scenario che non imposta alcun esito AML lascia lo screening pulito. Consulta il catalogo degli scenari su GET /v1/sandbox/scenarios/ o [Sandbox & Test Data](/it/integration/sandbox-testing).", "example": "decline_aml_hit" } } }, "example": { "full_name": "Antonio Ejemplo Modelo", "entity_type": "person", "date_of_birth": "1972-02-29", "nationality": "ES", "include_adverse_media": false, "vendor_data": "user-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/aml/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: aml-user-1234-2026-08-20' \\\n -d '{\n \"full_name\": \"Antonio Ejemplo Modelo\",\n \"entity_type\": \"person\",\n \"date_of_birth\": \"1972-02-29\",\n \"nationality\": \"ES\",\n \"include_adverse_media\": false,\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.aml.screen(\n full_name=\"Antonio Ejemplo Modelo\",\n entity_type=\"person\",\n date_of_birth=\"1972-02-29\",\n nationality=\"ES\",\n include_adverse_media=False,\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.aml.screen({\n full_name: \"Antonio Ejemplo Modelo\",\n entity_type: \"person\",\n date_of_birth: \"1972-02-29\",\n nationality: \"ES\",\n include_adverse_media: false,\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AML.Screen(ctx, didit.AMLScreenParams{\n\tFullName: \"Antonio Ejemplo Modelo\",\n\tEntityType: didit.Some(didit.AMLScreenParamsEntityType(\"person\")),\n\tDateOfBirth: didit.String(\"1972-02-29\"),\n\tNationality: didit.String(\"ES\"),\n\tIncludeAdverseMedia: didit.Bool(false),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport me.didit.Didit;\nimport me.didit.types.AmlScreenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.aml().screen(AmlScreenParams.builder()\n .fullName(\"Antonio Ejemplo Modelo\")\n .entityType(AmlScreenParams.EntityType.of(\"person\"))\n .dateOfBirth(LocalDate.parse(\"1972-02-29\"))\n .nationality(\"ES\")\n .includeAdverseMedia(false)\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "aml->screen([\n 'full_name' => 'Antonio Ejemplo Modelo',\n 'entity_type' => 'person',\n 'date_of_birth' => '1972-02-29',\n 'nationality' => 'ES',\n 'include_adverse_media' => false,\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.aml.screen(\n full_name: \"Antonio Ejemplo Modelo\",\n entity_type: \"person\",\n date_of_birth: \"1972-02-29\",\n nationality: \"ES\",\n include_adverse_media: false,\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Aml.ScreenAsync(new AmlScreenParams\n{\n FullName = \"Antonio Ejemplo Modelo\",\n EntityType = new AmlScreenParamsEntityType(\"person\"),\n DateOfBirth = \"1972-02-29\",\n Nationality = \"ES\",\n IncludeAdverseMedia = false,\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Screening completato. `aml.status` riflette le tue soglie; ogni hit pari o superiore alla soglia minima interna di inclusione è elencato in `aml.hits` con il relativo `match_score` di identità, `risk_score` dell'entità e uno `score_breakdown` che spiega la corrispondenza.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo." }, "aml": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "`Declined` quando `score` > `aml_score_review_threshold`; `In Review` quando `score` > `aml_score_approve_threshold`; `Approved` altrimenti (anche quando non è disponibile alcun punteggio)." }, "total_hits": { "type": "integer", "description": "Numero di voci in `hits`." }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Eco del tipo di entità sottoposta a screening." }, "hits": { "type": "array", "items": { "type": "object", "description": "Un hit dello screening. `match_score` (0–100) misura l'affidabilità dell'identità: gli hit inferiori a `aml_match_score_threshold` sono contrassegnati con `review_status: \"False Positive\"` ed esclusi dalla valutazione del rischio; gli hit pari o superiori alla soglia sono possibili corrispondenze con stato `\"Unreviewed\"`. `risk_score` (0–100) misura il livello di rischio dell'entità rilevata e determina il valore di `aml.score` di livello principale.", "properties": { "id": { "type": "string", "nullable": true, "description": "Identificativo stabile di Didit per l'hit: `hit_` seguito da 24 caratteri esadecimali. La stessa entità corrispondente mantiene lo stesso `id` quando il soggetto viene sottoposto nuovamente a screening. Passalo come `hit_id` agli endpoint di revisione degli hit AML." }, "url": { "type": "string", "nullable": true, "description": "URL di origine per l'entità corrispondente, quando disponibile." }, "match": { "type": "boolean", "nullable": true, "description": "Flag legacy di corrispondenza esatta. È preferibile utilizzare `match_score` + `review_status`." }, "score": { "type": "number", "nullable": true, "description": "DEPRECATO: punteggio di corrispondenza ponderato compreso nell'intervallo 0–1. Usa invece `match_score`." }, "match_score": { "type": "number", "nullable": true, "description": "Affidabilità dell'identità (0–100). Confrontata con `aml_match_score_threshold` per distinguere i falsi positivi dalle possibili corrispondenze." }, "risk_score": { "type": "number", "nullable": true, "description": "Punteggio di rischio dell'entità (0–100). Il `risk_score` più alto tra le corrispondenze diverse dai falsi positivi diventa il valore di primo livello `aml.score`." }, "target": { "type": "boolean", "nullable": true }, "caption": { "type": "string", "nullable": true, "description": "Nome visualizzato dell'entità corrispondente." }, "datasets": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "PEP", "PEP Level 1", "PEP Level 2", "PEP Level 3", "PEP Level 4", "Sanctions", "Adverse Media", "Warnings and Regulatory Enforcement", "Fitness and Probity", "SIP", "SIE", "Insolvency", "Other Lists" ] }, "description": "Categorie di rischio in cui l'entità è inclusa: `PEP` (con il relativo livello, da `PEP Level 1` a `PEP Level 4`), `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`, `SIP`, `SIE` o `Insolvency`. `Other Lists` quando la fonte dell'entità non indica nessuna di queste categorie." }, "features": { "type": "object", "nullable": true }, "properties": { "type": "object", "nullable": true, "description": "Profilo dell'entità: `name`, `alias`, `notes`, `gender`, `birthDate`, `birthPlace`, `nationality`, `position` e altri array biografici (ciascuno può essere null)." }, "rca_name": { "type": "string", "nullable": true, "description": "Nome della persona vicina correlata tramite la quale è stata rilevata la corrispondenza dell'entità, quando l'esito positivo è un RCA." }, "pep_matches": { "type": "array", "description": "Voci della lista PEP alla base di questo riscontro.", "items": { "type": "object", "properties": { "list_name": { "type": "string" }, "publisher": { "type": "string" }, "source_url": { "type": "string" }, "description": { "type": "string" }, "matched_name": { "type": "string" }, "pep_position": { "type": "string" }, "date_of_birth": { "type": "string" }, "place_of_birth": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "education": { "type": "array", "items": { "type": "string" } }, "other_sources": { "type": "array", "items": { "type": "string" } } } } }, "sanction_matches": { "type": "array", "items": { "type": "object" }, "description": "Voci della lista delle sanzioni a supporto di questa corrispondenza (stessa struttura della lista di supporto di `pep_matches`, più i campi specifici delle sanzioni)." }, "warning_matches": { "type": "array", "items": { "type": "object" }, "description": "Voci di avviso/watchlist a supporto di questa corrispondenza." }, "adverse_media_matches": { "type": "array", "description": "Articoli di notizie negative. Popolato solo quando `include_adverse_media=true`.", "items": { "type": "object", "properties": { "headline": { "type": "string" }, "summary": { "type": "string" }, "sentiment": { "type": "string" }, "sentiment_score": { "type": "number" }, "source_url": { "type": "string" }, "thumbnail": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "author_name": { "type": "string", "nullable": true }, "publication_date": { "type": "string", "nullable": true }, "adverse_keywords": { "type": "array", "items": { "type": "string" } }, "other_sources": { "type": "array", "items": { "type": "string" } } } } }, "adverse_media_details": { "type": "object", "nullable": true, "description": "Sentiment aggregato delle notizie negative per l'entità (`sentiment`, `sentiment_score`, mappa delle frequenze di `adverse_keywords`). Popolato solo quando `include_adverse_media=true`." }, "first_seen": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora della prima apparizione dell'entità nei dataset." }, "last_seen": { "type": "string", "format": "date-time", "nullable": true, "description": "Aggiornamento più recente del set di dati che ha incluso l'entità." }, "linked_entities": { "type": "array", "description": "Relazioni note dell'entità corrispondente (familiari, collaboratori, aziende).", "items": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string" } }, "relation": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "details": { "type": "array", "items": { "type": "string" } }, "active": { "type": "array", "items": { "type": "string" } } } } }, "risk_view": { "type": "object", "nullable": true, "description": "Dettaglio del rischio per dimensione (`crimes`, `countries`, `categories`, `custom_list`), ciascuno con `score`, `weightage`, `risk_level` e una mappa `risk_scores`." }, "additional_information": { "type": "object", "nullable": true, "description": "Contesto aggiuntivo a struttura libera, ad es. un array `flag_summary` che spiega perché l'entità è segnalata." }, "review_status": { "type": "string", "nullable": true, "enum": [ "False Positive", "Unreviewed", "Confirmed Match", "Inconclusive" ], "description": "`False Positive` — `match_score` inferiore a `aml_match_score_threshold`, escluso dalla valutazione del rischio. `Unreviewed` — possibile corrispondenza in attesa di revisione. `Confirmed Match` / `Inconclusive` — impostato manualmente da un revisore (tramite la Business Console) sulle sessioni salvate; tale funzionalità di revisione non fa parte di questa specifica." }, "score_breakdown": { "type": "object", "nullable": true, "description": "Modalità di calcolo di `match_score`. Nome, data di nascita e paese contribuiscono ciascuno con `_score` × `_weight_normalized` punti; i pesi vengono nuovamente normalizzati se un componente è assente dai dati sottoposti a screening. Il numero del documento non è ponderato: agisce come 'chiave fondamentale': `MATCH` sovrascrive il punteggio impostandolo a 100, `NEUTRAL` lo lascia invariato, `HARD_MISMATCH` applica una penalità.", "properties": { "name_score": { "type": "integer", "nullable": true, "description": "Somiglianza dei nomi non elaborata (0–100)." }, "name_weight": { "type": "integer", "nullable": true, "description": "Peso del nome configurato (`aml_name_weight`)." }, "name_weight_normalized": { "type": "number", "nullable": true, "description": "Peso del nome dopo la rinormalizzazione (0–100)." }, "name_contribution": { "type": "number", "nullable": true, "description": "Punti con cui il nome ha contribuito a `total_score`." }, "dob_score": { "type": "integer", "nullable": true, "description": "Punteggio della data di nascita come percentuale del suo peso (da −100 a 100)." }, "dob_weight": { "type": "integer", "nullable": true, "description": "Peso della data di nascita configurato (`aml_dob_weight`)." }, "dob_weight_normalized": { "type": "number", "nullable": true, "description": "Peso della data di nascita dopo la rinormalizzazione (0–100)." }, "dob_contribution": { "type": "number", "nullable": true, "description": "Punti con cui la data di nascita ha contribuito a `total_score`." }, "country_score": { "type": "integer", "nullable": true, "description": "Punteggio del paese come percentuale del suo peso (da −100 a 100)." }, "country_weight": { "type": "integer", "nullable": true, "description": "Peso del paese configurato (`aml_country_weight`)." }, "country_weight_normalized": { "type": "number", "nullable": true, "description": "Peso del paese dopo la rinormalizzazione (0–100)." }, "country_contribution": { "type": "number", "nullable": true, "description": "Punti con cui il paese ha contribuito a `total_score`." }, "document_number_match_type": { "type": "string", "nullable": true, "enum": [ "MATCH", "NEUTRAL", "HARD_MISMATCH" ], "description": "Risultato golden-key per il confronto del numero di documento." }, "document_number_effect": { "type": "string", "nullable": true, "description": "Descrizione di facile lettura dell'effetto del numero del documento." }, "total_score": { "type": "integer", "nullable": true, "description": "Punteggio di corrispondenza ponderato finale (0–100) — rispecchia `match_score`." } } } } } }, "score": { "type": "number", "nullable": true, "description": "Punteggio di rischio AML complessivo (0–100): il `risk_score` più alto tra i riscontri che non sono falsi positivi. Determina lo `status` tramite le due soglie." }, "screened_data": { "type": "object", "description": "Eco dei dati sottoposti a screening: `full_name`, `date_of_birth`, `nationality`, `document_number` (i campi assenti sono `null`).", "properties": { "full_name": { "type": "string" }, "date_of_birth": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Funzionalità che ha generato l'avviso." }, "risk": { "type": "string", "description": "Identificatore di rischio leggibile dalla macchina." }, "additional_data": { "type": "object", "nullable": true, "description": "Contesto aggiuntivo per l'avviso, se disponibile." }, "log_type": { "type": "string", "description": "`warning`, `information` o `error` — come il rischio ha influito sull'esito." }, "short_description": { "type": "string", "description": "Riepilogo su una riga leggibile dall'uomo." }, "long_description": { "type": "string", "description": "Spiegazione completa e leggibile." } } }, "description": "Contiene un avviso `POSSIBLE_MATCH_FOUND` ogni volta che `score` è diverso da zero e ≥ `aml_score_approve_threshold` (un punteggio esattamente pari a 0 non genera mai avvisi); vuoto altrimenti." } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato." }, "metadata": { "type": "object", "nullable": true, "description": "Eco del `metadata` inviato." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "No hits (Approved)": { "summary": "Screening pulito — zero corrispondenze", "value": { "request_id": "d27c5509-7a66-45a9-b05e-d69d9f4c336a", "aml": { "status": "Approved", "total_hits": 0, "entity_type": "person", "hits": [], "score": 0, "screened_data": { "full_name": "Maximilian Mustermann-Doe", "date_of_birth": "1992-03-14", "nationality": "DE", "document_number": null }, "warnings": [] }, "vendor_data": "user-1234", "metadata": { "internal_ref": "abc-123" }, "created_at": "2026-06-11T10:21:07.013938+00:00" } }, "PEP hit (Approved — risk below approve threshold)": { "summary": "Una possibile corrispondenza PEP; il punteggio di rischio 73 rimane al di sotto della soglia predefinita di approvazione di 80", "value": { "request_id": "0b7e7a3e-65a1-4f3d-9c7a-1de2f9a40111", "aml": { "status": "Approved", "total_hits": 1, "entity_type": "person", "hits": [ { "id": "hit_7c1e9a40b2d35f86e0a4c912", "url": "https://news.example.org/articles/sample", "match": false, "score": 0.93, "match_score": 93.0, "risk_score": 73.0, "target": null, "caption": "Antonio Ejemplo Modelo", "datasets": [ "PEP Level 1", "PEP" ], "features": null, "rca_name": "", "first_seen": "2026-01-07T00:00:00", "last_seen": "2026-01-07T00:00:00", "review_status": "Unreviewed", "properties": { "name": [ "Antonio Ejemplo Modelo", "Antonio Ejemplo" ], "alias": [ "Antonio Ejemplo Modelo", "Ejemplo Modelo, Pedro" ], "notes": [ "Prime Minister of Spain" ], "gender": [ "male" ], "birthDate": [ "1972-02-29" ], "birthPlace": [ "Madrid, Spain" ], "nationality": null, "position": null }, "risk_view": { "crimes": { "score": 0.0, "weightage": 20, "risk_level": "Low", "risk_scores": {} }, "countries": { "score": 9.64, "weightage": 30, "risk_level": "Low", "risk_scores": { "Spain": 25.71 } }, "categories": { "score": 62.5, "weightage": 50, "risk_level": "High", "risk_scores": { "PEP": 100.0, "PEP Level 1": 100.0 } }, "custom_list": {} }, "score_breakdown": { "name_score": 89, "name_weight": 60, "name_weight_normalized": 60.0, "name_contribution": 53.4, "dob_score": 100, "dob_weight": 25, "dob_weight_normalized": 25.0, "dob_contribution": 25.0, "country_score": 100, "country_weight": 15, "country_weight_normalized": 15.0, "country_contribution": 15.0, "document_number_match_type": "NEUTRAL", "document_number_effect": "No document number provided for screening", "total_score": 93 }, "pep_matches": [ { "aliases": [], "education": [], "list_name": "Presidency of the Government of Spain", "publisher": "Presidency of the Government of Spain", "source_url": "https://news.example.org/articles/sample", "description": "The Presidency of the Government is the central institutional body in Spain that supports the Prime Minister and coordinates the general action of the central government.", "matched_name": "Antonio Ejemplo Modelo", "pep_position": "", "date_of_birth": "1972-02-29", "other_sources": [], "place_of_birth": "Madrid, Spain" } ], "sanction_matches": [], "warning_matches": [], "adverse_media_matches": [], "adverse_media_details": null, "linked_entities": [ { "name": [ "Maria Begona Gomez Fernandez" ], "active": [], "status": [], "details": [], "relation": [ "spouse" ] } ], "additional_information": { "flag_summary": [ "Antonio Ejemplo Modelo has been flagged as a Level 1 Politically Exposed Person (PEP) from Spain, serving as the President of the Government of Spain." ] } } ], "score": 73.0, "screened_data": { "full_name": "Pedro Sanchez Perez-Castejon", "date_of_birth": "1972-02-29", "nationality": "ES", "document_number": null }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-11T10:23:44.812000+00:00" } } } } } }, "400": { "description": "Errore di validazione. I problemi a livello di campo restituiscono l'involucro standard di DRF (un array di messaggi per ogni campo non conforme); le regole tra campi (somma dei pesi, ordinamento delle soglie, monitoraggio senza salvataggio) restituiscono `{\"error\": [...]}`.", "content": { "application/json": { "examples": { "Missing full_name": { "summary": "`full_name` è l'unico campo obbligatorio", "value": { "full_name": [ "This field is required." ] } }, "Short full_name": { "summary": "`full_name` deve contenere almeno 2 caratteri", "value": { "full_name": [ "Ensure this field has at least 2 characters." ] } }, "Invalid nationality": { "summary": "`nationality` deve essere in formato ISO 3166-1 alpha-2", "value": { "nationality": [ "Invalid ISO 3166-1 alpha-2 country code." ] } }, "Weights do not sum to 100": { "summary": "`aml_name_weight` + `aml_dob_weight` + `aml_country_weight` ≠ 100", "value": { "error": [ "AML weights must sum to 100. Current sum: 90 (name: 50, dob: 25, country: 15)" ] } }, "Thresholds out of order": { "summary": "Soglia di approvazione superiore alla soglia di revisione", "value": { "error": [ "Approve threshold (90.0) cannot be greater than review threshold (80.0)" ] } }, "Monitoring without saving": { "summary": "`include_ongoing_monitoring=true` con `save_api_request=false`", "value": { "error": [ "Ongoing monitoring can only be enabled when the API request is saved." ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi screening o chiamata al provider.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/face-search/": { "post": { "summary": "Ricerca facciale", "description": "Cerca un'immagine del volto (1:N) nell'indice di Ricerca facciale della tua applicazione — volti registrati da sessioni di verifica, chiamate API autonome salvate, caricamenti diretti di volti da profili utente e le tue blocklist/allowlist — e ottieni corrispondenze ordinate per somiglianza, oltre ad avvisi di duplicati e blocklist.\n\n**Come funziona.** Il volto rilevato più grande in `user_image` viene convertito in embedding e cercato nell'indice, con ambito limitato alla tua applicazione. Vengono restituite in `matches` fino a **5 corrispondenze** al di sopra della soglia minima di somiglianza, ciascuna con `similarity_percentage`, la sessione di origine (`session_id`, `session_number`, `status`, `vendor_data`), `user_details` estratti durante la verifica del documento di quella sessione, i flag `is_blocklisted` / `is_allowlisted` e un discriminatore `source` (`session`, `imported` o `list_entry`).\n\n- `search_type=most_similar` (predefinito) ordina ogni volto registrato in base alla somiglianza — usalo per la deduplicazione e l'indagine su reti di frode.\n- `search_type=blocklisted_or_approved` limita i candidati ai volti in blocklist, volti in allowlist, volti provenienti da sessioni approvate e volti importati da profili utente, ordinando per prime le voci in blocklist — usalo quando l'obiettivo principale è lo screening delle blocklist.\n\n`status` è `Declined` solo quando scatta un avviso `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST`; `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` (`information`) e `MULTIPLE_FACES_DETECTED` (`warning`) non rifiutano mai. A differenza di Passive Liveness, questo endpoint **non** esclude dalla corrispondenza le sessioni precedenti con lo stesso `vendor_data`. Anche un'analisi di vitalità passiva viene eseguita internamente e salvata con la sessione memorizzata, ma il suo risultato non fa parte di questa risposta.\n\n**Fatturazione.** Ogni risposta `200` consuma un credito dell'API Ricerca facciale (scalato dal credito del tuo piano o dal saldo di ricarica). Un saldo insufficiente restituisce `403` prima di qualsiasi elaborazione delle immagini.\n\n**Persistenza della sessione e registrazione del volto (`save_api_request`, predefinito `true`).** Se impostato su `true`, la chiamata viene salvata come sessione di tipo API (Business Console, `GET /v3/session/{sessionId}/decision/` tramite il `request_id` restituito, webhook `status.updated`) e il volto cercato viene registrato nell'indice di Ricerca facciale. I volti registrati dalle chiamate di Ricerca facciale sono esclusi dai risultati futuri di Ricerca facciale, in modo che ricerche ripetute non corrispondano mai tra loro. Se impostato su `false`, la chiamata è monouso: non viene memorizzato nulla, il volto non viene registrato e i valori di `match_image_url` sono percorsi di archiviazione interni anziché URL scaricabili.\n\n**Sandbox.** Le chiavi API sandbox saltano qualsiasi elaborazione e fatturazione: dopo la validazione della richiesta (l'input non valido restituisce comunque `400`), l'endpoint restituisce un payload mock statico `Approved`, nessuna sessione viene salvata e nessun credito viene consumato.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`.", "operationId": "post_v3face-search", "x-didit-sdk": { "resource": "face_search", "method": "search", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "Immagine frontale del viso da utilizzare per la ricerca. Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Dimensione massima di caricamento: **5 MB** (i file più grandi vengono rifiutati con `400`). Le immagini vengono compresse automaticamente a ~0.5 MB prima dell'elaborazione, pertanto risoluzioni molto elevate non migliorano la precisione. L'immagine deve contenere almeno un volto rilevabile — altrimenti l'endpoint restituisce `400`. Quando sono presenti più volti, la ricerca viene eseguita su quello più grande e viene aggiunto un avviso `MULTIPLE_FACES_DETECTED`." }, "search_type": { "type": "string", "default": "most_similar", "enum": [ "most_similar", "blocklisted_or_approved" ], "description": "Politica di ricerca. `most_similar` (predefinita) classifica ogni volto registrato nella tua applicazione in base alla somiglianza. `blocklisted_or_approved` limita i candidati ai volti in blocklist, ai volti in allowlist, ai volti provenienti da sessioni approvate e ai volti dei profili utente importati — posizionando per prime le voci in blocklist.", "example": "most_similar" }, "rotate_image": { "type": "boolean", "default": false, "description": "Quando è `true`, il servizio prova rotazioni di 90 gradi dell'input e utilizza l'orientamento che offre il miglior rilevamento del volto. Utile quando manca l'orientamento EXIF. Aggiunge latenza.", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando è `true` (predefinito), memorizza la chiamata come sessione di tipo API, emette un webhook `status.updated`, pre-firma i valori di `match_image_url` e registra il volto cercato nel tuo indice di Ricerca facciale (le registrazioni di Ricerca facciale sono escluse dalle ricerche future). Quando è `false`, la ricerca è una tantum — non viene memorizzata alcuna sessione e il volto non viene registrato.", "example": true }, "vendor_data": { "type": "string", "description": "Identificativo opaco opzionale (il tuo ID utente, email, UUID...) memorizzato nella sessione persistita e restituito. Non esclude i volti dello stesso utente dai risultati di ricerca.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON: viene interpretato come oggetto.", "example": { "flow": "dedup_check" } } } }, "example": { "user_image": "(binary JPEG/PNG selfie)", "search_type": "most_similar", "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "dedup_check" } } } } }, "responses": { "200": { "description": "Ricerca facciale completata. `face_search.matches` contiene fino a 5 volti simili ordinati per somiglianza; un array vuoto indica che nessun volto registrato ha superato la soglia minima di somiglianza. `status` è `Declined` solo in caso di corrispondenze con la blocklist; le sole corrispondenze duplicate restituiscono `Approved`, quindi esamina `matches` e `warnings`, non solo `status`. Quando `save_api_request=true`, `request_id` è l'ID della sessione salvata. Ciascuna corrispondenza include `source` (`session`, `imported`, `list_entry` o `retained_template`), `vendor_user_id` e `biometric_template_id`; una corrispondenza `retained_template` proviene da un modello biometrico senza immagini conservato dopo l'eliminazione della sessione di origine e presenta campi di sessione, `match_image_url` e `user_details` impostati su `null`.", "content": { "application/json": { "examples": { "Blocklist hit (Declined)": { "summary": "Il volto corrisponde a un volto inserito nella blocklist", "value": { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "face_search": { "status": "Declined", "total_matches": 1, "matches": [ { "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "session_number": 323442, "similarity_percentage": 99.99, "source": "session", "vendor_data": "user-1", "verification_date": "2025-01-01T00:00:00Z", "user_details": { "full_name": "Jane Marie Doe", "document_type": "ID", "document_number": "X1234567" }, "match_image_url": "https:///face/3f6a1c2e/reference.jpg", "status": "Approved", "is_blocklisted": true, "is_allowlisted": false, "api_service": null, "vendor_user_id": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "biometric_template_id": null } ], "user_image": { "entities": [ { "bbox": [ 40, 40, 120, 120 ], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [ { "risk": "FACE_IN_BLOCKLIST", "feature": "LIVENESS", "additional_data": { "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "blocklisted_session_number": 323442, "api_service": null }, "log_type": "error", "short_description": "Face in blocklist", "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Duplicate found (Approved)": { "summary": "Il volto è già apparso in un'altra sessione approvata — informativo, nessun rifiuto", "value": { "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f", "face_search": { "status": "Approved", "total_matches": 1, "matches": [ { "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788", "session_number": 1024, "similarity_percentage": 87.42, "source": "session", "vendor_data": "user-9", "verification_date": "2025-11-20T09:15:00Z", "user_details": null, "match_image_url": "https:///face/9c8b7a6d/reference.jpg", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": "PASSIVE_LIVENESS", "vendor_user_id": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "biometric_template_id": null } ], "user_image": { "entities": [ { "bbox": [ 40, 40, 120, 120 ], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [ { "risk": "DUPLICATED_FACE", "feature": "LIVENESS", "additional_data": { "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788", "duplicated_session_number": 1024, "api_service": "PASSIVE_LIVENESS" }, "log_type": "information", "short_description": "Duplicated face from other approved session", "long_description": "The system identified a duplicated face from another approved session, requiring further investigation." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "No matches (Approved)": { "summary": "Nessun volto registrato ha superato la soglia minima di somiglianza", "value": { "request_id": "9d8c7b6a-5f4e-3d2c-1b0a-998877665544", "face_search": { "status": "Approved", "total_matches": 0, "matches": [], "user_image": { "entities": [ { "bbox": [ 40, 40, 120, 120 ], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo." }, "face_search": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Declined` solo quando è scattato un avviso `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST`. Le corrispondenze duplicate e gli avvisi di volti multipli non determinano mai il rifiuto." }, "total_matches": { "type": "integer", "description": "Numero di voci in `matches` (0–5).", "example": 1 }, "matches": { "type": "array", "maxItems": 5, "description": "Fino a 5 volti dal tuo indice di Ricerca facciale che superano la soglia minima di somiglianza, ordinati per somiglianza (con le voci in blocklist classificate per prime quando `search_type=blocklisted_or_approved`). Vuoto se nessun volto registrato è sufficientemente simile.", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID della sessione di verifica a cui appartiene il volto corrispondente. `null` quando `source` è `imported`, `list_entry` o `retained_template`.", "example": "882c42d5-8a4d-4d20-8080-a22f57822c86" }, "session_number": { "type": "integer", "nullable": true, "description": "Numero di sessione di facile lettura mostrato nella Business Console. `null` per le corrispondenze non legate a una sessione.", "example": 323442 }, "similarity_percentage": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Somiglianza tra il volto inviato e il volto corrispondente (0–100).", "example": 99.99 }, "source": { "type": "string", "enum": [ "session", "imported", "list_entry", "retained_template" ], "description": "Da dove è stato registrato il volto corrispondente: `session` — una sessione di verifica o una chiamata API standalone salvata; `imported` — un volto caricato direttamente su un profilo User; `list_entry` — un volto associato a uno dei tuoi elenchi; `retained_template` — un modello biometrico privo di immagini archiviato su un User, elencato sotto `/v3/biometric-templates/`." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` della sessione corrispondente o dell'utente collegato per i volti importati e con modello conservato.", "example": "user-1" }, "vendor_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID dell'utente collegato. `null` per le voci della lista e per le corrispondenze di sessione prive di utente.", "example": "2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4" }, "biometric_template_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del modello biometrico conservato. Impostato solo quando `source` è `retained_template`; `null` altrimenti.", "example": null }, "verification_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il volto corrispondente è stato originariamente acquisito o quando è stato creato un modello conservato (`YYYY-MM-DDThh:mm:ssZ`). `null` per le corrispondenze di tipo `list_entry`.", "example": "2025-01-01T00:00:00Z" }, "user_details": { "type": "object", "nullable": true, "description": "Dati di identità estratti durante la verifica del documento della sessione corrispondente. `null` quando la sessione corrispondente non ha dati del documento (es. sessioni di solo rilevamento della vitalità) e sempre `null` per le corrispondenze di tipo `retained_template`. Per le corrispondenze con `source: imported`, viene invece popolato dal profilo Utente: `full_name` impostato, `document_type`/`document_number` null.", "properties": { "full_name": { "type": "string", "nullable": true, "example": "Jane Marie Doe" }, "document_type": { "type": "string", "nullable": true, "example": "ID" }, "document_number": { "type": "string", "nullable": true, "example": "X1234567" } } }, "match_image_url": { "type": "string", "nullable": true, "description": "URL a tempo (`https:///...`) dell'immagine di riferimento del volto corrispondente quando `save_api_request=true`. Con `save_api_request=false` questo è un percorso di archiviazione interno non scaricabile direttamente. Sempre `null` per le corrispondenze di tipo `retained_template` poiché i modelli conservati non contengono immagini.", "example": "https:///face/3f6a1c2e/reference.jpg" }, "status": { "type": "string", "nullable": true, "description": "Stato della sessione corrispondente (`Approved`, `Declined`, `In Review`, …). `null` per le corrispondenze `imported`/`list_entry`.", "example": "Approved" }, "is_blocklisted": { "type": "boolean", "description": "`true` quando il volto corrispondente si trova nella tua blocklist dei volti. Qualsiasi corrispondenza sufficientemente simile presente nella blocklist comporta il rifiuto della ricerca." }, "is_allowlisted": { "type": "boolean", "description": "`true` quando il volto corrispondente si trova in una delle tue allowlist. Le corrispondenze in allowlist sopprimono gli avvisi di duplicazione." }, "api_service": { "type": "string", "nullable": true, "description": "Impostato quando il volto corrispondente è stato registrato tramite una chiamata API standalone (ad es. `PASSIVE_LIVENESS`); `null` per le normali sessioni di verifica e per i volti importati.", "example": null } } } }, "user_image": { "type": "object", "description": "Risultati del rilevamento facciale per l'immagine inviata. Le voci qui presenti contengono solo `bbox` e `confidence`.", "properties": { "entities": { "type": "array", "description": "Una voce per ogni volto rilevato. Il volto più grande è quello cercato.", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Riquadro di delimitazione `[x_min, y_min, x_max, y_max]` in pixel.", "example": [ 40, 40, 120, 120 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Affidabilità del rilevamento facciale (0–1).", "example": 0.732973 } } } }, "best_angle": { "type": "integer", "description": "Rotazione (gradi) che ha prodotto il miglior rilevamento del volto; diversa da zero solo quando `rotate_image=true` ha corretto l'orientamento. Mai null su questo endpoint (il valore predefinito è 0 quando il modello la omette).", "example": 0 } } }, "warnings": { "type": "array", "description": "Segnali di rischio. `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` (`error`) rifiutano la ricerca; `MULTIPLE_FACES_DETECTED` (`warning`) e `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` (`information`) hanno valore informativo.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "MULTIPLE_FACES_DETECTED", "FACE_IN_BLOCKLIST", "POSSIBLE_FACE_IN_BLOCKLIST", "DUPLICATED_FACE", "POSSIBLE_DUPLICATED_FACE" ], "description": "Codice di rischio leggibile dalla macchina." }, "feature": { "type": "string", "enum": [ "LIVENESS" ], "description": "Funzionalità che ha generato l'avviso. Sempre `LIVENESS` su questo endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "`null` per `MULTIPLE_FACES_DETECTED`. Le corrispondenze nella blocklist contengono `{blocklisted_session_id, blocklisted_session_number, api_service}`; i duplicati contengono `{duplicated_session_id, duplicated_session_number, api_service}` che puntano alla prima sessione corrispondente." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravità. Gli avvisi `error` portano `status` a `Declined`; le voci `warning` e `information` sono informative e non determinano mai un rifiuto da sole." }, "short_description": { "type": "string", "description": "Riepilogo del rischio su una riga leggibile dall'utente." }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura del rischio." } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, o `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco dell'oggetto `metadata` inviato, o `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp ISO 8601 (UTC) di generazione della risposta, ad es. `2026-06-12T01:04:42.763237+00:00`." } } } } } }, "400": { "description": "Errore di validazione. Restituito quando `user_image` è mancante, supera 5 MB, ha un'estensione non supportata o quando **non viene rilevato alcun volto** nell'immagine inviata. Gli errori di campo utilizzano l'envelope `{field: [messages]}` di DRF; gli errori di rilevamento del volto utilizzano `{\"error\": ...}`.", "content": { "application/json": { "examples": { "No face detected": { "summary": "L'immagine viene decodificata correttamente ma non contiene alcun volto rilevabile", "value": { "error": "No face detected in the image" } }, "Missing image": { "summary": "`user_image` non incluso nei dati del modulo", "value": { "user_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "Estensione del file diversa da tiff/jpg/jpeg/png/webp", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "Il caricamento supera il limite di 5 MB", "value": { "user_image": [ "File size should not exceed 5 MB" ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi elaborazione delle immagini.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/face-search/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'search_type=most_similar' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.face_search.search(\n user_image=open(\"user_image.jpg\", \"rb\"),\n search_type=\"most_similar\",\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"dedup_check\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.faceSearch.search({\n user_image: await fileFromPath(\"user_image.jpg\"),\n search_type: \"most_similar\",\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"dedup_check\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceSearch.Search(ctx, didit.FaceSearchSearchParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tSearchType: didit.Some(didit.FaceSearchSearchParamsSearchType(\"most_similar\")),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"dedup_check\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.FaceSearchSearchParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.faceSearch().search(FaceSearchSearchParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .searchType(FaceSearchSearchParams.SearchType.of(\"most_similar\"))\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"dedup_check\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "faceSearch->search([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'search_type' => 'most_similar',\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'dedup_check'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.face_search.search(\n user_image: Pathname(\"user_image.jpg\"),\n search_type: \"most_similar\",\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"dedup_check\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FaceSearch.SearchAsync(new FaceSearchSearchParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n SearchType = new FaceSearchSearchParamsSearchType(\"most_similar\"),\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"dedup_check\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/sessions/": { "get": { "summary": "Elenca le sessioni di verifica (KYC e/o KYB) con filtri e paginazione", "description": "Restituisce un elenco impaginato di sessioni di verifica per l'applicazione identificata dalla tua chiave API, dalla più recente alla meno recente (`session_number` decrescente).\n\n**URL canonico:** la rotta è `/v3/sessions/` (barra finale). Le richieste a `/v3/sessions` senza barra finale ricevono un reindirizzamento `301` all'URL con la barra conservando la query string; la maggior parte dei client HTTP lo segue in modo trasparente su GET.\n\n**Quando usare questo endpoint rispetto ai webhook.** Usa questo endpoint per dashboard, ricerche di back-office, riconciliazione ed esportazioni in batch. Non eseguire polling per monitorare l'avanzamento delle singole verifiche: configura invece i [webhook](/it/integration/webhooks), che inviano eventi `status.updated` non appena una sessione cambia. Per il risultato completo di una singola sessione, chiama `GET /v3/session/{sessionId}/decision/`.\n\n**Sessioni KYC e KYB.** `session_kind` seleziona quali tipi vengono elencati:\n- `user` (predefinito) - Solo sessioni di Verifica degli utenti (KYC). Comportamento retrocompatibile.\n- `business` - Solo sessioni di Verifica aziendale (KYB). Le righe hanno una struttura diversa e più ridotta (vedi lo schema della risposta).\n- `all` - Entrambi i tipi in un'unica risposta: la pagina KYC e la pagina KYB per gli stessi `limit`/`offset` vengono concatenate in `results` (prima le righe KYC), quindi una pagina può contenere fino a `2 x limit` righe. `count` è la somma di entrambi i tipi e `next`/`previous` riflettono l'impaginazione del lato KYC. Per un'impaginazione rigorosa dei dati misti, chiama `user` e `business` separatamente.\n\nOgni riga contiene un discriminatore `session_kind` (`\"user\"` o `\"business\"`).\n\n**Impaginazione.** Standard limit/offset: `limit` (predefinito 50) e `offset` (predefinito 0), con URL di pagina pronti all'uso in `next`/`previous`. Per le righe KYC `count` è esatto. Per le righe KYB `count` viene calcolato con una scansione limitata ed è bloccato a un massimo di 100: quando ci sono più di 100 corrispondenze rimane a 100, quindi itera usando `next` (o verificando se è stata restituita una pagina intera) anziché calcolare le pagine totali da `count`.\n\n**Semantica dei filtri.** Tutti i filtri si combinano con AND e si applicano alle righe KYC. Quando `session_kind` è `business` o `all`, il lato KYB rispetta i parametri condivisi `vendor_data`, `status`, `workflow_id`, `country` (codice paese del registro delle imprese), `date_from`, `date_to`, `search` (ragione sociale, numero di registrazione — inserisci i numeri di registrazione senza separatori, ad es. `DPC001` e non `DPC-001` — vendor_data, numero di sessione o UUID della sessione), `warning` e `organization_name`; i restanti filtri validi solo per KYC vengono ignorati per le righe KYB. I parametri separati da virgola (`status`, `country`, `document_type`, `region`, `workflow_id`, `document_name`, `warning`, `organization_name`, `session_type`) corrispondono a uno qualsiasi dei valori elencati (OR all'interno del parametro). `vendor_data` prevede una corrispondenza esatta: usa `search` per una corrispondenza parziale. I valori sconosciuti nei filtri di tipo elenco non restituiscono alcuna riga (nessun errore); i valori tipizzati malformati (`date_from`, `date_to`, `didit_internal_id`, `api_service`, `session_kind`) restituiscono `400` con un oggetto di errore per ciascun campo.\n\n**Ricerca.** `search` si adatta all'input: un UUID completo cerca `session_id`; le cifre (con `+ - . space` facoltativi) cercano corrispondenze per prefisso del numero di sessione, numeri di documento/personali, prefisso del numero di telefono o `vendor_data`; i valori contenenti `@` cercano corrispondenze con prefissi email; qualsiasi altro testo cerca corrispondenze con nomi (indipendentemente dagli accenti) e `vendor_data`.\n\nNon è applicato alcun limite di frequenza fisso per endpoint, ma mantieni poco frequente il polling degli elenchi e affidati ai webhook per gli aggiornamenti in tempo reale.", "operationId": "get_v3_sessions", "x-didit-sdk": { "resource": "sessions", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "session_kind", "in": "query", "required": false, "description": "Quale tipo di sessioni elencare: `user` (solo KYC, predefinito), `business` (solo KYB) o `all` (entrambe, concatenate; consulta la descrizione per la semantica di paginazione unificata). La corrispondenza non fa distinzione tra maiuscole e minuscole (`BUSINESS` funziona); qualsiasi valore diverso da una variante di maiuscole/minuscole di `user`/`business`/`all` restituisce `400`.", "schema": { "type": "string", "enum": [ "user", "business", "all" ], "default": "user" }, "example": "all" }, { "name": "limit", "in": "query", "required": false, "description": "Numero massimo di righe per pagina (per tipologia quando `session_kind=all`). Il valore predefinito è 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 20 }, { "name": "offset", "in": "query", "required": false, "description": "Numero di righe da saltare prima della prima riga restituita. Il valore predefinito è 0. È preferibile seguire gli URL `next`/`previous` della risposta.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 20 }, { "name": "status", "in": "query", "required": false, "description": "Elenco separato da virgole degli stati della sessione da includere, ad es. `Approved,In Review`. I valori fanno distinzione tra maiuscole e minuscole; consulta [Stati di verifica](/it/integration/verification-statuses). I valori sconosciuti non corrispondono a nulla.", "schema": { "type": "string" }, "example": "Approved,In Review" }, { "name": "vendor_data", "in": "query", "required": false, "description": "Filtro per corrispondenza esatta sul `vendor_data` inviato alla creazione della sessione (il tuo identificatore per l'utente/azienda). Per corrispondenze parziali, usa invece `search`.", "schema": { "type": "string" }, "example": "your-user-id-123" }, { "name": "search", "in": "query", "required": false, "description": "Un riferimento visualizzato completo come `S-0001` (utente) o `B-0001` (azienda) corrisponde unicamente a quel numero e tipo di sessione; gli zeri iniziali e le maiuscole/minuscole non influiscono sulla corrispondenza. Ricerca intelligente a testo libero. Un UUID completo corrisponde a `session_id`; un input numerico corrisponde al prefisso del numero di sessione, ai numeri di documento/personali, al prefisso telefonico o a `vendor_data`; un input contenente `@` corrisponde ai prefissi email; altro testo corrisponde ai nomi (senza distinzione di accenti) e a `vendor_data`. Il testo libero contenente cifre corrisponde inoltre ai campi di ricerca del numero di documento/personale e ai prefissi del numero di sessione.", "schema": { "type": "string" }, "example": "jane doe" }, { "name": "workflow_id", "in": "query", "required": false, "description": "UUID dei workflow separati da virgola (disponibili nella pagina Workflow della Console). Gli UUID non validi nell'elenco vengono ignorati; se nessuno è valido, il risultato è vuoto.", "schema": { "type": "string" }, "example": "9f9b1234-aaaa-bbbb-cccc-1234567890ab" }, { "name": "date_from", "in": "query", "required": false, "description": "Solo le sessioni create in questa data o successivamente (UTC), formato `YYYY-MM-DD`. Le date con formato non valido restituiscono `400`.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-01" }, { "name": "date_to", "in": "query", "required": false, "description": "Solo le sessioni create fino a questa data (UTC), formato `YYYY-MM-DD`. Per le righe KYC viene inclusa l'intera giornata; per le righe KYB il confronto è `created_at <= date_to` (mezzanotte), quindi usa la data del giorno successivo per includere un'intera giornata di sessioni KYB.", "schema": { "type": "string", "format": "date" }, "example": "2026-06-30" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ID di tag separati da virgole (`tags` della tua applicazione). Restituisce le sessioni che contengono uno qualsiasi di essi. Gli ID che non sono UUID validi vengono ignorati e, se nessuno è valido, l'elenco è vuoto." }, { "name": "decided_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Data e ora ISO 8601. Restituisce le sessioni il cui stato è cambiato l'ultima volta a partire da tale momento. Filtra in base all'orario dell'ultimo cambio di stato, non all'orario di creazione." }, { "name": "decided_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Data e ora ISO 8601. Restituisce le sessioni il cui stato è cambiato l'ultima volta prima di tale momento. Combina con `decided_from` per un intervallo semiaperto." }, { "name": "country", "in": "query", "required": false, "description": "Filtro per paese separato da virgole. Per le righe KYC: codici ISO 3166-1 alpha-3 dello stato di emissione del documento d'identità (ad es. `ESP,USA`), che possono differire dalla nazionalità. Per le righe KYB: il codice del paese dell'azienda nel registro.", "schema": { "type": "string" }, "example": "ESP,USA" }, { "name": "document_type", "in": "query", "required": false, "description": "Codici dei tipi di documento di identità verificati nella sessione, separati da virgole (solo righe KYC): `P` (passaporto), `ID` (carta d'identità), `DL` (patente di guida), `RP` (permesso di soggiorno), `SSC` (tessera di sicurezza sociale), `HIC` (tessera sanitaria), `WP` (permesso di lavoro), `TC` (tesserino del codice fiscale), `VISA`, `PSC` (carta dei servizi pubblici), `BC` (certificato di nascita), `OTHER`. Nota che il campo di risposta `document_type` contiene il nome visualizzato, non il codice.", "schema": { "type": "string" }, "example": "P,ID" }, { "name": "document_name", "in": "query", "required": false, "description": "Nomi esatti dei documenti; è possibile passare più nomi separati da virgola, ma il valore viene suddiviso in corrispondenza delle virgole solo se contiene più di un separatore ` - ` (un singolo nome contenente una virgola interna viene confrontato per intero). I nomi corrispondono a quelli riconosciuti dalla verifica del documento (fronte o retro), ad es. `Spain - Id Card (2021)`. Solo righe KYC.", "schema": { "type": "string" }, "example": "Spain - Id Card (2021)" }, { "name": "region", "in": "query", "required": false, "description": "Valori di regione/stato del documento separati da virgole (per documenti emessi su base regionale, come le patenti di guida statunitensi). Solo righe KYC.", "schema": { "type": "string" }, "example": "CA,TX" }, { "name": "didit_internal_id", "in": "query", "required": false, "description": "Filtra per identificatore interno dell'utente di Didit (il campo di risposta `didit_internal_id`) per elencare tutte le sessioni di un utente verificato. Deve essere un UUID valido; i valori non validi restituiscono `400`. Solo righe KYC.", "schema": { "type": "string", "format": "uuid" }, "example": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147" }, { "name": "session_type", "in": "query", "required": false, "description": "Canali di creazione della sessione separati da virgole: `API`, `HOSTED`, `MIGRATED`. Il valore speciale `ALL` (o l'omissione del parametro) disabilita il filtro. Solo righe KYC.", "schema": { "type": "string" }, "example": "HOSTED" }, { "name": "api_service", "in": "query", "required": false, "description": "Filtra le sessioni API standalone per servizio. I valori non validi restituiscono `400`. Solo righe KYC.", "schema": { "type": "string", "enum": [ "ID_VERIFICATION", "FACE_MATCH", "AGE_ESTIMATION", "FACE_SEARCH", "POA", "AML", "KYB_REGISTRY", "PASSIVE_LIVENESS", "DATABASE_VALIDATION", "PHONE_VERIFICATION", "EMAIL_VERIFICATION" ] }, "example": "AML" }, { "name": "screened_full_name", "in": "query", "required": false, "description": "Ricerca del nome senza distinzione di accenti all'interno dei dati sottoposti a screening AML e validazione su database. Se combinata con `api_service=AML` o `api_service=DATABASE_VALIDATION`, la ricerca è limitata ai dati sottoposti a screening di tale funzionalità. Solo righe KYC.", "schema": { "type": "string" }, "example": "Jane Doe" }, { "name": "warning", "in": "query", "required": false, "description": "Codici di rischio degli avvisi separati da virgole; restituisce le sessioni che ne hanno generato alcuno (ad es. `POSSIBLE_FRAUD`). I codici di rischio sono elencati per funzionalità nella [documentazione sugli avvisi](/it/integration/webhooks). Si applica alle righe KYC e, con i codici di avviso aziendali, alle righe KYB.", "schema": { "type": "string" }, "example": "POSSIBLE_FRAUD" }, { "name": "status_initialized_as_in_review", "in": "query", "required": false, "description": "Quando è `true`, include solo le sessioni la cui decisione è stata inizialmente impostata su `In Review` (utile per verificare il volume della revisione manuale). Solo righe KYC.", "schema": { "type": "boolean" }, "example": true }, { "name": "is_kyc_to_be_reviewed", "in": "query", "required": false, "description": "`true` restituisce le sessioni la cui verifica del documento è contrassegnata per la revisione manuale; `false` restituisce le sessioni la cui verifica del documento non è esplicitamente contrassegnata. Ometti per disattivare. Solo righe KYC.", "schema": { "type": "boolean" }, "example": true }, { "name": "euuid", "in": "query", "required": false, "description": "Filtra in base all'euuid dell'utente finale (UUID assegnato all'utente in fase di verifica, utilizzato per i deep link della Console). Deve essere un UUID valido; valori non corretti restituiscono un errore di campo 400. Solo righe KYC.", "schema": { "type": "string", "format": "uuid" }, "example": "0f8fad5b-d9cb-469f-a165-70867728950e" }, { "name": "organization_name", "in": "query", "required": false, "description": "Nomi delle organizzazioni separati da virgole. Destinato alla Console; con una chiave API (già limitata a una singola applicazione) corrisponde solo al nome della tua organizzazione.", "schema": { "type": "string" }, "example": "Acme Inc" } ], "responses": { "200": { "description": "Elenco sessioni impaginato. Gli elementi di `results` sono righe KYC, righe KYB o entrambe a seconda di `session_kind`; distingui con il campo `session_kind` di ciascuna riga.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Numero di sessioni corrispondenti ai filtri: esatto fino a 100 e limitato a 100 oltre tale soglia, pertanto non utilizzarlo come totale complessivo. Usa `next` per sapere se esistono altre pagine. Per `session_kind=all` corrisponde alla somma di entrambi i tipi, ciascuno limitato a 100.", "example": 2 }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina.", "example": "https://verification.didit.me/v3/sessions/?limit=20&offset=20" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina.", "example": null }, "results": { "type": "array", "description": "Righe delle sessioni, dalla più recente. Con `session_kind=all`, vengono prima le righe KYC, poi quelle KYB.", "items": { "oneOf": [ { "$ref": "#/components/schemas/UserSessionListItem" }, { "$ref": "#/components/schemas/BusinessSessionListItem" } ], "discriminator": { "propertyName": "session_kind", "mapping": { "user": "#/components/schemas/UserSessionListItem", "business": "#/components/schemas/BusinessSessionListItem" } } } } } }, "examples": { "KYC sessions (default)": { "summary": "session_kind=user - una sessione completata e una non avviata", "value": { "count": 2, "next": null, "previous": null, "results": [ { "session_id": "5b3720ed-d429-42ef-b67f-37ea805f48ee", "session_kind": "user", "session_number": 720, "session_url": "https://verify.didit.me/session/CuXoBYCYVO5Y", "portrait_image": "https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=...", "document_type": "Passport", "full_name": "Jane Marie Doe", "country": "ESP", "status": "Approved", "vendor_data": "your-user-id-123", "didit_internal_id": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147", "created_at": "2026-06-09T12:26:54.328364Z", "features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" }, { "feature": "IP_ANALYSIS", "status": "Approved" } ], "phone_number": { "number": "+14155552671", "is_verified": true }, "email_address": { "email": "jane@example.com", "is_verified": true }, "additional_details": { "aml": { "total_hits": 0, "entity_type": "person", "is_adverse_media_fetched": false }, "liveness": { "method": "PASSIVE", "score": 0.98 }, "face_match": { "score": 0.95 } } }, { "session_id": "038ad62f-5ebd-46c2-afe9-4b2956bf687f", "session_kind": "user", "session_number": 719, "session_url": "https://verify.didit.me/session/7RGKiO6ioGH6", "portrait_image": null, "document_type": null, "full_name": null, "country": null, "status": "Not Started", "vendor_data": "your-user-id-124", "didit_internal_id": "eb4e679d-ca4b-461f-9685-687bac29ebdb", "created_at": "2026-06-09T08:02:23.343053Z", "features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "FACE_MATCH", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" }, { "feature": "IP_ANALYSIS", "status": "Not Finished" } ], "phone_number": null, "email_address": null, "additional_details": null } ] } }, "Mixed KYC + KYB (session_kind=all)": { "summary": "session_kind=all - riga KYC seguita da una riga KYB", "value": { "count": 2, "next": null, "previous": null, "results": [ { "session_id": "5b3720ed-d429-42ef-b67f-37ea805f48ee", "session_kind": "user", "session_number": 720, "session_url": "https://verify.didit.me/session/CuXoBYCYVO5Y", "portrait_image": null, "document_type": "Identity Card", "full_name": "Jane Marie Doe", "country": "ESP", "status": "In Review", "vendor_data": "your-user-id-123", "didit_internal_id": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147", "created_at": "2026-06-09T12:26:54.328364Z", "features": [ { "feature": "ID_VERIFICATION", "status": "In Review" }, { "feature": "LIVENESS", "status": "Approved" } ], "phone_number": null, "email_address": null, "additional_details": { "liveness": { "method": "PASSIVE", "score": 0.98 } } }, { "session_id": "8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52", "session_kind": "business", "session_number": 42, "status": "Approved", "vendor_data": "your-company-id-77", "created_at": "2026-06-08T09:14:02.118450Z", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "workflow_type": "kyb", "workflow_label": "Standard KYB", "company_name": "Acme Holdings S.L.", "registration_number": "B12345678", "country": "ES" } ] } } } } } }, "301": { "description": "Reindirizzamento all'URL canonico con barra finale. Restituito quando il percorso della richiesta è `/v3/sessions` (senza barra finale); l'intestazione `Location` punta a `/v3/sessions/` preservando la query string. I client GET in genere lo seguono automaticamente." }, "400": { "description": "Parametro di query non valido. Il corpo è un oggetto indicizzato per il parametro errato.", "content": { "application/json": { "examples": { "Invalid session_kind": { "summary": "session_kind non è uno dei valori user/business/all", "value": { "session_kind": "Must be \"user\", \"business\", or \"all\"." } }, "Invalid date": { "summary": "date_from/date_to non validi", "value": { "date_from": [ "Enter a valid date." ] } }, "Invalid didit_internal_id": { "summary": "didit_internal_id non è un UUID", "value": { "didit_internal_id": [ "Enter a valid UUID." ] } }, "Invalid api_service": { "summary": "api_service non rientra tra le opzioni consentite", "value": { "api_service": [ "Select a valid choice. FOO is not one of the available choices." ] } } } } } }, "403": { "description": "Chiave API mancante, malformata o revocata. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.\n\n**Applicazione eliminata:** per alcuni minuti dopo l'eliminazione di un'applicazione, una richiesta effettuata con una delle sue chiavi API può restituire `{\"detail\": \"This application was deleted.\", \"code\": \"application_deleted\"}`. Non riprovare: l'applicazione e le sue chiavi API non esistono più. Trascorsi questi pochi minuti, la chiave viene rifiutata come qualsiasi altra chiave non valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." }, "code": { "type": "string", "description": "Motivo leggibile dalla macchina, presente solo per alcuni errori. `application_deleted`: la chiave API appartiene a un'applicazione che è stata eliminata.", "example": "application_deleted" } }, "required": [ "detail" ] }, "examples": { "Forbidden": { "summary": "x-api-key mancante o non valida", "value": { "detail": "You do not have permission to perform this action." } }, "ApplicationDeleted": { "summary": "Chiave API di un'applicazione eliminata", "value": { "detail": "This application was deleted.", "code": "application_deleted" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s 'https://verification.didit.me/v3/sessions/?status=Approved,In%20Review&date_from=2026-06-01&limit=20' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListAutoPaging(ctx, didit.SessionsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->list() as $item) {\n print_r($item);\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/share/": { "post": { "summary": "Genera un token di condivisione per una sessione di verifica completata", "description": "Genera un JWT di breve durata che consente a una specifica applicazione Didit di importare questa sessione completata. Da associare a `POST /v3/session/import-shared/`.", "operationId": "post_v3_session_share", "x-didit-sdk": { "resource": "sessions", "method": "share", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "Token di condivisione generato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "share_token": { "type": "string", "description": "JWT firmato con HS256. Passalo così com'è come `share_token` a [`POST /v3/session/import-shared/`](/sessions-api/import-shared-session) sull'applicazione di destinazione.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "for_application_id": { "type": "string", "format": "uuid", "description": "Restituisce l'UUID dell'applicazione di destinazione a cui è associato il token.", "example": "a5f3bca2-46e2-411e-90ef-a580900a57ee" }, "session_kind": { "type": "string", "enum": [ "user", "business" ], "description": "Indica se la sessione di origine è una sessione di Verifica degli utenti (KYC) o di Verifica aziendale (KYB)." } } }, "examples": { "User session": { "summary": "Condividi una sessione KYC", "value": { "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiMjBiYjNjM2ItNjE0Ni00MzlmLTg0YTQtYmQzMGQwMGFjNmEyIiwiZnJvbV9hcHBsaWNhdGlvbl9pZCI6ImRiZDIwZTM0LTQyZTktNGYyYy1iYTkxLWNmMDc2MjAxNmY2NCIsImZvcl9hcHBsaWNhdGlvbl9pZCI6ImE1ZjNiY2EyLTQ2ZTItNDExZS05MGVmLWE1ODA5MDBhNTdlZSIsImlhdCI6MTc1MzYzMDY2NiwiZXhwIjoxNzUzNjM0MjY2fQ.JJ9pNE_hqZsOtbR0XYZIWw4JzidjdEl279iUrsIkhGE", "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee", "session_kind": "user" } }, "Business session": { "summary": "Condividi una sessione KYB", "value": { "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee", "session_kind": "business" } } } } } }, "401": { "description": "Credenziali mancanti o non valide. A differenza della maggior parte degli endpoint v3, questo endpoint esegue l'autenticazione tramite il decoratore di autorizzazione e restituisce `401` se non viene presentato un token o una chiave validi.", "content": { "application/json": { "examples": { "Unauthorized": { "summary": "Non autorizzato", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "404": { "description": "Nessuna sessione con il `session_id` specificato esiste nella tua applicazione.", "content": { "application/json": { "examples": { "Not Found": { "summary": "Sessione non trovata", "value": { "detail": "Not found." } } } } } }, "400": { "description": "Errore di validazione. Gli errori di campo sono indicizzati per nome di campo; l'errore di mancato completamento arriva sotto una chiave `detail` (come array).", "content": { "application/json": { "examples": { "Wrong status": { "summary": "La sessione di origine non è terminata", "value": { "detail": [ "Only finished sessions (\"Approved\", \"Declined\", \"In Review\") can be shared." ] } }, "Target missing": { "summary": "L'applicazione di destinazione non esiste", "value": { "for_application_id": [ "Target application does not exist." ] } }, "Self-share": { "summary": "La destinazione è l'applicazione chiamante", "value": { "for_application_id": [ "Cannot share a session with the same application." ] } }, "TTL bounds": { "summary": "ttl_in_seconds fuori dai limiti", "value": { "ttl_in_seconds": [ "Ensure this value is greater than or equal to 60." ] } } } } } }, "403": { "description": "Le credenziali sono valide ma non dispongono dell'autorizzazione `write:sessions` per questa applicazione.", "content": { "application/json": { "examples": { "No Permission": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Nessuna autorizzazione" } } } } } }, "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica di origine per cui generare un token.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "for_application_id" ], "properties": { "for_application_id": { "type": "string", "format": "uuid", "description": "UUID dell'applicazione Didit che riscatterà il token. Deve esistere, non deve essere eliminata e deve essere diversa dall'applicazione chiamante. Puoi trovarlo nella Business Console sotto **Settings → Application**.", "example": "a5f3bca2-46e2-411e-90ef-a580900a57ee" }, "ttl_in_seconds": { "type": "integer", "description": "Durata del token, in secondi. Minimo `60`, massimo `86400` (24 ore). Il valore predefinito è `3600` (1 ora).", "minimum": 60, "maximum": 86400, "default": 3600, "example": 3600 } } }, "example": { "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee", "ttl_in_seconds": 7200 } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/share/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"for_application_id\": \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n \"ttl_in_seconds\": 7200\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.share(\n \"11111111-2222-3333-4444-555555555555\",\n for_application_id=\"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n ttl_in_seconds=7200,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.share(\"11111111-2222-3333-4444-555555555555\", {\n for_application_id: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n ttl_in_seconds: 7200,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Share(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsShareParams{\n\tForApplicationID: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n\tTTLInSeconds: didit.Int(7200),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsShareParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().share(\"11111111-2222-3333-4444-555555555555\", SessionsShareParams.builder()\n .forApplicationId(\"a5f3bca2-46e2-411e-90ef-a580900a57ee\")\n .ttlInSeconds(7200L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->share('11111111-2222-3333-4444-555555555555', [\n 'for_application_id' => 'a5f3bca2-46e2-411e-90ef-a580900a57ee',\n 'ttl_in_seconds' => 7200,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.share(\n \"11111111-2222-3333-4444-555555555555\",\n for_application_id: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n ttl_in_seconds: 7200\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ShareAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsShareParams\n{\n ForApplicationId = \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n TtlInSeconds = 7200,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/import-shared/": { "post": { "summary": "Riscatta un token di condivisione per clonare una sessione di verifica nella tua applicazione", "description": "Riscatta un token di condivisione per clonare una sessione KYC o KYB nell'applicazione chiamante con un nuovo `session_id`. Non idempotente — un token si riscatta una sola volta per destinatario.", "operationId": "post_v3_session_import_shared", "x-didit-sdk": { "resource": "sessions", "method": "import_shared", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "201": { "description": "Sessione clonata. Il corpo è il payload di decisione V3 per entrambi i tipi, discriminati da `session_kind`: `\"user\"` (KYC) con blocchi di funzionalità basati su elenchi come `id_verifications`, `liveness_checks`, `aml_screenings`; `\"business\"` (KYB) con blocchi come `registry_checks` e `key_people_checks`. Entrambi includono `shared_from_session` — il `session_id` della sessione originale nell'applicazione di origine. Con `trust_review: false`, lo `status` della sessione clonata viene forzato a `In Review`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDecision" }, "examples": { "User session imported": { "summary": "Sessione KYC clonata (troncata — in realtà payload decisionale V3 completo)", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "session_kind": "user", "shared_from_session": "99999999-8888-7777-6666-555555555555", "session_number": 43762, "session_url": null, "status": "In Review", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "user-1", "created_at": "2026-05-17T08:42:11Z", "expires_at": "2026-05-24T08:42:11Z" } }, "Business session imported": { "summary": "Sessione KYB clonata (troncata — in realtà payload decisionale V3 KYB completo)", "value": { "session_id": "22222222-3333-4444-5555-666666666666", "session_kind": "business", "shared_from_session": "88888888-7777-6666-5555-444444444444", "session_number": 982, "session_url": null, "status": "Approved", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "company-1" } } } } } }, "400": { "description": "Errore di validazione (token non valido, scaduto, con destinazione errata o che fa riferimento a una sessione che non esiste più).", "content": { "application/json": { "examples": { "Invalid Share Token": { "summary": "JWT non valido", "value": { "share_token": [ "Invalid share token." ] } }, "Expired Share Token": { "summary": "Token con `exp` scaduto", "value": { "share_token": [ "Share token has expired." ] } }, "Wrong audience": { "summary": "Token non associato a questa applicazione", "value": { "share_token": [ "This token is not valid for this application." ] } }, "Original missing": { "summary": "La sessione di origine è stata eliminata", "value": { "share_token": [ "Original session does not exist." ] } } } } } }, "403": { "description": "Chiave API mancante (una chiave errata, revocata o scaduta riceve `401`), oppure questa sessione di origine è già stata importata nell'applicazione chiamante (un solo riscatto per destinatario).", "content": { "application/json": { "examples": { "Forbidden": { "summary": "Vietato", "value": { "detail": "You do not have permission to perform this action." } }, "Already imported": { "summary": "Origine già importata una volta", "value": { "detail": "This session has already been shared with your application." } } } } } }, "404": { "description": "`workflow_id` non appartiene all'applicazione chiamante.", "content": { "application/json": { "examples": { "Workflow not found": { "summary": "Workflow sconosciuto", "value": { "detail": "Workflow does not exist for this application." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "share_token", "trust_review", "workflow_id" ], "properties": { "share_token": { "type": "string", "description": "Token di condivisione JWT emesso da [`POST /v3/session/{sessionId}/share/`](/sessions-api/share-session).", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "trust_review": { "type": "boolean", "description": "Se `true`, la sessione clonata mantiene lo `status` finale dell'origine. Se `false`, viene forzata in `In Review`.", "example": false }, "workflow_id": { "type": "string", "format": "uuid", "description": "UUID di un workflow nell'applicazione chiamante. Gli ID appartenenti ad altre applicazioni vengono rifiutati con `404`.", "example": "9f9b1234-aaaa-bbbb-cccc-1234567890ab" }, "vendor_data": { "type": "string", "nullable": true, "description": "Sostituzione opzionale per il `vendor_data` della sessione clonata.", "example": "user-1" } } }, "example": { "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "trust_review": false, "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "user-1" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/import-shared/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"share_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"trust_review\": false,\n \"workflow_id\": \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n \"vendor_data\": \"user-1\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.import_shared(\n share_token=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n trust_review=False,\n workflow_id=\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n vendor_data=\"user-1\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.importShared({\n share_token: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n trust_review: false,\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n vendor_data: \"user-1\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ImportShared(ctx, didit.SessionsImportSharedParams{\n\tShareToken: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n\tTrustReview: false,\n\tWorkflowID: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n\tVendorData: didit.String(\"user-1\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsImportSharedParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().importShared(SessionsImportSharedParams.builder()\n .shareToken(\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\")\n .trustReview(false)\n .workflowId(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\")\n .vendorData(\"user-1\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->importShared([\n 'share_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',\n 'trust_review' => false,\n 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab',\n 'vendor_data' => 'user-1',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.import_shared(\n share_token: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n trust_review: false,\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n vendor_data: \"user-1\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ImportSharedAsync(new SessionsImportSharedParams\n{\n ShareToken = \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n TrustReview = false,\n WorkflowId = \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n VendorData = \"user-1\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/kyb/search/": { "post": { "summary": "Ricerca azienda nel registro KYB (autonoma)", "operationId": "post_v3_kyb_search", "x-didit-sdk": { "resource": "kyb", "method": "search", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Cerca nei registri delle imprese ufficiali le aziende candidate per nome e/o numero di registrazione. Questo è il passaggio 1 del flusso del registro in due passaggi: la **ricerca** restituisce candidati con dati essenziali, poi `POST /v3/kyb/select/` recupera il profilo completo di un candidato.\n\n**Fatturazione della ricerca.** Le ricerche riuscite che utilizzano una fonte a pagamento di dati aziendali costano USD 0.50 per richiesta, indipendentemente dal numero di candidati. Risultati vuoti, errori e risultati forniti esclusivamente da altre fonti non vengono addebitati. Il prezzo applicabile viene riservato prima della ricerca; un saldo insufficiente restituisce 403 con codice `insufficient_credits`. Si applicano le tariffe contrattuali concordate e una tariffa di ricerca contrattuale non configurata restituisce 403. Le ricerche in sandbox sono gratuite. La ripetizione di una ricerca riuscita può comportare un nuovo addebito; la consegna del callback non aggiunge costi. Il recupero del profilo viene fatturato separatamente. Questa tariffa di ricerca si applica anche a v2. I candidati hanno sempre `fetch_status: \"pending\"`: i dati aziendali completi vengono recuperati (e fatturati) solo al momento della selezione.\n\n**`kyb_response_id` è effimero.** È un identificatore per singola ricerca, non un ID azienda stabile. Effettua la selezione tempestivamente dopo la ricerca ed esegui nuovamente la ricerca per ottenere un nuovo identificatore invece di memorizzarlo.\n\n**`tier` seleziona la catena di provider.** `tier` specifica il livello di registro su cui viene eseguita la ricerca: `basic` (il valore predefinito, la catena Lite), `shareholders` o `ubo`. La ricerca utilizza la catena di provider che serve quel livello e non è sempre la stessa catena letta dalla ricerca Lite, quindi una ricerca Lite vuota non è la prova che il registro non contenga l'azienda: cerca di nuovo al livello necessario. Per un paese che non offre il livello specificato, la ricerca viene eseguita al livello più alto disponibile fino a quello indicato. Recupera il candidato dall'endpoint associato a quel livello: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/`.\n\n**Autenticazione.** `POST /v3/kyb/search/` (e `/v2/`) accetta la chiave API della tua applicazione nell'intestazione `x-api-key`. L'endpoint ospitato `POST /v1/kyb/search/` è la rotta autenticata tramite sessione chiamata da un flusso di verifica ospitato: risponde `403` a una chiave API e non accetta alcun `tier` — la catena viene selezionata dalla configurazione del registro KYB del workflow.\n\n**Due modalità.**\n- *Sincrona (predefinita):* l'API esegue il polling del registro fino alla risoluzione della ricerca e restituisce l'elenco finale dei candidati (`search_resolved: true`).\n- *Asincrona:* passando `webhook_url`, l'API risponde immediatamente — solitamente con `search_status: \"pending\"` e un elenco di candidati vuoto — per poi inviare una POST con callback `kyb.registry_search.resolved` al tuo URL una volta terminata la ricerca nel registro. Il corpo del callback è `{\"event_id\", \"event_type\": \"kyb.registry_search.resolved\", \"request_id\", \"vendor_data\", \"metadata\", \"search_status\", \"search_resolved\", \"kyb_registry\", \"timestamp\", \"created_at\"}` — si noti che `timestamp` e `created_at` nel callback sono numeri interi epoch, a differenza del formato ISO di `created_at` in questo endpoint — e viene inviato **non firmato** (intestazione `X-Didit-Unsigned-Callback: true`, senza `X-Signature`).\n\n**Codici paese.** ISO 3166-1 alpha-2 (`GB`, `DE`), oltre ai codici di suddivisione `XX-YY` dove i registri sono regionali — ad es. `US-CA` per la California.\n\n**Sandbox.** Le chiavi delle applicazioni sandbox restituiscono un singolo candidato statico senza contattare alcun registro.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "country_code" ], "properties": { "country_code": { "type": "string", "maxLength": 10, "description": "Codice ISO 3166-1 alpha-2 del paese nel cui registro delle imprese effettuare la ricerca. Ad esempio, `GB`. Laddove i registri delle imprese operano a livello statale o provinciale, aggiungi il codice di suddivisione ISO 3166-2 come `XX-YY`: `US-CA` effettua la ricerca nel registro della California. Le ricerche relative agli Stati Uniti richiedono sempre la suddivisione: un semplice `US` viene rifiutato. Non fa distinzione tra maiuscole e minuscole; viene normalizzato in maiuscolo.", "example": "GB" }, "name": { "type": "string", "maxLength": 255, "description": "Ragione sociale da cercare. È obbligatorio specificare `name` oppure `registration_number`.", "example": "Tesco" }, "registration_number": { "type": "string", "maxLength": 100, "description": "Numero di registrazione del registro delle imprese da cercare. È obbligatorio indicare `name` oppure `registration_number`." }, "tier": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "default": "basic", "description": "Livello del registro delle imprese sulla cui catena di provider viene eseguita questa ricerca. `basic` (predefinito) cerca nella catena Lite del paese; `shareholders` e `ubo` cercano nella catena dell'assetto proprietario di quel livello, che può essere una fonte diversa, quindi una ricerca Lite vuota non dimostra che l'azienda sia assente dal registro. Per un paese che non offre il livello indicato, la ricerca viene eseguita al livello più alto disponibile fino a quello richiesto. Recupera il candidato dall'endpoint che offre il livello cercato: `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` o `POST /v3/kyb/ubo/`.", "example": "basic" }, "search_type": { "type": "string", "enum": [ "contains" ], "default": "contains", "description": "Strategia di corrispondenza dei nomi applicata dalla ricerca nel registro. `contains` è l'unico valore accettato: nessuna fonte di registro utilizzata per la ricerca offre una modalità con prefisso o fuzzy, pertanto `start_with` e `fuzzy` vengono rifiutati con `400` (`not a valid choice`)." }, "vendor_data": { "type": "string", "description": "Il tuo identificatore per questa ricerca; restituito nella risposta e incluso nel callback webhook." }, "metadata": { "type": "object", "nullable": true, "description": "JSON a struttura libera; restituito nella risposta e incluso nel callback del webhook." }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 500, "description": "Passa la ricerca alla modalità asincrona: l'API risponde immediatamente e invia una chiamata POST di callback `kyb.registry_search.resolved` non firmata a questo URL quando l'elenco dei candidati è pronto." } } }, "example": { "country_code": "GB", "name": "Tesco", "search_type": "contains", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/search/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"country_code\": \"GB\",\n \"name\": \"Tesco\",\n \"search_type\": \"contains\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.search(\n country_code=\"GB\",\n name=\"Tesco\",\n search_type=\"contains\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.search({\n country_code: \"GB\",\n name: \"Tesco\",\n search_type: \"contains\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Search(ctx, didit.KYBSearchParams{\n\tCountryCode: \"GB\",\n\tName: didit.String(\"Tesco\"),\n\tSearchType: didit.Some(didit.KYBSearchParamsSearchType(\"contains\")),\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KybSearchParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().search(KybSearchParams.builder()\n .countryCode(\"GB\")\n .name(\"Tesco\")\n .searchType(KybSearchParams.SearchType.of(\"contains\"))\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->search([\n 'country_code' => 'GB',\n 'name' => 'Tesco',\n 'search_type' => 'contains',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.search(\n country_code: \"GB\",\n name: \"Tesco\",\n search_type: \"contains\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.SearchAsync(new KybSearchParams\n{\n CountryCode = \"GB\",\n Name = \"Tesco\",\n SearchType = new KybSearchParamsSearchType(\"contains\"),\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Ricerca accettata. La modalità sincrona restituisce l'elenco definitivo dei candidati; la modalità webhook restituisce immediatamente una risposta (spesso `search_status: \"pending\"`) e consegna l'elenco finale tramite la callback `kyb.registry_search.resolved`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Con `webhook_url`: l'ID salvato della richiesta di ricerca, restituito come `request_id` nel callback `kyb.registry_search.resolved`. Senza `webhook_url`: un UUID di correlazione temporaneo (la ricerca non viene memorizzata)." }, "kyb_registry": { "$ref": "#/components/schemas/KYBRegistrySearchResults" }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato." }, "metadata": { "type": "object", "nullable": true, "description": "Eco del `metadata` inviato." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved search": { "summary": "Modalità sincrona — elenco finale dei candidati", "value": { "request_id": "0c7e9a40-3a13-4f7e-8a44-9d2e2f1c5b6a", "kyb_registry": { "companies": [ { "kyb_response_id": "69aeeb95febb0f1704042259", "name": "Tesco PLC", "registration_number": "00445790", "status": "active", "type": "Public Limited Company", "risk_level": null, "fetch_status": "pending" }, { "kyb_response_id": "69aeeb95febb0f170404225a", "name": "E-TESCO LTD", "registration_number": "15168476", "status": "active", "type": "Private Limited Company", "risk_level": null, "fetch_status": "pending" } ], "pagination": { "total": 2, "page": 1, "per_page": 25 }, "search_status": "resolved", "search_resolved": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:40:00.000000+00:00" } }, "Pending search (webhook mode)": { "summary": "`webhook_url` fornito — i candidati arrivano tramite il callback kyb.registry_search.resolved", "value": { "request_id": "5f2d8c1b-7e4a-4b9c-9f0d-3a6e8c2b1d4f", "kyb_registry": { "companies": [], "pagination": { "total": 0, "page": 1, "per_page": 25 }, "search_status": "pending", "search_resolved": false }, "vendor_data": "company-1234", "metadata": { "source": "onboarding" }, "created_at": "2026-06-11T10:41:00.000000+00:00" } } } } } }, "400": { "description": "Errore di validazione. I problemi a livello di campo utilizzano l'involucro standard di DRF; la regola su nome/numero di registrazione genera una segnalazione sotto `non_field_errors`. Un paese non coperto dai registri restituisce `400` con `code: kyb_registry_country_unsupported`.", "content": { "application/json": { "examples": { "Missing search criteria": { "summary": "Né `name` né `registration_number` forniti", "value": { "non_field_errors": [ "Either 'name' or 'registration_number' is required." ] } }, "Invalid country_code": { "summary": "Deve essere `XX` (alpha-2) o la suddivisione `XX-YY`", "value": { "country_code": [ "country_code must be a 2-letter ISO code." ] } }, "Invalid search_type": { "summary": "È accettato solo `contains`", "value": { "search_type": [ "\"start_with\" is not a valid choice." ] } }, "Invalid webhook_url": { "summary": "`webhook_url` deve essere un URL valido", "value": { "webhook_url": [ "Enter a valid URL." ] } }, "Country not covered": { "summary": "Nessun registro delle imprese è disponibile per il paese", "value": { "detail": "Company registry search is not available for this country. Enter the company details manually to continue.", "code": "kyb_registry_country_unsupported" } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Restituito inoltre prima di eseguire la ricerca quando la tariffa di ricerca applicabile non può essere coperta (`code: \"insufficient_credits\"`), o quando manca una tariffa di ricerca contrattuale.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato, oppure la quota di ricerche disponibili è esaurita. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600), con intestazioni `X-RateLimit-*` e `Retry-After`. Separatamente, le ricerche a pagamento nei registri sono limitate a 600 per applicazione all'ora: oltre tale soglia la risposta è `429` con `code: kyb_registry_search_limit_reached`, mentre le ricerche servite esclusivamente da fonti gratuite continuano a funzionare. Attendi e cerca di nuovo più tardi.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } }, "Search allowance spent": { "summary": "Più di 600 ricerche a pagamento nell'ultima ora", "value": { "detail": "The maximum number of company registry searches for this session has been reached. Enter the company details manually to continue.", "code": "kyb_registry_search_limit_reached" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } }, "502": { "description": "Il fornitore del registro delle imprese (KYB) è temporaneamente non disponibile: risposta 5xx, timeout o errore di connessione dal registro a monte. La ricerca non viene fatturata. Riprova più tardi oppure, nel flusso di verifica ospitato di Didit, all'utente viene offerto automaticamente l'inserimento manuale dell'azienda anziché un errore che consente solo un nuovo tentativo.", "content": { "application/json": { "examples": { "Registry provider outage": { "summary": "Il provider del registro non ha risposto alla ricerca", "value": { "detail": "The KYB registry provider is temporarily unavailable. Please try again shortly.", "code": "kyb_registry_provider_unavailable" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/v3/kyb/select/": { "post": { "summary": "Selezione azienda nel registro KYB — Livello Lite (autonoma)", "operationId": "post_v3_kyb_select", "x-didit-sdk": { "resource": "kyb", "method": "select", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Recupera il profilo di registro **Lite** di un candidato restituito da `POST /v3/kyb/search/` — dettagli aziendali, sede legale, identificativi, stato, attività e amministratori, oltre al payload grezzo del registro. Gli azionisti e i titolari effettivi sono venduti tramite `POST /v3/kyb/shareholders/` e `POST /v3/kyb/ubo/`.\n\n**Abbinamento con la ricerca.** Passa il `kyb_response_id` del candidato esattamente come restituito da una ricerca della stessa applicazione. L'handle è temporaneo e limitato a quella ricerca — effettua la selezione tempestivamente e ripeti la ricerca per ottenere un nuovo handle anziché memorizzarlo.\n\n**Fatturazione.** Ogni selezione viene fatturata al prezzo Lite del paese (l'eventuale tariffa di ricerca è separata); vedi [Prezzi del registro KYB](/it/getting-started/kyb-registry-pricing). Il saldo viene verificato prima di qualsiasi chiamata al registro (`403` in caso di saldo insufficiente) e l'addebito viene registrato sulla sessione aziendale creata.\n\n**La persistenza è obbligatoria.** Ogni selezione crea una sessione aziendale (il cui id è il `request_id`) in modo da consentire il monitoraggio della fatturazione e del recupero; viene visualizzata nella console. `save_api_request` è accettato per simmetria ma deve essere `true` (impostazione predefinita) — l'invio di `false` restituisce `400`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistryCandidateRequest" }, "example": { "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/select/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"kyb_response_id\": \"69aeeb95febb0f1704042259\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.select(\n kyb_response_id=\"69aeeb95febb0f1704042259\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.select({\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Select(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KYBRegistryCandidateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().select(KYBRegistryCandidateRequest.builder()\n .kybResponseId(\"69aeeb95febb0f1704042259\")\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->select([\n 'kyb_response_id' => '69aeeb95febb0f1704042259',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.select(\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.SelectAsync(new KYBRegistryCandidateRequest\n{\n KybResponseId = \"69aeeb95febb0f1704042259\",\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Azienda recuperata e fatturata. `kyb_registry` include il profilo completo; verifica `data_resolved` — se `false`, il registro delle imprese era ancora in fase di elaborazione e il record salvato si completa automaticamente una volta risolto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione aziendale creata per questo recupero. Il record memorizzato (visibile nella console) continua ad aggiornarsi se la ricerca nel registro viene completata dopo la risposta." }, "registry_tier_requested": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "Il livello venduto da questo endpoint: `basic` (Lite) per select, `shareholders`, `ubo`." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "Il livello effettivamente fornito e fatturato. Inferiore a quello richiesto quando i registri del paese non contengono dati sull'assetto proprietario, oppure il registro non ha record sull'assetto proprietario per questa azienda." }, "kyb_registry": { "type": "object", "description": "Profilo aziendale completo del registro delle imprese.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID Didit per questo record aziendale." }, "node_id": { "type": "string", "example": "feature_kyb_registry" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review" ], "description": "Valutazione di Didit sulla verifica del registro delle imprese (ad es. `In Review` quando l'azienda non è attiva nel registro o non è stato possibile ricavare i dati sull'assetto proprietario)." }, "registry_status": { "type": "string", "nullable": true, "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off" ], "description": "Stato aziendale normalizzato come riportato dal registro." }, "data_resolved": { "type": "boolean", "description": "`true` quando il registro ha restituito il profilo completo. `false` quando il registro era ancora in elaborazione dopo il polling — il record memorizzato viene completato automaticamente una volta che il registro ha completato l'elaborazione." }, "company_name": { "type": "string", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "example": "00445790" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2.", "example": "GB" }, "region": { "type": "string", "nullable": true, "description": "Codice della suddivisione quando il registro è regionale (ad es. `CA` per `US-CA`); altrimenti vuoto." }, "company_type": { "type": "string", "nullable": true, "example": "Public Limited Company" }, "incorporation_date": { "type": "string", "format": "date", "nullable": true, "example": "1947-11-27" }, "registered_address": { "type": "string", "nullable": true, "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA" }, "tax_number": { "type": "string", "nullable": true, "example": "GB412 8925 93" }, "risk_level": { "type": "string", "nullable": true, "description": "Livello di rischio riportato dal registro delle imprese, se disponibile." }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "Stato di verifica tra giurisdizioni: `verified` quando lo stato nel registro ne attesta la validità operativa (`active`), `failed` quando indica che l'azienda non è più operativa (ad esempio `dissolved`), altrimenti `unknown`. `null` per un'azienda che non proviene da un registro delle imprese e mentre una selezione è ancora `pending`." }, "is_from_registry": { "type": "boolean", "description": "Sempre `true` per questo endpoint — il profilo è stato recuperato da un registro ufficiale." }, "fetch_status": { "type": "string", "enum": [ "pending", "resolved" ], "description": "Ciclo di vita del recupero dal registro delle imprese. Riflesso da `data_resolved`." }, "alternative_names": { "type": "string", "nullable": true, "description": "Denominazioni aziendali alternative, commerciali, precedenti o nella lingua originale sotto forma di testo, se segnalate." }, "nature_of_business": { "type": "string", "nullable": true, "description": "Descrizione dell'attività o codice di classificazione, se segnalato." }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "Importo decimale sotto forma di stringa, se comunicato." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Codice ISO 4217, se indicato." }, "website": { "type": "string", "nullable": true, "example": "https://www.tesco.com/" }, "email": { "type": "string", "nullable": true, "example": "customer.service@tesco.co.uk" }, "phone": { "type": "string", "nullable": true, "example": "03301231688" }, "legal_entity_identifier": { "type": "string", "nullable": true, "description": "LEI, se segnalato." }, "location_of_registration": { "type": "string", "nullable": true, "description": "Registro delle imprese/giurisdizione presso cui l'azienda è registrata, se indicati." }, "vat_number": { "type": "string", "nullable": true, "description": "Partita IVA UE, se raccolta durante il passaggio del registro ospitato o modificata successivamente. Al momento della selezione in genere non è ancora impostata: la validazione della partita IVA e dell'identificativo fiscale viene eseguita quando l'utente finale invia il passaggio del registro nel flusso ospitato." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Risultato della validazione della partita IVA o, qualora non presente, del `tax_number`, al momento dell'invio al registro. `valid` / `invalid`: stabilito dal registro ufficiale del paese (VIES UE, Norvegia, Svizzera, Brasile, Colombia, Costa Rica, Ecuador, Paraguay; per la Polonia anche dal registro IVA nazionale). `format_valid` / `invalid_format`: stabilito dalle regole di formato e cifra di controllo del paese laddove non sia possibile interrogare alcun registro. `could_not_validate`: il registro non era disponibile. `not_applicable`: nessun numero, paese privo di registro o regole, oppure sessione sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "Il numero verificato, così come noto alla fonte (ad esempio la partita IVA derivata da un SIREN francese o un RSIN olandese). `null` quando non è stato eseguito alcun controllo." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "La fonte che ha stabilito `vat_validation_status`: un registro ufficiale, oppure `format_rules`. `null` se non è stato eseguito alcun controllo." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registrato presso la fonte che ha validato il numero, quando ne fornisce uno. Impostato solo quando lo stato è `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Indirizzo registrato presso la fonte che ha convalidato il numero, quando ne comunica uno. Impostato solo quando lo stato è `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp del controllo. `null` se non è stato eseguito alcun controllo." }, "financial_summary": { "type": "object", "nullable": true, "description": "Dettagli sulle azioni/sul capitale riportati dal registro delle imprese (valuta, azioni totali, categorie di azioni), se disponibili." }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MELISSA BETHELL" }, "designation": { "type": "string", "nullable": true, "description": "Denominazione del registro non elaborata (ad es. `Director`, `Secretary`)." }, "role": { "type": "string", "description": "Ruolo normalizzato derivato dalla qualifica. Set completo di 17 valori del modello; l'analisi del registro su questo endpoint genera tipicamente director, non_executive_director, secretary, chairman o company_officer.", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "company_officer", "settlor", "protector", "investor", "other" ] }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "description": "`false` quando il registro contrassegna l'incarico come terminato per dimissioni." }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending" ], "description": "Stato di una sessione KYC associata, se ne è stata avviata una per questo funzionario. `null` altrimenti." }, "kyc_session_url": { "type": "string", "nullable": true, "description": "URL di verifica della sessione KYC associata, se esistente." }, "first_name": { "type": "string", "nullable": true, "description": "Nome quando esplicitamente riportato dal registro; non dedotto dal nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Cognome quando esplicitamente riportato dal registro." }, "address": { "type": "string", "nullable": true, "description": "Indirizzo dell'amministratore riportato dal registro." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina dell'amministratore.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data di fine dell'incarico, quando indicata.", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa comunicata dal registro delle imprese. Null se sono noti solo l'anno o il mese di nascita.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Anno di nascita riportato dal registro delle imprese, anche quando la data completa non è disponibile." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mese di nascita riportato dal registro delle imprese. Null se è noto solo l'anno." } } }, "description": "Amministratori, segretari e altri dirigenti estratti dal registro." }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se il titolare è una persona fisica o un'entità aziendale." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Ruoli normalizzati (ad es. `ubo`, `shareholder`)." }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferiore della fascia di assetto proprietario riportata dal registro (ad es. `25%`)." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superiore della fascia di assetto proprietario riportata dal registro delle imprese." }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending" ] }, "kyc_session_url": { "type": "string", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "Percentuale di assetto proprietario analizzata (limite massimo, con fallback al limite minimo)." }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa, se indicata.", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina, se comunicata.", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } }, "description": "Titolari effettivi / persone con controllo significativo estratti dal registro. Può essere vuoto se il registro non espone l'assetto proprietario." }, "addresses": { "type": "array", "nullable": true, "description": "Ogni indirizzo indicato dal registro, in un formato canonico. Null se non ne indica alcuno.", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "Le attività con cui il registro classifica l'azienda, in formato canonico. Null quando non ne viene indicata alcuna.", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Date di deposito presso il registro delle imprese, se disponibili. Le dichiarazioni annuali e le assemblee generali utilizzano last_annual_return_date e last_agm_date; sono distinte dai bilanci di esercizio." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "description": "Sempre `null` su questo endpoint (utilizzato dal flusso KYB ospitato quando gli utenti finali modificano i dati del registro)." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Sempre `null` su questo endpoint." }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Impostato quando un revisore della console modifica il record in un secondo momento." }, "is_editable": { "type": "boolean", "description": "Indica se i dati provenienti dal registro delle imprese possono ancora essere modificati nel flusso ospitato o nella console." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "Corrisponde al valore di primo livello `registry_tier_delivered`." }, "registry_ownership_status": { "type": "string", "nullable": true, "enum": [ "not_requested", "delivered", "not_held", "unavailable" ], "description": "`delivered` quando i dati sull'assetto proprietario sono stati restituiti, `not_held` quando il registro delle imprese ha risposto e non elenca questa azienda (vedi `registry_data.ownership_error`), `unavailable` quando è stato richiesto un livello di assetto proprietario ma il registro non ne disponeva per questa azienda o non è stato possibile interrogarlo (vedi `registry_data.ownership_error`), `not_requested` per il livello Lite." }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "Il livello del registro ordinato dal workflow: `basic`, `shareholders` o `ubo`. Anche in `ownership.tier_requested`." }, "registry_monitoring": { "type": "object", "nullable": true, "description": "Il monitoraggio del registro più recente per l'azienda, o `null` quando non ne esiste alcuno.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "I campi aziendali che il monitor monitora." } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato." }, "metadata": { "type": "object", "nullable": true, "description": "Eco del `metadata` inviato." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved company": { "summary": "Profilo completo del registro delle imprese (elenco degli amministratori troncato per brevità)", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d", "node_id": "feature_kyb_registry", "status": "In Review", "registry_status": "active", "data_resolved": true, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": "", "company_type": "Public Limited Company", "incorporation_date": "1947-11-27", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "tax_number": "GB412 8925 93", "risk_level": "low risk", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": "https://www.tesco.com/", "email": "customer.service@tesco.co.uk", "phone": "03301231688", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": { "currency": "Pound (£)", "total_number_of_shares": "8174378721", "meta_detail": { "Class_Of_Share": "Ordinary" } }, "officers": [ { "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b", "name": "CHRISTOPHER JON TAYLOR", "designation": "Secretary", "role": "secretary", "nationality": null, "is_active": true, "kyc_status": null, "kyc_session_url": null }, { "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c", "name": "MELISSA BETHELL", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": null, "kyc_session_url": null } ], "beneficial_owners": [], "addresses": [ { "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "type": "legal_entity_registry_address", "description": "registered office address" } ], "industries": null, "accounts": { "last_account": "26 February 2025", "next_account": "26 February 2026", "due_by_date": "26 August 2026" }, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } }, "Pending (registry still resolving)": { "summary": "La selezione è rimasta in sospeso dopo il polling — campi sparsi, completamento automatico lato server", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d", "node_id": "feature_kyb_registry", "status": "Not Finished", "registry_status": null, "data_resolved": false, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": null, "company_type": null, "incorporation_date": null, "registered_address": null, "tax_number": null, "risk_level": null, "verification_status": null, "is_from_registry": true, "fetch_status": "pending", "alternative_names": null, "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": {}, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } } } } } }, "400": { "description": "Errore di validazione. I problemi a livello di campo utilizzano l'involucro standard di DRF. Un paese non coperto dai registri restituisce `400` con `code: kyb_registry_country_unsupported`.", "content": { "application/json": { "examples": { "Missing kyb_response_id": { "summary": "`kyb_response_id` è obbligatorio", "value": { "kyb_response_id": [ "This field is required." ] } }, "save_api_request=false rejected": { "summary": "Le selezioni vengono sempre salvate in modo persistente", "value": { "save_api_request": [ "KYB registry select must be saved so billing and retrieval can be tracked." ] } }, "Country not covered": { "summary": "Nessun registro delle imprese è disponibile per il paese", "value": { "detail": "Company registry search is not available for this country. Enter the company details manually to continue.", "code": "kyb_registry_country_unsupported" } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi screening o chiamata al provider.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/passive-liveness/": { "post": { "summary": "Rilevamento passivo della vitalità", "description": "Rileva gli attacchi di presentazione — foto stampate, riproduzioni su schermo, maschere, deepfake — da una singola immagine del volto. Non richiede video, movimento o interazione con l'utente.\n\n**Come funziona.** L'immagine viene analizzata da un modello biometrico; il volto rilevato più grande viene valutato e viene calcolato uno `score` di vitalità (0–100). Lo `status` è `Declined` quando viene attivato un avviso con gravità `error`:\n- `NO_FACE_DETECTED` — il modello di vitalità non ha rilevato alcun volto,\n- `LOW_LIVENESS_SCORE` — punteggio pari o inferiore a `face_liveness_score_decline_threshold` (valore predefinito `30`),\n- `LIVENESS_FACE_ATTACK` — il modello ha rilevato un attacco di presentazione,\n- `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` — il volto corrisponde a una voce presente nella tua blocklist dei volti.\n\n`MULTIPLE_FACES_DETECTED` è un segnale con gravità `warning` (non comporta il rifiuto), mentre `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` sono segnali con gravità `information` che indicano che lo stesso volto è già comparso in un'altra sessione approvata (non comportano mai il rifiuto). `face_quality` e `face_luminance` (0–100, nullable) descrivono la qualità di acquisizione.\n\n**Screening per blocklist e duplicati.** Viene eseguito a **ogni** chiamata — con o senza `save_api_request` — confrontando il volto rilevato con l'indice di Ricerca facciale della tua applicazione. I volti precedenti con lo stesso `vendor_data` vengono esclusi dall'intera ricerca nell'indice — quindi eseguire nuovamente il rilevamento della vitalità per lo stesso utente non attiva `DUPLICATED_FACE`, e anche un volto in blocklist originato da una sessione con lo stesso `vendor_data` del chiamante NON viene segnalato (lo screening `FACE_IN_BLOCKLIST` viene ignorato per i volti con lo stesso `vendor_data`).\n\n**Fatturazione.** Ogni risposta `200` consuma un credito dell'API Passive Liveness (addebitato dal credito del tuo piano o dal saldo di ricarica). Un saldo insufficiente restituisce `403` prima di qualsiasi elaborazione dell'immagine.\n\n**Persistenza della sessione e registrazione del volto (`save_api_request`, predefinito `true`).** Quando è `true`, la chiamata viene salvata come sessione di tipo API (Business Console, `GET /v3/session/{sessionId}/decision/` tramite il `request_id` restituito, webhook `status.updated`), l'immagine di riferimento e il ritaglio del volto vengono memorizzati e il volto rilevato viene **registrato nell'indice di Ricerca facciale** affinché le successive chiamate a Ricerca facciale e i controlli dei duplicati possano trovarlo. Quando è `false`, la chiamata è una tantum: non viene memorizzato nulla e il volto non viene registrato (lo screening per blocklist/duplicati viene comunque eseguito).\n\n**Sandbox.** Le chiavi API di sandbox ignorano tutte le elaborazioni e la fatturazione: dopo la validazione della richiesta (i dati di input non validi restituiscono comunque `400`), l'endpoint restituisce un payload fittizio statico `Approved`, non viene salvata alcuna sessione e non vengono consumati crediti.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`.", "operationId": "post_v3passive-liveness", "x-didit-sdk": { "resource": "passive_liveness", "method": "check", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "Immagine frontale del viso (ad es. un selfie). Estensioni consentite: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Dimensione massima di caricamento: **5 MB** (i file più grandi vengono rifiutati con `400`). Le immagini vengono compresse automaticamente a ~0.5 MB prima dell'elaborazione, pertanto risoluzioni molto elevate non migliorano la precisione. L'immagine deve contenere un unico soggetto — quando sono presenti più volti, viene valutato quello più grande e viene aggiunto un avviso `MULTIPLE_FACES_DETECTED`." }, "face_liveness_score_decline_threshold": { "type": "number", "format": "float", "default": 30, "minimum": 0, "maximum": 100, "description": "Soglia del punteggio di rilevamento della vitalità (0–100). Un punteggio calcolato **pari o inferiore** a questo valore genera un avviso `LOW_LIVENESS_SCORE` e imposta `status` su `Declined`. Predefinito `30`; aumentala per un livello anti-spoofing più restrittivo. I valori non compresi tra 0 e 100 restituiscono `400`.", "example": 30 }, "rotate_image": { "type": "boolean", "default": false, "description": "Quando è `true`, il servizio prova rotazioni di 90 gradi dell'input e utilizza l'orientamento che offre il miglior rilevamento del volto. Utile quando manca l'orientamento EXIF. Aggiunge latenza.", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "Quando è `true` (predefinito), memorizza la chiamata come sessione di tipo API, salva le immagini del volto, emette un webhook `status.updated` e registra il volto rilevato nel tuo indice di Ricerca facciale. Quando è `false`, la chiamata è una tantum: non viene memorizzato nulla e il volto non viene registrato. Lo screening della blocklist e dei duplicati viene eseguito in entrambi i casi.", "example": true }, "vendor_data": { "type": "string", "description": "Identificativo opaco opzionale (il tuo ID utente, email, UUID...) memorizzato nella sessione persistita e restituito. Viene utilizzato anche per escludere le sessioni precedenti con lo stesso `vendor_data` dal controllo dei volti duplicati, in modo che la nuova verifica dello stesso utente non generi `DUPLICATED_FACE`.", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Oggetto JSON opzionale memorizzato con la sessione (quando `save_api_request=true`) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON: viene interpretato come oggetto.", "example": { "flow": "withdrawal" } } } }, "example": { "user_image": "(binary JPEG/PNG selfie)", "face_liveness_score_decline_threshold": 30, "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "withdrawal" } } } } }, "responses": { "200": { "description": "Rilevamento passivo della vitalità completato. `liveness.score` è il livello di affidabilità da 0 a 100 del modello che l'immagine mostri una persona viva; `status` è `Approved` a meno che non sia scattato un avviso con gravità `error`. Un volto falsificato o inserito in blocklist restituisce comunque `200` — esamina `liveness.status` e `liveness.warnings`, non solo il codice HTTP. Quando `save_api_request=true`, `request_id` è l'ID di sessione salvato.", "content": { "application/json": { "examples": { "Approved": { "summary": "Volto dal vivo — nessun avviso", "value": { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "liveness": { "status": "Approved", "method": "PASSIVE", "score": 95.0, "user_image": { "entities": [ { "bbox": [ 661, 728, 1688, 2188 ], "confidence": 0.732973, "age": 26.91, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [], "face_quality": 84.21, "face_luminance": 50.33 }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Declined - presentation attack": { "summary": "Il modello ha segnalato uno spoofing (stampa, replay, maschera…)", "value": { "request_id": "f1c8c9b2-d3e4-4f5a-9b8c-7d6e5f4a3b2c", "liveness": { "status": "Declined", "method": "PASSIVE", "score": 12.5, "user_image": { "entities": [ { "bbox": [ 100, 120, 420, 540 ], "confidence": 0.81, "age": 30.1, "gender": "female", "race": null } ], "best_angle": 0 }, "warnings": [ { "risk": "LOW_LIVENESS_SCORE", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Low liveness score", "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data." }, { "risk": "LIVENESS_FACE_ATTACK", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Liveness Face Attack", "long_description": "The system detected a potential attempt to bypass the liveness check." } ], "face_quality": 72.4, "face_luminance": 48.2 }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Declined - face on blocklist": { "summary": "Volto dal vivo, ma corrisponde a una voce della blocklist", "value": { "request_id": "0b54a1de-22aa-4e0f-9c84-5a2b1f3c4d5e", "liveness": { "status": "Declined", "method": "PASSIVE", "score": 93.75, "user_image": { "entities": [ { "bbox": [ 40, 40, 100, 100 ], "confidence": 0.722082, "age": 27.0, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [ { "risk": "FACE_IN_BLOCKLIST", "feature": "LIVENESS", "additional_data": { "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "blocklisted_session_number": 3242, "api_service": null }, "log_type": "error", "short_description": "Face in blocklist", "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified." } ], "face_quality": null, "face_luminance": null }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo." }, "liveness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "`Declined` quando è scattato almeno un avviso con gravità `error` (nessun volto, punteggio basso, attacco di presentazione o riscontro nella blocklist); `Approved` altrimenti. Le voci `warning`/`information` (volti multipli, duplicati) non determinano mai il rifiuto da sole." }, "method": { "type": "string", "enum": [ "PASSIVE" ], "description": "Sempre `PASSIVE` per questo endpoint." }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Affidabilità del rilevamento della vitalità (0–100, due decimali) che l'immagine ritragga una persona reale anziché uno spoofing. `null` se il modello non ha restituito alcuna affidabilità.", "example": 95.0 }, "user_image": { "type": "object", "description": "Risultati del rilevamento facciale per l'immagine inviata.", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "Riquadro di delimitazione del volto rilevato come coordinate in pixel `[x_min, y_min, x_max, y_max]` nell'immagine elaborata.", "example": [ 661, 728, 1688, 2188 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "Affidabilità del rilevamento facciale (0–1).", "example": 0.732973 }, "age": { "type": "number", "format": "float", "description": "Età stimata dal modello per il volto rilevato, in anni. Solo a scopo informativo: non influisce sulla decisione del rilevamento della vitalità.", "example": 26.91 }, "gender": { "type": "string", "description": "Genere previsto dal modello per il volto rilevato (`male` o `female`). Solo a scopo informativo.", "example": "male" }, "race": { "type": "string", "nullable": true, "description": "Campo riservato — sempre `null` nelle risposte di questo endpoint.", "example": null } } }, "description": "Una voce per ogni volto rilevato. Il volto più grande è quello valutato." }, "best_angle": { "type": "integer", "nullable": true, "description": "Rotazione (gradi) che ha prodotto il miglior rilevamento del volto; diversa da zero solo quando `rotate_image=true` ha corretto l'orientamento.", "example": 0 } } }, "warnings": { "type": "array", "description": "Segnali di rischio. Gravità `error` (comporta il rifiuto): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (punteggio pari o inferiore alla soglia), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Gravità `warning` (revisione, nessun rifiuto): `MULTIPLE_FACES_DETECTED`. Gravità `information` (nessun rifiuto): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` — lo stesso volto è già apparso in un'altra sessione approvata.", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "NO_FACE_DETECTED", "LOW_LIVENESS_SCORE", "LIVENESS_FACE_ATTACK", "MULTIPLE_FACES_DETECTED", "FACE_IN_BLOCKLIST", "POSSIBLE_FACE_IN_BLOCKLIST", "DUPLICATED_FACE", "POSSIBLE_DUPLICATED_FACE" ], "description": "Codice di rischio leggibile dalla macchina." }, "feature": { "type": "string", "enum": [ "LIVENESS" ], "description": "Funzionalità che ha generato l'avviso. Sempre `LIVENESS` su questo endpoint." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "`null` per la maggior parte degli avvisi. Le corrispondenze con la blocklist riportano `{blocklisted_session_id, blocklisted_session_number, api_service}`; i duplicati rilevati riportano `{duplicated_session_id, duplicated_session_number, api_service}` che puntano alla sessione corrispondente." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravità. Gli avvisi `error` portano `status` a `Declined`; le voci `warning` e `information` sono informative e non determinano mai un rifiuto da sole." }, "short_description": { "type": "string", "description": "Riepilogo del rischio su una riga leggibile dall'utente." }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura del rischio." } } } }, "face_quality": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Punteggio di qualità di acquisizione del volto rilevato, normalizzato tra 0 e 100. `null` quando il modello non è riuscito a produrre un valore affidabile.", "example": 84.21 }, "face_luminance": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Luminosità del volto rilevato, normalizzata tra 0 e 100. `null` se non disponibile.", "example": 50.33 } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, o `null`." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco dell'oggetto `metadata` inviato, o `null`." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp ISO 8601 (UTC) di generazione della risposta, ad es. `2026-06-12T01:04:42.763237+00:00`." } } } } } }, "400": { "description": "Errore di validazione. Restituito quando `user_image` è mancante, supera 5 MB, ha un'estensione non supportata, non supera la decodifica dell'immagine lato server o quando un'opzione è fuori intervallo. Gli errori di campo utilizzano l'envelope `{field: [messages]}` di DRF; gli errori di decodifica dell'immagine utilizzano `{\"error\": ...}`.", "content": { "application/json": { "examples": { "Missing image": { "summary": "`user_image` non incluso nei dati del modulo", "value": { "user_image": [ "No file was submitted." ] } }, "Invalid image format": { "summary": "Estensione consentita ma contenuto dell'immagine non decodificabile", "value": { "error": "Invalid user image format.", "code": "invalid_image" } }, "Unsupported file extension": { "summary": "Estensione del file diversa da tiff/jpg/jpeg/png/webp", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "Il caricamento supera il limite di 5 MB", "value": { "user_image": [ "File size should not exceed 5 MB" ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi elaborazione delle immagini.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'face_liveness_score_decline_threshold=30' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.passive_liveness.check(\n user_image=open(\"user_image.jpg\", \"rb\"),\n face_liveness_score_decline_threshold=30.0,\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"withdrawal\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.passiveLiveness.check({\n user_image: await fileFromPath(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"withdrawal\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.PassiveLiveness.Check(ctx, didit.PassiveLivenessCheckParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"withdrawal\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.PassiveLivenessCheckParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.passiveLiveness().check(PassiveLivenessCheckParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .faceLivenessScoreDeclineThreshold(30.0)\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"withdrawal\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "passiveLiveness->check([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'face_liveness_score_decline_threshold' => 30.0,\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'withdrawal'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.passive_liveness.check(\n user_image: Pathname(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"withdrawal\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.PassiveLiveness.CheckAsync(new PassiveLivenessCheckParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n FaceLivenessScoreDeclineThreshold = 30.0,\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"withdrawal\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/database-validation/": { "post": { "summary": "Validazione su database (indipendente)", "operationId": "post_v3database-validation", "x-didit-sdk": { "resource": "database_validation", "method": "validate", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Valida i dati di identità di una persona confrontandoli con fonti governative e registri ufficiali — CPF in Brasile, RENAPER in Argentina, registri DNI in Spagna e Perù, INE in Messico e 100+ altri servizi in 60+ paesi.\n\n**Selezione dei servizi.** Ogni paese espone uno o più servizi di catalogo identificati da un `service_id` (ad es. `bra_cpf`, `arg_renaper`, `pan_cedula_sib`). Fissa i servizi desiderati con l'array `services` — se lo ometti, viene eseguito esattamente **un** servizio predefinito (il servizio attivo da più tempo per il paese). L'invio di `services` converte inoltre la risposta nel formato esteso con `services_used` e `match_score`. Scopri i servizi, i relativi campi obbligatori e i prezzi tramite `GET /v1/organization/database-validation-countries/` (un endpoint di catalogo non documentato in questa specifica) o tramite l'editor di workflow della Business Console. Alcuni servizi sono contrassegnati con `requires_consent=true` nel catalogo e richiedono `consent=true`; altri richiedono l'onboarding per la tua organizzazione prima di poter essere chiamati.\n\n**Campi di input.** `identification_number` è un campo universale che mappa automaticamente il campo corretto specifico per paese (vedi la sua descrizione). Le regole di formato del paese vengono applicate prima che venga chiamato qualsiasi provider (ad es. il CPF BRA deve essere composto esattamente da 11 cifre) e gli errori di formato non vengono mai fatturati. I servizi biometrici richiedono il caricamento di un `selfie` (solo multipart); RENAPER in Argentina richiede inoltre `gender`.\n\n**Risultati.** Ciascun servizio restituisce una mappa `validation` campo per campo e un `outcome_code` neutro rispetto al fornitore (`MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, `DOCUMENT_NOT_FOUND`, `INVALID_DOCUMENT_FORMAT`, `INVALID_INPUT`, `MINOR_BLOCKED`, `DECEASED`, `BIOMETRIC_NO_MATCH`, `BIOMETRIC_IMAGE_UNUSABLE`, `INCONCLUSIVE`, `DOCUMENT_SUPERSEDED`, `REGISTRY_UNAVAILABLE`, `REGISTRY_ERROR`). Nota le differenze: `NO_MATCH` indica una mancata corrispondenza definitiva, `INCONCLUSIVE` significa che il registro non ha potuto confermare né in un senso né nell'altro (revisione, non rifiuto), e `BIOMETRIC_IMAGE_UNUSABLE` è un problema tecnico relativo al selfie (da ripetere), a differenza del definitivo `BIOMETRIC_NO_MATCH`. Il `match_type` complessivo aggrega i risultati tra i servizi (qualsiasi corrispondenza completa → `full_match`, altrimenti qualsiasi parziale → `partial_match`, altrimenti `no_match`) e `no_match_action`/`partial_match_action` lo traducono nello `status` finale. `validation_type` è derivato: `two_by_two` quando due o più servizi distinti hanno prodotto un riscontro completo (sul numero di identificazione, su nome completo + data di nascita insieme, o sull'indirizzo senza contraddizioni), altrimenti `one_by_one`.\n\n**Persistenza.** Il valore predefinito di `save_api_request` è **true**: il risultato viene memorizzato come sessione (`request_id` funziona con `GET /v3/session/{sessionId}/decision/`), compare nella console e attiva un webhook `status.updated`. Controlla inoltre il formato di `validations` — oggetti per ciascun servizio quando la richiesta viene salvata, una mappa aggregata `{field: match}` quando non lo è.\n\n**Fatturazione.** Per servizio: a ogni servizio che restituisce un risultato fatturabile viene addebitato il rispettivo prezzo di catalogo. I servizi non riusciti o ignorati non vengono fatturati e le richieste rifiutate con `400` non costano nulla. Il controllo preventivo del saldo copre la somma dei prezzi dei servizi selezionati (`403` se insufficiente).\n\n**Errori.** Quando nessun servizio selezionato restituisce un risultato utilizzabile, l'API restituisce `400` con `validation_errors` se ogni tentativo senza risposta ha rifiutato esplicitamente l'input (`provider_rejected_input`, `retryable: false`). Correggi l'input prima di riprovare. Altrimenti restituisce `502` con `validation_errors` (`empty_provider_response`, `retryable: true`), inclusi casi misti di rifiuto dell'input e tentativi di fallback non disponibili; non viene addebitato nulla (viene comunque registrata una sessione con stato `Not Finished` quando `save_api_request=true`). Quando falliscono solo alcuni servizi, la risposta `200` include i relativi errori in `database_validation.errors`.\n\n**Sandbox.** Le chiavi delle applicazioni sandbox ignorano le chiamate ai registri e la fatturazione, restituendo una risposta statica `full_match` — il payload sandbox include sempre `services_used` e `match_score: 100` a prescindere da come sia stato inviato `services`, quindi non verificare il gating del formato esteso in produzione o la frazione 0.0–1.0 di `match_score` rispetto alle risposte sandbox.\n\nInvia la richiesta come `application/json`, oppure come `multipart/form-data` quando carichi un `selfie`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "issuing_state" ], "properties": { "issuing_state": { "type": "string", "description": "Codice paese ISO 3166-1 **alpha-3** del registro rispetto al quale convalidare (ad es. `BRA`, `ESP`, `COL`). Determina quali servizi sono disponibili. I codici non supportati restituiscono `400` con l'elenco completo delle opzioni valide.", "example": "BRA" }, "services": { "type": "array", "items": { "type": "string" }, "description": "`service_id` di catalogo da eseguire per questo paese (ad es. `[\"bra_cpf\"]`). Accetta anche una singola stringa o una stringa separata da virgole/codificata in JSON. **Se omesso o vuoto, viene eseguito esattamente un servizio predefinito** — il servizio live da più tempo attivo per il paese; i servizi più recenti, biometrici e a consumo (pay-as-you-go) devono essere indicati esplicitamente. L'invio di `services` passa la risposta al formato esteso (aggiunge `services_used` e `match_score`). Ogni id deve esistere ed essere attivo per lo `issuing_state`; i servizi che richiedono l'onboarding restituiscono `400` finché non vengono attivati per la tua organizzazione. Scopri i servizi disponibili per paese tramite `GET /v1/organization/database-validation-countries/` (un endpoint di catalogo non documentato in questa specifica) o nell'editor dei workflow della Business Console.", "example": [ "bra_cpf" ] }, "validation_type": { "type": "string", "deprecated": true, "description": "DEPRECATO. Accettato per compatibilità con le versioni precedenti ma ignorato: il `validation_type` della risposta è ora derivato da quanti servizi hanno avuto una corrispondenza completa. Usa `services` per fissare servizi specifici." }, "consent": { "type": "boolean", "default": false, "description": "Imposta su `true` quando l'utente finale ha acconsentito esplicitamente ai servizi di validazione selezionati. Obbligatorio per i servizi contrassegnati da `requires_consent=true` nel catalogo: senza di esso tali servizi restituiscono `400` con `services_requiring_consent`." }, "identification_number": { "type": "string", "description": "Numero di identificazione universale — mappato automaticamente al campo specifico del paese corretto, quindi puoi usarlo al posto di `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 cifre), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 cifre), ECU→personal_number (Cédula, 10 cifre), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 caratteri), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 cifre), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Non sovrascrive mai un campo specifico del paese fornito esplicitamente." }, "first_name": { "type": "string", "description": "Il nome proprio della persona fisica. Richiesto da alcuni servizi o paesi.", "example": "John" }, "last_name": { "type": "string", "description": "Il cognome della persona fisica. Richiesto da alcuni servizi o paesi.", "example": "Doe" }, "middle_name": { "type": "string", "description": "Secondo nome, utilizzato da alcuni servizi nazionali (AUS, NZL, …)." }, "full_name": { "type": "string", "description": "Nome completo: alcuni servizi lo accettano al posto di nome/cognome (ad es. i servizi CHN, che confrontano il nome nel sistema di scrittura nativo)." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data di nascita, `YYYY-MM-DD`. Richiesta da molti servizi.", "example": "1980-01-01" }, "personal_number": { "type": "string", "description": "Identificativo personale univoco rilasciato dallo stato. Utilizzato da: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Valuta l'uso di `identification_number` in alternativa." }, "tax_number": { "type": "string", "description": "Identificativo fiscale. Usato da: BRA (CPF, 11 cifre). Considera invece `identification_number`." }, "document_number": { "type": "string", "description": "Numero del documento. Utilizzato da: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considera invece `identification_number`." }, "document_type": { "type": "string", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "description": "Tipo di documento in fase di convalida: `P` passaporto, `DL` patente di guida, `ID` carta d'identità, `RP` permesso di soggiorno (oltre a `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Richiesto da alcuni servizi (es. ESP)." }, "expiration_date": { "type": "string", "format": "date", "description": "Data di scadenza del documento, `YYYY-MM-DD`. Obbligatoria per la validazione ESP (Spagna).", "example": "2030-01-15" }, "date_of_issue": { "type": "string", "format": "date", "description": "Data di emissione del documento, `YYYY-MM-DD` (fecha de expedición). Obbligatoria per la validazione della cédula COL (Colombia).", "example": "2015-06-20" }, "nationality": { "type": "string", "description": "Nazionalità in formato ISO 3166-1 alpha-3. Richiesta da alcuni servizi." }, "gender": { "type": "string", "enum": [ "M", "F", "X" ], "description": "Genere: `M`, `F` o `X` (altro/sconosciuto). Richiesto per la validazione RENAPER dell'Argentina (`arg_renaper`)." }, "address": { "description": "Indirizzo di residenza. È preferibile l'oggetto strutturato `{\"street_1\":\"123 Main St\",\"street_2\":\"Apt 4B\",\"city\":\"Springfield\",\"region\":\"IL\",\"postal_code\":\"62701\",\"country\":\"US\"}`; viene comunque accettata una stringa completa su riga singola. Richiesto dai servizi di verifica dell'indirizzo; quando un servizio definisce i requisiti per l'indirizzo, le parti mancanti restituiscono `400` con `address_fields_required_by`.", "oneOf": [ { "type": "object", "properties": { "street_1": { "type": "string" }, "street_2": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, { "type": "string", "description": "Indirizzo completo su riga singola (legacy)." } ] }, "address_element_1": { "type": "string", "description": "Indirizzo stradale inclusi numero civico e tipo di via. Se omesso, viene ricavato da `address`." }, "address_element_2": { "type": "string", "description": "Appartamento, interno, edificio, piano o riga di indirizzo aggiuntiva. Inviare solo se si dispone esplicitamente di questo dato." }, "address_element_3": { "type": "string", "description": "Città, sobborgo, distretto, località o quartiere. Se omesso, viene ricavato da `address`." }, "address_element_4": { "type": "string", "description": "Stato, provincia, regione o città. Se omesso, viene ricavato da `address`." }, "address_element_5": { "type": "string", "description": "Codice postale o CAP. `postal_code` è accettato come alias." }, "postal_code": { "type": "string", "description": "Codice postale per i servizi basati sull'indirizzo (alias di `address_element_5`)." }, "driver_license_number": { "type": "string", "description": "Numero della patente di guida per i servizi governativi di verifica dei documenti (AUS, NZL, IND)." }, "driver_license_card_number": { "type": "string", "description": "Numero della tessera fisica della patente di guida, dove richiesto separatamente dal numero di patente (AUS)." }, "driver_license_state": { "type": "string", "description": "Stato o territorio di rilascio della patente di guida (AUS)." }, "driver_license_version": { "type": "string", "description": "Codice versione della patente di guida (NZL)." }, "passport_number": { "type": "string", "description": "Numero di passaporto per i servizi governativi di verifica del passaporto (AUS, NZL, IND, CHN)." }, "passport_expiration_date": { "type": "string", "format": "date", "description": "Data di scadenza del passaporto, `YYYY-MM-DD`, per i servizi di verifica del passaporto." }, "passport_file_number": { "type": "string", "description": "Numero di pratica del passaporto (IND)." }, "passport_issue_country": { "type": "string", "description": "Paese di emissione del passaporto (ISO 3166-1 alpha-3) per i servizi di verifica del passaporto." }, "medicare_card_number": { "type": "string", "description": "Numero della carta Medicare (AUS)." }, "immi_card_number": { "type": "string", "description": "Numero dell'ImmiCard australiana." }, "immi_card_expiry_date": { "type": "string", "format": "date", "description": "Data di scadenza dell'ImmiCard australiana." }, "citizenship_certificate_number": { "type": "string", "description": "Numero del certificato di cittadinanza (AUS)." }, "birth_registration_number": { "type": "string", "description": "Numero di registrazione del certificato di nascita (AUS)." }, "birth_registration_date": { "type": "string", "format": "date", "description": "Data di registrazione del certificato di nascita (AUS)." }, "birth_registration_state": { "type": "string", "description": "Stato di registrazione del certificato di nascita (AUS)." }, "marriage_certificate_number": { "type": "string", "description": "Numero del certificato di matrimonio (AUS)." }, "change_of_name_certificate_number": { "type": "string", "description": "Numero del certificato di cambio nome (AUS)." }, "first_partner_name": { "type": "string", "description": "Nome del coniuge su un certificato di matrimonio (AUS)." }, "last_partner_name": { "type": "string", "description": "Cognome del partner su un certificato di matrimonio (AUS)." }, "voter_id": { "type": "string", "description": "Numero di registrazione elettorale (IND EPIC, IRL)." }, "epic_card": { "type": "string", "description": "Numero della tessera elettorale EPIC indiana." }, "pan": { "type": "string", "description": "PAN indiano (Permanent Account Number)." }, "national_id": { "type": "string", "description": "Numero di identificazione nazionale (CHN, MYS, KEN, KHM, NGA, ZAF, …)." }, "cic": { "type": "string", "description": "Código de Identificación de Credencial (CIC) dell'INE/IFE messicano, 9 cifre. Utilizzato dal servizio di validità delle credenziali MEX INE (`mex_ine_vigencia`)." }, "identificador_ciudadano": { "type": "string", "description": "Identificador del Ciudadano dell'INE messicano (9 cifre). Utilizzato con `cic` per i modelli INE moderni (E/F/G/H) in `mex_ine_vigencia`." }, "ocr": { "type": "string", "description": "Numero OCR dell'INE messicano (13 cifre, retro del documento). Utilizzato con `cic` per il Modello D in `mex_ine_vigencia`." }, "voter_number": { "type": "string", "description": "Clave de Elector dell'INE messicano (18 caratteri). Utilizzata con `emission_number` per i modelli IFE legacy (A/B/C) in `mex_ine_vigencia`." }, "emission_number": { "type": "string", "description": "Número de Emisión dell'INE messicano. Utilizzato con `voter_number` per i modelli IFE legacy (A/B/C) in `mex_ine_vigencia`." }, "bvn": { "type": "string", "description": "Numero di verifica bancaria nigeriano." }, "bank_card_number": { "type": "string", "description": "Numero di carta bancaria (verifica della carta bancaria CHN)." }, "company_registration_number": { "type": "string", "description": "Numero di registrazione aziendale rilasciato dal registro delle imprese: il CNPJ in Brasile (es. `11222333000181`), il numero di registrazione in Sudafrica (es. `1936/007721/06`). Obbligatorio per i servizi del registro delle imprese e degli amministratori aziendali (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`)." }, "company_name": { "type": "string", "description": "Ragione sociale registrata, confrontata con la voce del registro. Opzionale per `zaf_company_registry`." }, "initials": { "type": "string", "description": "Le iniziali della persona come stampate sul documento. Obbligatorie per `zaf_drivers_license`; accettate da `zaf_bank_account_holder`." }, "licence_number": { "type": "string", "description": "Numero della patente di guida come stampato sulla tessera, per `zaf_drivers_license`. Se omesso, viene utilizzato `document_number`." }, "refugee_file_number": { "type": "string", "description": "Numero di pratica per rifugiati rilasciato dal Department of Home Affairs del Sudafrica. Richiesto da `zaf_refugee`." }, "bank_name": { "type": "string", "description": "Nome della banca presso cui è detenuto il conto. Obbligatorio per `zaf_bank_account_holder`." }, "bank_account_number": { "type": "string", "description": "Numero di conto bancario. Obbligatorio per `zaf_bank_account_holder`; accettato da `zaf_fraud_prevention`." }, "account_type": { "type": "string", "description": "Tipo di conto bancario per `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` o `notKnown`, senza distinzione tra maiuscole e minuscole. Qualsiasi altro valore restituisce `400`. Omettilo se non conosci il tipo: la verifica incrociata del tipo di conto verrà quindi segnalata come non confermata." }, "phone_number": { "type": "string", "description": "Numero di cellulare di contatto, per i servizi che verificano la contattabilità (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`)." }, "right_thumb": { "type": "string", "description": "Impronta digitale del pollice destro codificata in Base64 per `zaf_dha_fingerprint_match`, insieme a `left_thumb` o da sola." }, "left_thumb": { "type": "string", "description": "Impronta digitale del pollice sinistro codificata in Base64 per `zaf_dha_fingerprint_match`, insieme a `right_thumb` o da sola." }, "score_level": { "type": "integer", "description": "Livello minimo del punteggio biometrico per `zaf_criminal_face_screening`. Il valore predefinito è `3`." }, "max_matches": { "type": "integer", "description": "Numero massimo di corrispondenze candidate restituite da `zaf_criminal_face_screening`. Il valore predefinito è `1`." }, "vehicle_register_number": { "type": "string", "description": "Numero di registrazione del veicolo. Obbligatorio, insieme a `vehicle_licence_plate` e `vin`, per `zaf_vehicle_ownership`." }, "vehicle_licence_plate": { "type": "string", "description": "Numero di targa del veicolo. Obbligatorio, insieme a `vehicle_register_number` e `vin`, per `zaf_vehicle_ownership`." }, "vin": { "type": "string", "description": "Numero di identificazione del veicolo (VIN o numero di telaio). Obbligatorio, insieme a `vehicle_register_number` e `vehicle_licence_plate`, per `zaf_vehicle_ownership`." }, "ssn": { "type": "string", "description": "Social Security Number (USA)." }, "phone": { "type": "string", "description": "Numero di telefono per i servizi di verifica telefonica." }, "landline": { "type": "string", "description": "Numero di rete fissa per i servizi di verifica telefonica." }, "email": { "type": "string", "format": "email", "description": "Indirizzo email per i servizi di verifica dell'identità." }, "country_of_residence": { "type": "string", "description": "Paese di residenza ISO 3166-1 alpha-2. Utilizzato dai servizi globali di arricchimento dell'identità (ad es. `glb_identity_enrichment`) per concentrare la ricerca.", "example": "US" }, "partial_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "NO_ACTION", "description": "Effetto di un `partial_match` su `database_validation.status`. Il valore predefinito è `NO_ACTION` (lo stato rimane `Approved`, con un avviso)." }, "no_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "Effetto di un `no_match` su `database_validation.status`. Il valore predefinito è `DECLINE`." }, "save_api_request": { "type": "boolean", "default": true, "description": "Salva la validazione come sessione (visibilità nella console, endpoint della decisione, webhook `status.updated`). Modifica anche la struttura della risposta di `validations`: oggetti per servizio quando è `true` (predefinito), una mappa di campi unificata quando è `false`." }, "vendor_data": { "type": "string", "description": "Il tuo identificatore per l'utente validato; restituito nella risposta e memorizzato con la sessione." }, "metadata": { "type": "object", "nullable": true, "description": "JSON a struttura libera memorizzato con la richiesta e restituito nella risposta." } } }, "example": { "issuing_state": "BRA", "services": [ "bra_cpf" ], "identification_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01", "vendor_data": "user-1234" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "issuing_state" ], "properties": { "issuing_state": { "type": "string", "description": "Codice paese ISO 3166-1 **alpha-3** del registro rispetto al quale convalidare (ad es. `BRA`, `ESP`, `COL`). Determina quali servizi sono disponibili. I codici non supportati restituiscono `400` con l'elenco completo delle opzioni valide.", "example": "BRA" }, "services": { "type": "array", "items": { "type": "string" }, "description": "`service_id` di catalogo da eseguire per questo paese (ad es. `[\"bra_cpf\"]`). Accetta anche una singola stringa o una stringa separata da virgole/codificata in JSON. **Se omesso o vuoto, viene eseguito esattamente un servizio predefinito** — il servizio live da più tempo attivo per il paese; i servizi più recenti, biometrici e a consumo (pay-as-you-go) devono essere indicati esplicitamente. L'invio di `services` passa la risposta al formato esteso (aggiunge `services_used` e `match_score`). Ogni id deve esistere ed essere attivo per lo `issuing_state`; i servizi che richiedono l'onboarding restituiscono `400` finché non vengono attivati per la tua organizzazione. Scopri i servizi disponibili per paese tramite `GET /v1/organization/database-validation-countries/` (un endpoint di catalogo non documentato in questa specifica) o nell'editor dei workflow della Business Console.", "example": [ "bra_cpf" ] }, "validation_type": { "type": "string", "deprecated": true, "description": "DEPRECATO. Accettato per compatibilità con le versioni precedenti ma ignorato: il `validation_type` della risposta è ora derivato da quanti servizi hanno avuto una corrispondenza completa. Usa `services` per fissare servizi specifici." }, "consent": { "type": "boolean", "default": false, "description": "Imposta su `true` quando l'utente finale ha acconsentito esplicitamente ai servizi di validazione selezionati. Obbligatorio per i servizi contrassegnati da `requires_consent=true` nel catalogo: senza di esso tali servizi restituiscono `400` con `services_requiring_consent`." }, "identification_number": { "type": "string", "description": "Numero di identificazione universale — mappato automaticamente al campo specifico del paese corretto, quindi puoi usarlo al posto di `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 cifre), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 cifre), ECU→personal_number (Cédula, 10 cifre), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 caratteri), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 cifre), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Non sovrascrive mai un campo specifico del paese fornito esplicitamente." }, "first_name": { "type": "string", "description": "Il nome proprio della persona fisica. Richiesto da alcuni servizi o paesi.", "example": "John" }, "last_name": { "type": "string", "description": "Il cognome della persona fisica. Richiesto da alcuni servizi o paesi.", "example": "Doe" }, "middle_name": { "type": "string", "description": "Secondo nome, utilizzato da alcuni servizi nazionali (AUS, NZL, …)." }, "full_name": { "type": "string", "description": "Nome completo: alcuni servizi lo accettano al posto di nome/cognome (ad es. i servizi CHN, che confrontano il nome nel sistema di scrittura nativo)." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data di nascita, `YYYY-MM-DD`. Richiesta da molti servizi.", "example": "1980-01-01" }, "personal_number": { "type": "string", "description": "Identificativo personale univoco rilasciato dallo stato. Utilizzato da: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Valuta l'uso di `identification_number` in alternativa." }, "tax_number": { "type": "string", "description": "Identificativo fiscale. Usato da: BRA (CPF, 11 cifre). Considera invece `identification_number`." }, "document_number": { "type": "string", "description": "Numero del documento. Utilizzato da: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considera invece `identification_number`." }, "document_type": { "type": "string", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "description": "Tipo di documento in fase di convalida: `P` passaporto, `DL` patente di guida, `ID` carta d'identità, `RP` permesso di soggiorno (oltre a `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Richiesto da alcuni servizi (es. ESP)." }, "expiration_date": { "type": "string", "format": "date", "description": "Data di scadenza del documento, `YYYY-MM-DD`. Obbligatoria per la validazione ESP (Spagna).", "example": "2030-01-15" }, "date_of_issue": { "type": "string", "format": "date", "description": "Data di emissione del documento, `YYYY-MM-DD` (fecha de expedición). Obbligatoria per la validazione della cédula COL (Colombia).", "example": "2015-06-20" }, "nationality": { "type": "string", "description": "Nazionalità in formato ISO 3166-1 alpha-3. Richiesta da alcuni servizi." }, "gender": { "type": "string", "enum": [ "M", "F", "X" ], "description": "Genere: `M`, `F` o `X` (altro/sconosciuto). Richiesto per la validazione RENAPER dell'Argentina (`arg_renaper`)." }, "address": { "description": "Indirizzo di residenza. È preferibile l'oggetto strutturato `{\"street_1\":\"123 Main St\",\"street_2\":\"Apt 4B\",\"city\":\"Springfield\",\"region\":\"IL\",\"postal_code\":\"62701\",\"country\":\"US\"}`; viene comunque accettata una stringa completa su riga singola. Richiesto dai servizi di verifica dell'indirizzo; quando un servizio definisce i requisiti per l'indirizzo, le parti mancanti restituiscono `400` con `address_fields_required_by`.", "oneOf": [ { "type": "object", "properties": { "street_1": { "type": "string" }, "street_2": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, { "type": "string", "description": "Indirizzo completo su riga singola (legacy)." } ] }, "address_element_1": { "type": "string", "description": "Indirizzo stradale inclusi numero civico e tipo di via. Se omesso, viene ricavato da `address`." }, "address_element_2": { "type": "string", "description": "Appartamento, interno, edificio, piano o riga di indirizzo aggiuntiva. Inviare solo se si dispone esplicitamente di questo dato." }, "address_element_3": { "type": "string", "description": "Città, sobborgo, distretto, località o quartiere. Se omesso, viene ricavato da `address`." }, "address_element_4": { "type": "string", "description": "Stato, provincia, regione o città. Se omesso, viene ricavato da `address`." }, "address_element_5": { "type": "string", "description": "Codice postale o CAP. `postal_code` è accettato come alias." }, "postal_code": { "type": "string", "description": "Codice postale per i servizi basati sull'indirizzo (alias di `address_element_5`)." }, "driver_license_number": { "type": "string", "description": "Numero della patente di guida per i servizi governativi di verifica dei documenti (AUS, NZL, IND)." }, "driver_license_card_number": { "type": "string", "description": "Numero della tessera fisica della patente di guida, dove richiesto separatamente dal numero di patente (AUS)." }, "driver_license_state": { "type": "string", "description": "Stato o territorio di rilascio della patente di guida (AUS)." }, "driver_license_version": { "type": "string", "description": "Codice versione della patente di guida (NZL)." }, "passport_number": { "type": "string", "description": "Numero di passaporto per i servizi governativi di verifica del passaporto (AUS, NZL, IND, CHN)." }, "passport_expiration_date": { "type": "string", "format": "date", "description": "Data di scadenza del passaporto, `YYYY-MM-DD`, per i servizi di verifica del passaporto." }, "passport_file_number": { "type": "string", "description": "Numero di pratica del passaporto (IND)." }, "passport_issue_country": { "type": "string", "description": "Paese di emissione del passaporto (ISO 3166-1 alpha-3) per i servizi di verifica del passaporto." }, "medicare_card_number": { "type": "string", "description": "Numero della carta Medicare (AUS)." }, "immi_card_number": { "type": "string", "description": "Numero dell'ImmiCard australiana." }, "immi_card_expiry_date": { "type": "string", "format": "date", "description": "Data di scadenza dell'ImmiCard australiana." }, "citizenship_certificate_number": { "type": "string", "description": "Numero del certificato di cittadinanza (AUS)." }, "birth_registration_number": { "type": "string", "description": "Numero di registrazione del certificato di nascita (AUS)." }, "birth_registration_date": { "type": "string", "format": "date", "description": "Data di registrazione del certificato di nascita (AUS)." }, "birth_registration_state": { "type": "string", "description": "Stato di registrazione del certificato di nascita (AUS)." }, "marriage_certificate_number": { "type": "string", "description": "Numero del certificato di matrimonio (AUS)." }, "change_of_name_certificate_number": { "type": "string", "description": "Numero del certificato di cambio nome (AUS)." }, "first_partner_name": { "type": "string", "description": "Nome del coniuge su un certificato di matrimonio (AUS)." }, "last_partner_name": { "type": "string", "description": "Cognome del partner su un certificato di matrimonio (AUS)." }, "voter_id": { "type": "string", "description": "Numero di registrazione elettorale (IND EPIC, IRL)." }, "epic_card": { "type": "string", "description": "Numero della tessera elettorale EPIC indiana." }, "pan": { "type": "string", "description": "PAN indiano (Permanent Account Number)." }, "national_id": { "type": "string", "description": "Numero di identificazione nazionale (CHN, MYS, KEN, KHM, NGA, ZAF, …)." }, "cic": { "type": "string", "description": "Código de Identificación de Credencial (CIC) dell'INE/IFE messicano, 9 cifre. Utilizzato dal servizio di validità delle credenziali MEX INE (`mex_ine_vigencia`)." }, "identificador_ciudadano": { "type": "string", "description": "Identificador del Ciudadano dell'INE messicano (9 cifre). Utilizzato con `cic` per i modelli INE moderni (E/F/G/H) in `mex_ine_vigencia`." }, "ocr": { "type": "string", "description": "Numero OCR dell'INE messicano (13 cifre, retro del documento). Utilizzato con `cic` per il Modello D in `mex_ine_vigencia`." }, "voter_number": { "type": "string", "description": "Clave de Elector dell'INE messicano (18 caratteri). Utilizzata con `emission_number` per i modelli IFE legacy (A/B/C) in `mex_ine_vigencia`." }, "emission_number": { "type": "string", "description": "Número de Emisión dell'INE messicano. Utilizzato con `voter_number` per i modelli IFE legacy (A/B/C) in `mex_ine_vigencia`." }, "bvn": { "type": "string", "description": "Numero di verifica bancaria nigeriano." }, "bank_card_number": { "type": "string", "description": "Numero di carta bancaria (verifica della carta bancaria CHN)." }, "company_registration_number": { "type": "string", "description": "Numero di registrazione aziendale rilasciato dal registro delle imprese: il CNPJ in Brasile (es. `11222333000181`), il numero di registrazione in Sudafrica (es. `1936/007721/06`). Obbligatorio per i servizi del registro delle imprese e degli amministratori aziendali (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`)." }, "company_name": { "type": "string", "description": "Ragione sociale registrata, confrontata con la voce del registro. Opzionale per `zaf_company_registry`." }, "initials": { "type": "string", "description": "Le iniziali della persona come stampate sul documento. Obbligatorie per `zaf_drivers_license`; accettate da `zaf_bank_account_holder`." }, "licence_number": { "type": "string", "description": "Numero della patente di guida come stampato sulla tessera, per `zaf_drivers_license`. Se omesso, viene utilizzato `document_number`." }, "refugee_file_number": { "type": "string", "description": "Numero di pratica per rifugiati rilasciato dal Department of Home Affairs del Sudafrica. Richiesto da `zaf_refugee`." }, "bank_name": { "type": "string", "description": "Nome della banca presso cui è detenuto il conto. Obbligatorio per `zaf_bank_account_holder`." }, "bank_account_number": { "type": "string", "description": "Numero di conto bancario. Obbligatorio per `zaf_bank_account_holder`; accettato da `zaf_fraud_prevention`." }, "account_type": { "type": "string", "description": "Tipo di conto bancario per `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` o `notKnown`, senza distinzione tra maiuscole e minuscole. Qualsiasi altro valore restituisce `400`. Omettilo se non conosci il tipo: la verifica incrociata del tipo di conto verrà quindi segnalata come non confermata." }, "phone_number": { "type": "string", "description": "Numero di cellulare di contatto, per i servizi che verificano la contattabilità (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`)." }, "right_thumb": { "type": "string", "description": "Impronta digitale del pollice destro codificata in Base64 per `zaf_dha_fingerprint_match`, insieme a `left_thumb` o da sola." }, "left_thumb": { "type": "string", "description": "Impronta digitale del pollice sinistro codificata in Base64 per `zaf_dha_fingerprint_match`, insieme a `right_thumb` o da sola." }, "score_level": { "type": "integer", "description": "Livello minimo del punteggio biometrico per `zaf_criminal_face_screening`. Il valore predefinito è `3`." }, "max_matches": { "type": "integer", "description": "Numero massimo di corrispondenze candidate restituite da `zaf_criminal_face_screening`. Il valore predefinito è `1`." }, "vehicle_register_number": { "type": "string", "description": "Numero di registrazione del veicolo. Obbligatorio, insieme a `vehicle_licence_plate` e `vin`, per `zaf_vehicle_ownership`." }, "vehicle_licence_plate": { "type": "string", "description": "Numero di targa del veicolo. Obbligatorio, insieme a `vehicle_register_number` e `vin`, per `zaf_vehicle_ownership`." }, "vin": { "type": "string", "description": "Numero di identificazione del veicolo (VIN o numero di telaio). Obbligatorio, insieme a `vehicle_register_number` e `vehicle_licence_plate`, per `zaf_vehicle_ownership`." }, "ssn": { "type": "string", "description": "Social Security Number (USA)." }, "phone": { "type": "string", "description": "Numero di telefono per i servizi di verifica telefonica." }, "landline": { "type": "string", "description": "Numero di rete fissa per i servizi di verifica telefonica." }, "email": { "type": "string", "format": "email", "description": "Indirizzo email per i servizi di verifica dell'identità." }, "country_of_residence": { "type": "string", "description": "Paese di residenza ISO 3166-1 alpha-2. Utilizzato dai servizi globali di arricchimento dell'identità (ad es. `glb_identity_enrichment`) per concentrare la ricerca.", "example": "US" }, "partial_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "NO_ACTION", "description": "Effetto di un `partial_match` su `database_validation.status`. Il valore predefinito è `NO_ACTION` (lo stato rimane `Approved`, con un avviso)." }, "no_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "Effetto di un `no_match` su `database_validation.status`. Il valore predefinito è `DECLINE`." }, "save_api_request": { "type": "boolean", "default": true, "description": "Salva la validazione come sessione (visibilità nella console, endpoint della decisione, webhook `status.updated`). Modifica anche la struttura della risposta di `validations`: oggetti per servizio quando è `true` (predefinito), una mappa di campi unificata quando è `false`." }, "vendor_data": { "type": "string", "description": "Il tuo identificatore per l'utente validato; restituito nella risposta e memorizzato con la sessione." }, "metadata": { "type": "object", "nullable": true, "description": "JSON a struttura libera memorizzato con la richiesta e restituito nella risposta." }, "selfie": { "type": "string", "format": "binary", "description": "Immagine del selfie (`jpg`, `jpeg`, `png`, `webp`; max 2 MB — le immagini vengono compresse a ~1.5 MB prima del caricamento nel registro) per i servizi di validazione biometrica, ad es. Argentina RENAPER (`arg_renaper`) e Panama SIB (`pan_cedula_sib`, `pan_cedula_sib_plus`). Obbligatorio ogni volta che un servizio selezionato lo include come campo obbligatorio. Disponibile solo tramite `multipart/form-data`." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/database-validation/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"issuing_state\": \"BRA\",\n \"services\": [\"bra_cpf\"],\n \"identification_number\": \"12345678900\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1980-01-01\",\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.database_validation.validate(\n issuing_state=\"BRA\",\n services=[\"bra_cpf\"],\n identification_number=\"12345678900\",\n first_name=\"John\",\n last_name=\"Doe\",\n date_of_birth=\"1980-01-01\",\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.databaseValidation.validate({\n issuing_state: \"BRA\",\n services: [\"bra_cpf\"],\n identification_number: \"12345678900\",\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1980-01-01\",\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{\n\tIssuingState: \"BRA\",\n\tServices: didit.Some([]string{\"bra_cpf\"}),\n\tIdentificationNumber: didit.String(\"12345678900\"),\n\tFirstName: didit.String(\"John\"),\n\tLastName: didit.String(\"Doe\"),\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.DatabaseValidationValidateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder()\n .issuingState(\"BRA\")\n .services(List.of(\"bra_cpf\"))\n .identificationNumber(\"12345678900\")\n .firstName(\"John\")\n .lastName(\"Doe\")\n .dateOfBirth(LocalDate.parse(\"1980-01-01\"))\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "databaseValidation->validate([\n 'issuing_state' => 'BRA',\n 'services' => ['bra_cpf'],\n 'identification_number' => '12345678900',\n 'first_name' => 'John',\n 'last_name' => 'Doe',\n 'date_of_birth' => '1980-01-01',\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.database_validation.validate(\n issuing_state: \"BRA\",\n services: [\"bra_cpf\"],\n identification_number: \"12345678900\",\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1980-01-01\",\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams\n{\n IssuingState = \"BRA\",\n Services = new string[] { \"bra_cpf\" },\n IdentificationNumber = \"12345678900\",\n FirstName = \"John\",\n LastName = \"Doe\",\n DateOfBirth = \"1980-01-01\",\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Validazione completata — almeno un servizio selezionato ha restituito un risultato utilizzabile. Ispeziona `database_validation.match_type` per l'esito aggregato, `validations` per i confronti dei campi per servizio e i relativi `outcome_code`, ed `errors` (quando presente) per i servizi che hanno avuto esito negativo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione salvata quando `save_api_request=true` (utilizzabile con `GET /v3/session/{sessionId}/decision/`); altrimenti un UUID di correlazione temporaneo." }, "database_validation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "`Declined` quando il `match_type` complessivo attiva un'azione `DECLINE` (il valore predefinito di `no_match_action` è `DECLINE`, mentre quello di `partial_match_action` è `NO_ACTION`); `In Review` quando nessun servizio ha prodotto un confronto utilizzabile, ad esempio quando l'unico servizio selezionato ha restituito `REGISTRY_UNAVAILABLE` o `INCONCLUSIVE`; `Approved` altrimenti. Una richiesta che ha selezionato più servizi può risultare `Approved` sulla corrispondenza di un servizio mentre un altro non era disponibile, quindi controlla anche `errors` e gli `outcome_code` di ciascun servizio." }, "issuing_state": { "type": "string", "description": "Eco del paese ISO 3166-1 alpha-3 rispetto al quale è stata eseguita la validazione.", "example": "BRA" }, "validation_type": { "type": "string", "enum": [ "one_by_one", "two_by_two" ], "description": "Derivato dai risultati: `two_by_two` quando ≥2 servizi distinti hanno prodotto una corrispondenza completa (sul numero identificativo, su nome completo + data di nascita insieme, o sull'indirizzo senza contraddizioni); altrimenti `one_by_one`. (Il campo della richiesta con lo stesso nome è deprecato e ignorato.)" }, "screened_data": { "type": "object", "description": "Eco dei campi di input inviati ai servizi selezionati (date normalizzate in `YYYY-MM-DD`; un `selfie`, quando inviato, viene restituito come URL pre-firmato; `consent_obtained: true` viene aggiunto quando è stato fornito il consenso)." }, "match_type": { "type": "string", "nullable": true, "enum": [ "full_match", "partial_match", "no_match" ], "description": "Risultato complessivo aggregato tra i servizi con confronti a livello di campo: qualsiasi `full_match` → `full_match`; altrimenti qualsiasi `partial_match` → `partial_match`; altrimenti `no_match`. I servizi basati solo sull'esito, come lo screening criminale biometrico, possono restituire `null`; esamina ciascun elemento in `validations` per il relativo `outcome_code`." }, "validations": { "description": "La struttura dipende da `save_api_request`. **`true` (predefinito):** un array di oggetti per servizio (`service_id`, `service_name`, `validation`, `outcome_code`, `outcome_detail`, `source_data`). **`false`:** un singolo oggetto piatto che unisce i risultati a livello di campo di tutti i servizi (`{\"full_name\": \"full_match\", ...}`).", "oneOf": [ { "type": "array", "items": { "type": "object", "description": "Risultato della validazione per singolo servizio (restituito quando `save_api_request=true`, l'impostazione predefinita).", "properties": { "service_id": { "type": "string", "description": "Id di catalogo del servizio che ha prodotto questo risultato (ad es. `bra_cpf`).", "example": "bra_cpf" }, "service_name": { "type": "string", "description": "Nome del servizio nel catalogo, leggibile dall'utente.", "example": "Brazil - CPF status check" }, "validation": { "type": "object", "description": "Confronto campo per campo tra i dati inseriti e il record del registro. Le chiavi sono nomi di campo canonici (`full_name`, `date_of_birth`, `identification_number`, `address`, …); i valori sono `full_match`, `partial_match` o `no_match`.", "additionalProperties": { "type": "string", "enum": [ "full_match", "partial_match", "no_match" ] } }, "outcome_code": { "type": "string", "enum": [ "MATCH", "PARTIAL_MATCH", "NO_MATCH", "DOCUMENT_NOT_FOUND", "INVALID_DOCUMENT_FORMAT", "INVALID_INPUT", "MINOR_BLOCKED", "DECEASED", "BIOMETRIC_NO_MATCH", "BIOMETRIC_IMAGE_UNUSABLE", "INCONCLUSIVE", "DOCUMENT_SUPERSEDED", "REGISTRY_UNAVAILABLE", "REGISTRY_ERROR" ], "description": "Esito indipendente dal vendor della consultazione del registro. `MATCH`/`PARTIAL_MATCH`/`NO_MATCH` descrivono il confronto; `DOCUMENT_NOT_FOUND` indica che l'identificativo non è presente nel registro; `INCONCLUSIVE` indica che il registro non ha potuto confermare in nessun senso (inoltrato a revisione — NON è una mancata corrispondenza); `BIOMETRIC_NO_MATCH` è una mancata corrispondenza facciale definitiva, mentre `BIOMETRIC_IMAGE_UNUSABLE` è un problema tecnico dell'immagine (scatta nuovamente il selfie); `DECEASED`/`MINOR_BLOCKED` sono esiti legati alle policy del registro; `DOCUMENT_SUPERSEDED` indica che l'identità corrispondeva ma l'edizione del documento presentato non è quella registrata (è stata emessa un'edizione più recente); `INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` indicano che il registro stesso ha rifiutato i dati inviati; `REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` indicano errori a monte." }, "outcome_detail": { "type": "string", "nullable": true, "description": "Dettaglio dello stato a monte non elaborato a supporto del codice di esito (ad es. un codice di stato HTTP o del registro)." }, "source_data": { "type": "object", "nullable": true, "description": "Vista ripulita e normalizzata del record di registro che utilizza nomi di campo canonici (`identification_number`, `first_name`, `last_name`, `date_of_birth`, più flag specifici del registro). I campi immagine, se presenti, vengono restituiti come URL pre-firmati." } } } }, { "type": "object", "additionalProperties": { "type": "string", "enum": [ "full_match", "partial_match", "no_match" ] }, "description": "Risultati uniti a livello di campo (formato stateless `save_api_request=false`)." } ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Funzionalità che ha generato l'avviso." }, "risk": { "type": "string", "description": "Identificatore di rischio leggibile dalla macchina." }, "additional_data": { "type": "object", "nullable": true, "description": "Contesto aggiuntivo per l'avviso, se disponibile." }, "log_type": { "type": "string", "description": "`warning`, `information` o `error` — come il rischio ha influito sull'esito." }, "short_description": { "type": "string", "description": "Riepilogo su una riga leggibile dall'uomo." }, "long_description": { "type": "string", "description": "Spiegazione completa e leggibile." } } }, "description": "`DATABASE_VALIDATION_NO_MATCH` o `DATABASE_VALIDATION_PARTIAL_MATCH` quando applicabile; vuoto in caso di corrispondenza completa." }, "errors": { "type": "array", "description": "Presente solo quando alcuni (ma non tutti) i servizi selezionati non sono riusciti. Ogni voce include `service_id`, `code`, `message` e `retryable`. Un servizio segnalato qui è assente da `validations` e `services_used`, e non viene fatturato. Questo array è l'unico punto in cui compare, quindi esaminalo anche quando `status` è `Approved`.", "items": { "type": "object", "properties": { "service_id": { "type": "string" }, "code": { "type": "string", "example": "empty_provider_response" }, "message": { "type": "string" }, "retryable": { "type": "boolean", "description": "`true` quando il servizio non ha prodotto alcuna risposta e un nuovo tentativo successivo può avere successo; `false` quando la fonte ha rifiutato i dati inviati e l'input deve essere prima corretto.", "example": true } } } }, "services_used": { "type": "array", "items": { "type": "string" }, "description": "Id di catalogo dei servizi che hanno restituito un risultato fatturabile. **Presente solo quando la richiesta ha inviato esplicitamente `services`.**" }, "match_score": { "type": "number", "description": "Frazione (0.0–1.0) dei servizi tentati che hanno prodotto una corrispondenza completa (sul numero identificativo, su nome completo + data di nascita insieme, o sull'indirizzo senza contraddizioni). **Presente solo quando la richiesta ha inviato esplicitamente `services`.**" } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato." }, "metadata": { "type": "object", "nullable": true, "description": "Eco del `metadata` inviato." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Full match (Approved)": { "summary": "Valore predefinito save_api_request=true — oggetti `validations` per servizio", "value": { "request_id": "7f9a1c0e-1f2b-4f6e-9d3a-2b1c0e7f9a1c", "database_validation": { "status": "Approved", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "full_match", "validations": [ { "validation": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "outcome_code": "MATCH", "outcome_detail": "200", "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "source_data": { "identification_number": "12345678900", "first_name": "JOHN", "last_name": "DOE", "date_of_birth": "1980-01-01", "lgpd_minor": false, "minor_under_16": false, "minor_under_18": false } } ], "warnings": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-11T10:30:00.000000+00:00" } }, "Explicit services (extended shape)": { "summary": "Richiesta inviata con `services` — la risposta aggiunge `services_used` e `match_score`", "value": { "request_id": "b3e7c1a2-9d4f-4f0b-8a6c-5e2d1f0a9b3e", "database_validation": { "status": "Approved", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "full_match", "validations": [ { "validation": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "outcome_code": "MATCH", "outcome_detail": "200", "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "source_data": { "identification_number": "12345678900", "first_name": "JOHN", "last_name": "DOE", "date_of_birth": "1980-01-01", "lgpd_minor": false, "minor_under_16": false, "minor_under_18": false } } ], "warnings": [], "services_used": [ "bra_cpf" ], "match_score": 1.0 }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-11T10:30:00.000000+00:00" } }, "No match (Declined)": { "summary": "Il record del registro delle imprese non corrisponde — predefinito `no_match_action=DECLINE`", "value": { "request_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789", "database_validation": { "status": "Declined", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "no_match", "validations": [ { "validation": { "full_name": "no_match", "date_of_birth": "no_match", "identification_number": "no_match" }, "outcome_code": "NO_MATCH", "outcome_detail": "200", "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "source_data": { "identification_number": "00987654321", "first_name": "TOTALLY", "last_name": "DIFFERENT NAME", "date_of_birth": "1999-01-01", "lgpd_minor": false, "minor_under_16": false, "minor_under_18": false } } ], "warnings": [ { "feature": "DATABASE_VALIDATION", "risk": "DATABASE_VALIDATION_NO_MATCH", "additional_data": null, "log_type": "error", "short_description": "Database validation no match", "long_description": "The system identified a no match in the database validation, requiring further investigation." } ] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-11T10:31:00.000000+00:00" } }, "Stateless (save_api_request=false)": { "summary": "`validations` si riduce a una mappa di campi unificata; non viene memorizzato nulla", "value": { "request_id": "c4d5e6f7-8901-2345-6789-abcdef012345", "database_validation": { "status": "Approved", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "full_match", "validations": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-11T10:32:00.000000+00:00" } } } } } }, "400": { "description": "Errore di validazione - non viene fatturato nulla. Gli errori sui campi in fase di preflight si verificano prima di qualsiasi chiamata esterna. Se ogni tentativo senza risposta rifiuta esplicitamente l'input, la risposta include invece `validation_errors` con `code: provider_rejected_input` e `retryable: false`; correggi l'input prima di riprovare. I problemi a livello di campo utilizzano la busta standard di DRF; i problemi del catalogo restituiscono un array `services` (più `requires_onboarding` o `services_requiring_consent` se pertinenti); gli errori per campi mancanti includono `fields_required_by` che mappa ogni campo mancante ai servizi che lo richiedono; i servizi che necessitano di almeno un identificatore aggiuntivo (ad es. `usa_states_credit_bureau`, che non può verificare un nome da solo) restituiscono `any_field_required_by` mappando ciascun servizio ai campi di cui almeno uno deve essere presente; i problemi di formato controllati per servizio restituiscono `invalid_fields_by_service`.", "content": { "application/json": { "examples": { "Invalid issuing_state": { "summary": "Paese non supportato — il messaggio elenca tutti i codici alpha-3 validi", "value": { "error": [ "Invalid issuing state. Valid options are: ARE, ARG, AUS, AUT, BEL, BGD, BOL, BRA, CAN, CHE, CHL, CHN, CIV, COL, CRI, CZE, DEU, DNK, DOM, ECU, ESP, FIN, FRA, GBR, GHA, GLB, GRC, GTM, HKG, HND, IDN, IND, IRL, ITA, KEN, KHM, MAR, MEX, MYS, NGA, NLD, NOR, NZL, OMN, PAN, PER, PHL, POL, PRT, PRY, QAT, SGP, SLV, SVK, SWE, THA, UGA, URY, USA, VEN, ZAF, ZMB, ZWE" ] } }, "Missing required fields": { "summary": "Unione dei campi obbligatori nei servizi selezionati, con l'indicazione del campo universale", "value": { "error": [ "Missing required fields: tax_number (or use 'identification_number' which maps to 'tax_number' for BRA)" ], "fields_required_by": { "tax_number": [ "bra_cpf" ] } } }, "Unknown service id": { "summary": "`services` contiene un id non presente nel catalogo", "value": { "services": [ "Unknown service_id(s): ['bogus_service']" ] } }, "Service not live for country": { "summary": "`services` fa riferimento a un servizio di un altro paese (o a una voce fittizia)", "value": { "services": [ "Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration']" ] } }, "Service requires onboarding": { "summary": "Il servizio esiste ma non è ancora attivato per la tua organizzazione", "value": { "services": [ "Services require onboarding before they can be enabled for AUS: ['aus_australia_driver_licence']. Contact Didit support to activate them." ], "requires_onboarding": [ "aus_australia_driver_licence" ] } }, "Consent missing": { "summary": "Un servizio selezionato è contrassegnato con requires_consent=true e `consent` non era `true`", "value": { "consent": [ "Explicit end-user consent is required for these database validation services: ['chn_national_id']. Send `consent=true`." ], "services_requiring_consent": [ "chn_national_id" ] } }, "Country format rule violation": { "summary": "L'identificatore non rispetta la regola di formato del paese (lunghezza/cifre/regex)", "value": { "tax_number": [ "Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). Must be exactly 11 characters long (got 10)." ] } }, "Service-specific format violation": { "summary": "Un campo non soddisfa i requisiti di formato propri del servizio selezionato", "value": { "error": [ "One or more fields do not match the format required by the selected service." ], "invalid_fields_by_service": { "chn_national_id": [ "national_id_format" ] } } }, "Input refused by every attempt": { "summary": "Correggi l'input prima di riprovare", "value": { "error": "The source refused to run this query with the supplied input.", "validation_errors": [ { "service_id": "bra_cpf", "code": "provider_rejected_input", "message": "The source refused to run this query with the supplied input.", "retryable": false } ] } } }, "schema": { "type": "object", "additionalProperties": true, "properties": { "error": { "description": "Spiegazione a livello di richiesta o errori preliminari sui campi.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "validation_errors": { "type": "array", "description": "Presente quando ogni tentativo senza risposta ha rifiutato l'input dopo il preflight.", "items": { "type": "object", "properties": { "service_id": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean", "description": "Indica se riprovare più tardi può risolvere questo errore del servizio. False indica che è necessario prima correggere l'input fornito." } } } } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi screening o chiamata al provider.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "502": { "description": "Nessun servizio selezionato ha restituito un risultato utilizzabile. Ispeziona ogni voce di validation_errors prima di effettuare un nuovo tentativo; l'errore HTTP 502 da solo non prova un errore temporaneo. Un valore empty_provider_response con retryable: true indica risultati non disponibili o non spiegati, compreso un fornitore primario rifiutato seguito da un'alternativa non disponibile. Le voci legacy provider_invalid_input e provider_validation_error richiedono invece dati di input corretti e possono omettere retryable. Nulla viene fatturato. Quando save_api_request=true, il tentativo fallito viene registrato come sessione con stato Not Finished. Gli errori parziali restituiscono 200 con database_validation.errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "service_id": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean", "description": "Indica se riprovare più tardi può risolvere questo errore del servizio. False indica che è necessario prima correggere l'input fornito." } } } } } }, "examples": { "Provider returned no result": { "summary": "Tutti i servizi selezionati hanno avuto esito negativo", "value": { "error": "Database validation could not be performed. The external validation service did not return a result. Please try again later.", "validation_errors": [ { "service_id": "bra_cpf", "code": "empty_provider_response", "message": "The provider did not return a database validation result.", "retryable": true } ] } } } } } } } } }, "/v3/phone/send/": { "post": { "summary": "Invia codice telefonico", "description": "Invia un codice monouso (OTP) a un numero di telefono tramite WhatsApp, SMS o un altro canale supportato, quindi verificalo con [`POST /v3/phone/check/`](/it/standalone-apis/phone-check).\n\n**Come si associano invio e verifica.** Lo stato della verifica è associato alla tua applicazione e al `phone_number` in formato E.164 — la chiamata di verifica non richiede `request_id`. Ogni nuovo invio crea una verifica in sospeso valida per **5 minuti**: chiama l'endpoint di verifica con lo stesso numero e con il codice ricevuto dall'utente prima della scadenza dell'intervallo temporale. Chiamando nuovamente l'endpoint di invio per lo stesso numero mentre una verifica è in sospeso, viene reinviato un codice per quella stessa verifica (`status: \"Retry\"`, stesso `request_id`). In questo modo può essere associato al massimo un nuovo tentativo (due invii totali); un ulteriore invio avvia una nuova verifica con un nuovo `request_id`. L'intervallo di 5 minuti viene calcolato dal primo invio e non viene esteso dai nuovi tentativi.\n\n**Canali di consegna.** `options.preferred_channel` seleziona il canale (predefinito: `whatsapp`; sono supportati anche `sms`, `telegram`, `voice`, `rcs`, `viber` e `zalo`). Quando il canale preferito non è disponibile per il paese o il numero di destinazione, la consegna passa automaticamente a SMS — l'invio restituisce comunque `Success`, e il canale effettivamente utilizzato viene riportato nella risposta della verifica (`phone.verification_method` e gli eventi del `lifecycle`).\n\n**Personalizzazione del brand.** I codici SMS includono il nome del mittente SMS della tua applicazione, configurato nella Business Console, senza costi aggiuntivi. Passa `options.sms_sender_name` per inviare un codice con un nome diverso, oppure `options.use_white_label_customization: true` per ripiegare sul tuo nome pubblico white label quando non è impostato alcun nome mittente. I codici WhatsApp utilizzano un messaggio fisso; collega il tuo numero WhatsApp Business nella Business Console per inviarli con il nome e il numero della tua azienda, con addebito della sola tariffa Didit.\n\n**Stati dell'invio.** `Success` — OTP inviato per una nuova verifica; `Retry` — OTP reinviato per la verifica in sospeso; `Blocked` — il livello antifrode ha rifiutato l'invio (vedi `reason`, ad es. `repeated_attempts`, `suspicious`, `spam`). Un invio `Blocked` finalizza immediatamente la verifica come `Declined` con un avviso di rischio elevato, quindi una successiva verifica restituirà `Expired or Not Found`.\n\n**Fatturazione.** Il prezzo dipende dal paese di destinazione e dal canale che consegna effettivamente il messaggio — consulta i [Prezzi della Verifica telefonica](/it/getting-started/phone-verification-pricing). Solo gli invii con esito `Blocked` sono garantiti come gratuiti: qualsiasi altro tentativo di invio non fatturato viene addebitato al momento della finalizzazione o della scadenza della verifica, anche se la consegna non è mai stata confermata o il fornitore del servizio di consegna ha segnalato il messaggio come non recapitabile. I controlli di verifica sono sempre gratuiti. Come misura contro gli abusi, la verifica telefonica rimane disabilitata fino alla prima ricarica della tua organizzazione (`403`).\n\n**Persistenza della sessione.** Ogni nuova verifica viene memorizzata come sessione di tipo API: `request_id` è un vero ID sessione che puoi passare a `GET /v3/session/{sessionId}/decision/`, la verifica compare nella Business Console e vengono inviati i webhook `status.updated` man mano che avanza.\n\n**Sandbox.** Le chiavi API di sandbox ignorano la consegna e la fatturazione: dopo la validazione della richiesta (un input non valido restituisce comunque `400`), l'endpoint restituisce un payload statico `Success` con un `request_id` casuale; nessun messaggio viene inviato e nulla viene memorizzato. Utilizza il codice `123456` per la verifica in sandbox.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — questa API non restituisce mai `401`.\n\n**Limiti di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE, oltre a un limite di protezione dagli abusi di 4 tentativi di invio per numero di telefono all'ora; il superamento di uno di questi limiti restituisce `429`.", "operationId": "post_v3phone_send", "x-didit-sdk": { "resource": "phone", "method": "send_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/phone/send/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"+14155552671\",\n \"options\": {\n \"code_size\": 6,\n \"preferred_channel\": \"whatsapp\",\n \"locale\": \"en-US\"\n },\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.phone.send_code(\n phone_number=\"+14155552671\",\n options={\n \"locale\": \"en-US\",\n \"preferred_channel\": \"whatsapp\",\n },\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.phone.sendCode({\n phone_number: \"+14155552671\",\n options: {\n locale: \"en-US\",\n preferred_channel: \"whatsapp\",\n },\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.SendCode(ctx, didit.PhoneSendCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tOptions: didit.Some(didit.PhoneSendCodeParamsOptions{\n\t\tLocale: didit.String(\"en-US\"),\n\t\tPreferredChannel: didit.Some(didit.PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.PhoneSendCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.phone().sendCode(PhoneSendCodeParams.builder()\n .phoneNumber(\"+14155552671\")\n .options(PhoneSendCodeParams.Options.builder()\n .locale(\"en-US\")\n .preferredChannel(PhoneSendCodeParams.Options.PreferredChannel.of(\"whatsapp\"))\n .build())\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "phone->sendCode([\n 'phone_number' => '+14155552671',\n 'options' => [\n 'locale' => 'en-US',\n 'preferred_channel' => 'whatsapp',\n ],\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.phone.send_code(\n phone_number: \"+14155552671\",\n options: {\n locale: \"en-US\",\n preferred_channel: \"whatsapp\",\n },\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Phone.SendCodeAsync(new PhoneSendCodeParams\n{\n PhoneNumber = \"+14155552671\",\n Options = new PhoneSendCodeParamsOptions\n {\n Locale = \"en-US\",\n PreferredChannel = new PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\"),\n },\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "maxLength": 20, "description": "Numero di telefono del destinatario in formato E.164 — con `+` iniziale e prefisso internazionale (es. `+14155552671`). I numeri vengono validati e normalizzati in E.164; i numeri non analizzabili o non validi restituiscono `400` con un errore nel campo `phone_number`.", "example": "+14155552671" }, "options": { "type": "object", "description": "Opzioni di consegna dell'OTP. Tutti i campi sono facoltativi.", "properties": { "code_size": { "type": "integer", "minimum": 4, "maximum": 8, "default": 6, "description": "Numero di cifre nell'OTP." }, "locale": { "type": "string", "maxLength": 5, "pattern": "^[a-z]{2,3}(-[A-Z]{2,3})?$", "description": "Codice lingua BCP-47 utilizzato per localizzare il messaggio di verifica (ad es. `en-US`, `fr`, `es`). I formati non validi restituiscono `400`.", "example": "en-US" }, "preferred_channel": { "type": "string", "enum": [ "whatsapp", "sms", "telegram", "voice", "rcs", "viber", "zalo" ], "default": "whatsapp", "description": "Canale di consegna preferito. Se il canale non è disponibile per il paese o il numero di destinazione, il messaggio passa automaticamente all'SMS — l'invio segnala comunque `Success`." }, "use_white_label_customization": { "type": "boolean", "default": false, "description": "Quando è `true`, l'invio è white label: se la tua applicazione non ha un nome mittente SMS, l'SMS riporterà invece il tuo nome pubblico white label (\"123456 è il tuo codice di verifica per Acme Bank\"). Il tuo nome mittente SMS, se impostato, viene utilizzato indipendentemente da questo flag. Si applica ai messaggi SMS, compreso il fallback via SMS da un altro canale; i codici WhatsApp vengono inviati con un messaggio predefinito e non sono personalizzati con il brand. Il valore predefinito è `false`." }, "sms_sender_name": { "type": "string", "nullable": true, "maxLength": 30, "example": "Acme Bank", "description": "Il nome riportato nell'SMS di questo codice (\"123456 è il tuo codice di verifica per Acme Bank\"), al posto del nome mittente SMS della tua applicazione. Gratuito. Da 1 a 30 caratteri: solo lettere, cifre, spazi e ' & - !, non solo cifre, con spazi singoli tra le parole; qualsiasi altro valore restituisce `400` e nessun codice viene inviato. Se omesso, `null` o vuoto, viene utilizzato il nome mittente SMS della tua applicazione. Ogni applicazione può iniziare a utilizzare fino a due nuovi nomi al giorno (UTC); oltre tale limite, il codice viene inviato con il nome della tua applicazione. Si applica ai messaggi SMS, incluso un fallback via SMS da un altro canale; i codici WhatsApp non sono personalizzati con il marchio.", "pattern": "^$|^(?![\\d ]+$)[\\p{L}\\p{N}'&!-]+( [\\p{L}\\p{N}'&!-]+)*$" } } }, "signals": { "type": "object", "description": "Segnali opzionali di dispositivo e rete relativi all'utente finale, inoltrati al livello antifrode per migliorare il rilevamento del traffico abusivo o automatizzato. Tutti i campi sono opzionali.", "properties": { "ip": { "type": "string", "description": "Indirizzo IP del dispositivo dell'utente finale. IPv4 o IPv6.", "example": "192.0.2.1" }, "device_id": { "type": "string", "maxLength": 255, "description": "Identificativo univoco del dispositivo dell'utente finale. Android: `ANDROID_ID`; iOS: `identifierForVendor`.", "example": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2" }, "device_platform": { "type": "string", "enum": [ "android", "ios", "ipados", "tvos", "web" ], "description": "Piattaforma del dispositivo dell'utente finale." }, "device_model": { "type": "string", "maxLength": 255, "description": "Modello del dispositivo dell'utente finale.", "example": "iPhone17,2" }, "os_version": { "type": "string", "maxLength": 64, "description": "Versione del sistema operativo del dispositivo dell'utente finale.", "example": "18.0.1" }, "app_version": { "type": "string", "maxLength": 64, "description": "Versione della tua applicazione.", "example": "1.2.34" }, "user_agent": { "type": "string", "maxLength": 512, "description": "User agent del browser o dell'app dell'utente finale.", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1" } } }, "vendor_data": { "type": "string", "description": "Identificatore opzionale controllato dal chiamante (il tuo ID utente interno, un'email, un UUID, ecc.) memorizzato nella sessione e restituito nella risposta di invio, nella risposta di verifica della corrispondenza, nei webhook e nella Business Console. Usalo per correlare il `request_id` di Didit con il record del tuo utente." }, "metadata": { "type": "object", "nullable": true, "description": "Oggetto JSON a struttura libera opzionale memorizzato nella sessione e restituito nella risposta di invio, nella risposta del controllo di corrispondenza, nei webhook e nella Business Console." } }, "required": [ "phone_number" ] }, "examples": { "WhatsApp (default)": { "summary": "OTP a 6 cifre via WhatsApp, con fallback automatico a SMS", "value": { "phone_number": "+14155552671", "options": { "preferred_channel": "whatsapp", "locale": "en-US" }, "vendor_data": "user-1234" } }, "SMS with custom code length": { "summary": "Forza la consegna via SMS con un codice a 4 cifre", "value": { "phone_number": "+34699999999", "options": { "preferred_channel": "sms", "code_size": 4, "locale": "es" } } }, "With fraud signals": { "summary": "Inoltra i segnali del dispositivo per rafforzare lo screening antifrode", "value": { "phone_number": "+14155552671", "signals": { "ip": "192.0.2.1", "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2", "device_platform": "ios", "device_model": "iPhone17,2", "os_version": "18.0.1", "app_version": "1.2.34" }, "vendor_data": "user-1234" } } } } } }, "responses": { "200": { "description": "Invio confermato. Ispeziona `status`: `Success` e `Retry` indicano che un codice è in arrivo; `Blocked` indica che il livello antifrode ha rifiutato e la verifica è già finalizzata come `Declined`. `request_id` è l'ID di sessione persistente (stesso ID in caso di `Retry`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerificationSendResponse" }, "examples": { "Success": { "summary": "OTP inviato per una nuova verifica", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Success", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Retry": { "summary": "Secondo invio per lo stesso numero entro la finestra di 5 minuti — stesso request_id", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Retry", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Blocked": { "summary": "Rifiuto antifrode — verifica finalizzata come Rifiutata, nessun costo addebitato", "value": { "request_id": "0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3", "status": "Blocked", "reason": "repeated_attempts", "vendor_data": "user-1234", "metadata": null } } } } } }, "400": { "description": "Errore di validazione. Un input malformato restituisce l'envelope degli errori di campo di DRF (un array di messaggi per ciascun campo interessato, nidificato sotto `options` per gli errori delle opzioni). Un numero valido a livello sintattico ma rifiutato al momento dell'invio (irraggiungibile o con un tipo di linea non idoneo come un codice breve) restituisce invece un envelope `{\"detail\": ...}`.", "content": { "application/json": { "examples": { "Invalid phone number (field error)": { "summary": "Il numero non è valido in formato E.164", "value": { "phone_number": [ "Invalid phone number provided." ] } }, "Missing phone number": { "summary": "`phone_number` non incluso nel corpo", "value": { "phone_number": [ "This field is required." ] } }, "Invalid options": { "summary": "`code_size` fuori intervallo, `locale` non valido, `preferred_channel` sconosciuto", "value": { "options": { "code_size": [ "Ensure this value is less than or equal to 8." ], "locale": [ "Ensure this field has no more than 5 characters." ], "preferred_channel": [ "\"carrier_pigeon\" is not a valid choice." ] } } }, "Number rejected at send time": { "summary": "Formato E.164 valido, ma il numero non può ricevere un OTP", "value": { "detail": "Invalid phone number provided." } }, "Ineligible line type": { "summary": "Il tipo di linea non può ricevere OTP (es. short code)", "value": { "detail": "Invalid phone line type provided." } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante (`{\"detail\": ...}`); una chiave errata, revocata o scaduta restituisce `401`. Restituito inoltre prima di qualsiasi invio quando l'organizzazione non ha mai effettuato una ricarica (meccanismo anti-abuso) o quando il suo saldo non è sufficiente a coprire il prezzo di invio della destinazione (`{\"error\": ...}`).", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Top-up required": { "summary": "La verifica telefonica rimane disabilitata fino alla prima ricarica dell'organizzazione", "value": { "detail": "To protect against abuse, phone verification is disabled until your first top-up." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire il prezzo di invio", "value": { "error": "You don't have enough credits to perform this request." } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). Inoltre, a monte si applica un limite anti-abuso di 4 tentativi di verifica per numero di telefono all'ora. La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. Nota: le intestazioni `X-RateLimit-*`/`Retry-After` accompagnano solo l'errore 429 relativo al limite di scrittura di 300/min; l'errore 429 relativo al limite per numero di telefono non include intestazioni del limite di frequenza.", "content": { "application/json": { "examples": { "Per-number cap": { "summary": "Più di 4 tentativi di verifica per lo stesso numero nell'ultima ora", "value": { "detail": "Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number." } }, "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "502": { "description": "Il provider di verifica telefonica è temporaneamente non disponibile: una risposta 5xx, timeout o errore di connessione persistito dopo i nuovi tentativi integrati. È possibile riprovare in sicurezza; non viene addebitato nulla e non viene consumato alcun tentativo.", "content": { "application/json": { "examples": { "Provider outage": { "summary": "Il provider non ha risposto alla richiesta di invio", "value": { "detail": "Phone verification is temporarily unavailable. Please try again shortly.", "code": "phone_provider_unavailable" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Errore imprevisto durante la creazione della verifica non riconducibile a un'interruzione nota del fornitore. È sicuro effettuare un nuovo tentativo.", "content": { "application/json": { "examples": { "Provider error": { "summary": "Impossibile avviare la consegna dell'OTP", "value": { "detail": "Error creating phone verification" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/phone/check/": { "post": { "summary": "Verifica codice telefonico", "description": "Verifica l'OTP recapitato da [`POST /v3/phone/send/`](/it/standalone-apis/phone-send) e ottieni il risultato finale della verifica oltre a informazioni sul numero di telefono: nome dell'operatore e tipo di linea, flag per numero virtuale (VoIP) e usa e getta, e l'utilizzo duplicato del numero tra le tue sessioni.\n\n**Come il controllo individua la verifica.** La corrispondenza avviene in base alla tua applicazione e al `phone_number` in formato E.164 — `request_id` non è un input. Viene controllata la verifica in sospeso più recente creata negli ultimi **5 minuti**. Se non ne esiste alcuna (mai inviata, già completata o creata più di 5 minuti prima), l'endpoint restituisce `200` con `status: \"Expired or Not Found\"`.\n\n**Budget di tentativi.** Ogni verifica consente **3 tentativi di inserimento del codice**. I primi due codici errati restituiscono `status: \"Failed\"` con i tentativi rimanenti e `phone: null`; il terzo codice errato finalizza la verifica come `Declined` con un avviso `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` e restituisce il report telefonico completo.\n\n**Esiti.** `Approved` — codice corretto e nessun rischio di rifiuto. `Declined` — terminale: il codice era corretto ma è stato rilevato un rischio di rifiuto (un'azione `DECLINE` indicata sotto, un numero presente in blocklist o ad alto rischio) oppure il budget di tentativi è esaurito. `Failed` — codice errato, tentativi rimanenti. `Expired or Not Found` — nulla da controllare. In caso di `Approved`/`Declined`, `request_id` corrisponde al `request_id` dell'invio (l'ID sessione) e `phone` contiene il report completo (`carrier`, `is_virtual`, `is_disposable`, `warnings`, `lifecycle`, `matches`); in caso di `Failed` ed `Expired or Not Found`, `request_id` è un UUID casuale generato una tantum.\n\n**Azioni di rischio.** `duplicated_phone_number_action`, `disposable_number_action` e `voip_number_action` determinano cosa succede quando viene rilevato il rischio corrispondente con un codice corretto: `DECLINE` imposta lo stato finale su `Declined`; `NO_ACTION` (predefinito) registra il rischio in `phone.warnings` senza modificare lo stato.\n\n**Fatturazione.** I controlli sono gratuiti — la consegna viene fatturata al momento dell'invio (vedi [Prezzi di Verifica telefonica](/it/getting-started/phone-verification-pricing)).\n\n**Persistenza della sessione.** Un controllo finalizzato aggiorna la sessione creata dall'invio (visibile nella Business Console, interrogabile tramite `GET /v3/session/{sessionId}/decision/`) e attiva un webhook `status.updated`.\n\n**Sandbox.** Le chiavi API di sandbox ignorano qualsiasi elaborazione: qualunque codice ben formato (4–8 cifre, `123456` compreso) restituisce un payload statico `Approved` con un oggetto `phone` semplificato e piatto (`status`, `phone_number`, `country_code`, `carrier_name`, `line_type`, `flags`); un input non valido restituisce comunque `400`. Nessun dato viene salvato.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — questa API non restituisce mai `401`.\n\n**Limiti di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API, oltre al limite anti-abuso a monte di 4 tentativi per numero all'ora; il superamento di uno dei due restituisce `429`.\n\n**Presenza social.** Imposta `enable_social` su `true` per aggiungere un blocco `phone_social`: le piattaforme online su cui questo numero è registrato, con conteggi per categoria ed eventuali dettagli del profilo disponibili. `profiles_registered: 0` significa che le piattaforme sono state verificate e il numero non è stato trovato su nessuna di esse - una risposta valida e fatturabile. Il blocco è assente quando il modulo aggiuntivo non è stato richiesto o non è stato possibile completare il controllo; in questo caso non viene fatturato. La fatturazione aggiunge un'unità `phone_social` per richiesta al prezzo proprio di questo endpoint.", "operationId": "post_v3phone_check", "x-didit-sdk": { "resource": "phone", "method": "check_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/phone/check/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"+14155552671\",\n \"code\": \"123456\",\n \"voip_number_action\": \"DECLINE\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.phone.check_code(\n phone_number=\"+14155552671\",\n code=\"123456\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.phone.checkCode({\n phone_number: \"+14155552671\",\n code: \"123456\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.PhoneCheckCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.phone().checkCode(PhoneCheckCodeParams.builder()\n .phoneNumber(\"+14155552671\")\n .code(\"123456\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "phone->checkCode([\n 'phone_number' => '+14155552671',\n 'code' => '123456',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.phone.check_code(\n phone_number: \"+14155552671\",\n code: \"123456\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Phone.CheckCodeAsync(new PhoneCheckCodeParams\n{\n PhoneNumber = \"+14155552671\",\n Code = \"123456\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "maxLength": 20, "description": "Lo stesso numero di telefono utilizzato nella chiamata corrispondente [`POST /v3/phone/send/`](/it/standalone-apis/phone-send), in formato E.164. Questo è ciò che collega la verifica all'invio.", "example": "+14155552671" }, "code": { "type": "string", "minLength": 4, "maxLength": 8, "pattern": "^[0-9]{4,8}$", "description": "L'OTP ricevuto dall'utente finale. Deve essere composto da 4–8 cifre numeriche; qualsiasi altro valore restituisce `400` senza consumare un tentativo. Un codice ben formato ma errato restituisce `200` con `status: \"Failed\"` e consuma uno dei 3 tentativi.", "example": "123456" }, "duplicated_phone_number_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Cosa fare quando lo stesso numero è già stato utilizzato da un utente diverso (diverso `vendor_data`) della tua applicazione. `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il rischio in `phone.warnings` e popola `phone.matches`." }, "disposable_number_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Cosa fare quando la ricerca dell'operatore segnala il numero come linea temporanea/usa e getta (`phone.is_disposable`). `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il rischio in `phone.warnings`." }, "voip_number_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Cosa fare quando la ricerca dell'operatore restituisce un tipo di linea virtuale — `voip`, `isp` o `vpn` (`phone.is_virtual`). `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il rischio in `phone.warnings`." }, "enable_enrichment": { "type": "boolean", "default": false, "description": "Quando è `true`, esegue anche l'analisi del numero di telefono: un punteggio di rischio, il tipo di linea, l'eventuale portabilità recente e un indice di affidabilità. Fatturato come un'unità `phone_intelligence_api` per richiesta ($0.05 a prezzo di listino) in aggiunta al prezzo di questo endpoint. La richiesta restituisce `403` quando il tuo saldo non è sufficiente a coprirlo.", "example": false }, "phone_intelligence_score_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Azione quando il punteggio di rischio dell'intelligence telefonica supera la soglia. `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il segnale senza rifiutare. Ha effetto solo quando `enable_enrichment` è `true`." }, "phone_type_risk_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Azione quando il numero appartiene a un tipo di linea ad alto rischio. `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il segnale senza rifiutare. Ha effetto solo quando `enable_enrichment` è `true`." }, "recent_port_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Azione quando il numero è stato trasferito di recente a un altro operatore. `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il segnale senza rifiutare. Ha effetto solo quando `enable_enrichment` è `true`." }, "low_phone_trust_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Azione quando l'indice di affidabilità dell'intelligence telefonica è pari o inferiore alla soglia. `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il segnale senza rifiutare. Ha effetto solo quando `enable_enrichment` è `true`." }, "enable_social": { "type": "boolean", "default": false, "description": "Se true, cerca anche l'impronta social del numero: le piattaforme di messaggistica, social, e-commerce e professionali su cui è registrato. Fatturato come un'unità `phone_social` per richiesta in aggiunta al prezzo di questo endpoint.", "example": true }, "phone_no_social_presence_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Azione quando il controllo dell'impronta social rileva che il numero non è registrato su nessuna delle piattaforme coperte. Solo NO_ACTION e DECLINE sono accettati su questo endpoint; REVIEW è disponibile sulla chiave di configurazione del workflow con lo stesso nome." } }, "required": [ "phone_number", "code" ] }, "examples": { "Default": { "summary": "Registra eventuali rischi ma non rifiutare mai automaticamente", "value": { "phone_number": "+14155552671", "code": "123456" } }, "Strict risk policy": { "summary": "Rifiuta automaticamente linee VoIP e monouso", "value": { "phone_number": "+14155552671", "code": "123456", "voip_number_action": "DECLINE", "disposable_number_action": "DECLINE" } } } } } }, "responses": { "200": { "description": "Verifica completata: anche i codici errati e le verifiche mancanti restituiscono `200`; esamina `status`, non il codice HTTP. `phone` viene popolato solo per gli esiti definitivi (`Approved`/`Declined`), è `null` per `Failed` ed è assente per `Expired or Not Found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerificationCheckResponse" }, "examples": { "Approved": { "summary": "Codice corretto — report telefonico completo con operatore, ciclo di vita e corrispondenze", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Approved", "message": "The verification code is correct.", "phone": { "status": "Approved", "phone_number_prefix": "+1", "phone_number": "4155552671", "full_number": "+14155552671", "country_code": "US", "country_name": "United States", "carrier": { "name": "AT&T", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.0509 }, { "type": "PHONE_DELIVERY_DELIVERED", "timestamp": "2026-06-12T01:23:43.118220+00:00", "details": { "channel": "whatsapp", "status": "delivered" }, "fee": 0 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Failed (attempts remaining)": { "summary": "Codice errato: l'utente può riprovare; request_id qui è un UUID monouso", "value": { "request_id": "11111111-2222-3333-4444-555555555555", "status": "Failed", "message": "The verification code is incorrect. Attempts remaining: 2", "phone": null, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:21.512340+00:00" } }, "Declined (max attempts)": { "summary": "Terzo codice errato: verifica finalizzata come Rifiutata", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Declined", "message": "The verification code is incorrect. Maximum attempts reached.", "phone": { "status": "Declined", "phone_number_prefix": "+1", "phone_number": "4155552671", "full_number": "+14155552671", "country_code": "US", "country_name": "United States", "carrier": { "name": "AT&T", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": null, "warnings": [ { "feature": "PHONE", "risk": "VERIFICATION_CODE_ATTEMPTS_EXCEEDED", "additional_data": null, "log_type": "error", "short_description": "Verification code attempts exceeded", "long_description": "The system detected that the phone number has exceeded the maximum number of verification code attempts." } ], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.0509 }, { "type": "INVALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:01.118220+00:00", "details": { "code_tried": "111111", "status": "Failed" }, "fee": 0 }, { "type": "INVALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:21.512340+00:00", "details": { "code_tried": "222222", "status": "Failed" }, "fee": 0 }, { "type": "INVALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "333333", "status": "Failed" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_DECLINED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": { "reason": "VERIFICATION_CODE_ATTEMPTS_EXCEEDED" }, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Declined (risk policy)": { "summary": "Codice corretto, ma la linea è VoIP e voip_number_action=DECLINE", "value": { "request_id": "7f1c9d2e-44a1-4b6e-9a3e-5b8e6f1c2d3a", "status": "Declined", "message": "The verification code is correct.", "phone": { "status": "Declined", "phone_number_prefix": "+1", "phone_number": "5005550006", "full_number": "+15005550006", "country_code": "US", "country_name": "United States", "carrier": { "name": "CLEC LLC", "type": "voip" }, "is_disposable": false, "is_virtual": true, "verification_method": "sms", "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [ { "feature": "PHONE", "risk": "VOIP_NUMBER_DETECTED", "additional_data": null, "log_type": "error", "short_description": "VoIP number detected", "long_description": "The system detected that the phone number is a VoIP number, which is not allowed." } ], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "sms" }, "fee": 0.0509 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_DECLINED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": { "reason": "VOIP_NUMBER_DETECTED" }, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Expired or Not Found": { "summary": "Nessuna verifica in sospeso per questo numero negli ultimi 5 minuti", "value": { "request_id": "69cc35c6-280a-47a6-ab8c-4f32abc02ed0", "status": "Expired or Not Found", "message": "No pending phone verification found in the last 5 minutes.", "vendor_data": null, "metadata": null, "created_at": "2026-06-12T01:24:47.311323+00:00" } } } } } }, "400": { "description": "Errore di validazione — busta dell'errore di campo di DRF: un array di messaggi per campo non conforme.", "content": { "application/json": { "examples": { "Invalid code format": { "summary": "`code` non è composto da 4–8 cifre numeriche", "value": { "code": [ "Invalid code format. Enter 4 to 8 numeric digits." ] } }, "Invalid phone number": { "summary": "`phone_number` non è un numero E.164 valido", "value": { "phone_number": [ "Invalid phone number provided." ] } }, "Invalid action": { "summary": "Le azioni di rischio accettano solo NO_ACTION o DECLINE", "value": { "voip_number_action": [ "\"REVIEW\" is not a valid choice." ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante; una chiave errata, revocata o scaduta restituisce `401`. I controlli sono gratuiti, pertanto qui non viene eseguito alcun controllo del credito disponibile.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). Inoltre, a monte si applica un limite anti-abuso di 4 tentativi di verifica per numero di telefono all'ora. La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. Nota: le intestazioni `X-RateLimit-*`/`Retry-After` accompagnano solo l'errore 429 relativo al limite di scrittura di 300/min; l'errore 429 relativo al limite per numero di telefono non include intestazioni del limite di frequenza.", "content": { "application/json": { "examples": { "Per-number cap": { "summary": "Più di 4 tentativi di verifica per lo stesso numero nell'ultima ora", "value": { "detail": "Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number." } }, "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "502": { "description": "Il provider di verifica telefonica è temporaneamente non disponibile: una risposta 5xx, timeout o errore di connessione persistito dopo i nuovi tentativi integrati. È possibile riprovare in sicurezza; il budget di tentativi non viene consumato.", "content": { "application/json": { "examples": { "Provider outage": { "summary": "Il provider non ha risposto alla richiesta di verifica", "value": { "detail": "Phone verification is temporarily unavailable. Please try again shortly.", "code": "phone_provider_unavailable" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "Errore imprevisto a monte durante la verifica del codice non riconducibile a un'interruzione nota del fornitore. È sicuro effettuare un nuovo tentativo; il limite di tentativi viene consumato solo dai controlli completati.", "content": { "application/json": { "examples": { "Provider error": { "summary": "Impossibile completare la verifica del codice", "value": { "detail": "Error checking phone verification" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/bank/account-check/": { "post": { "summary": "Verifica un conto bancario", "description": "Verifica che un conto bancario appartenga alla persona o all'azienda indicata, prima di inviarvi denaro. Nessuna sessione e nessun accesso: invia il nome e il conto, leggi il risultato. È il [controllo del conto](/it/core-technology/bank-verification/account-check) del passaggio Bank Verification, eseguito dal tuo backend.\n\n**Cosa invii.** Il `country` del conto (ISO 3166-1 alpha-3), l'`account` nel formato previsto da quel paese e il nome dell'`holder`: `full_name` per una persona fisica o `business_name` per un'azienda. Un nome aziendale verifica un conto aziendale.\n\n**Cosa ricevi in risposta.** `result` è `match`, `close_match`, `no_match` o `cannot_verify`. Con `close_match`, `holder_name` è l'intestatario associato al conto dalla banca, qualora quest'ultima lo abbia restituito. L'`account` viene restituito mascherato con solo gli ultimi 4 caratteri visibili.\n\n**Fatturazione.** Ogni verifica a cui la banca risponde viene fatturata una volta al prezzo di controllo del conto del paese corrispondente, qualunque sia il risultato: vengono fatturati anche `no_match`, un conto inesistente e `cannot_verify`. Una richiesta a cui viene risposto con un errore non viene mai fatturata.\n\n**Ogni richiesta è una nuova verifica.** Non esiste una chiave di idempotenza né un endpoint per rileggere un controllo già eseguito, pertanto una richiesta ripetuta viene eseguita, e fatturata, nuovamente. Salva la risposta.\n\n**Sandbox.** Usa una chiave API sandbox con i dati di conto di esempio. Una chiave sandbox non chiama alcuna banca e non prevede addebiti. Gli ultimi 4 caratteri dell'IBAN, o in alternativa del numero di conto, determinano la risposta: `0001` un `close_match` con un `holder_name`, `0002` un `close_match` senza, `0003` e `0006` un `no_match`, `0004` `cannot_verify`, `0005` un `503` e `0009` un `400`. Qualsiasi altra terminazione corrisponde a un `match`.\n\n**Chiavi API.** Una chiave API con ambiti richiede l'accesso in scrittura alle sessioni.", "operationId": "post_v3_bank_account_check", "tags": [ "Standalone APIs" ], "x-didit-sdk": { "resource": "bank", "method": "account_check", "auth": "api_key", "server": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckRequest" }, "examples": { "Person, Nigeria": { "summary": "Un codice bancario e un numero di conto, verificati rispetto al nome di una persona", "value": { "country": "NGA", "account": { "bank_code": "000014", "account_number": "0123450001" }, "holder": { "full_name": "Maria Oliveira" }, "vendor_data": "payout_20481" } }, "Company, Nigeria": { "summary": "Un codice bancario e un numero di conto, verificati rispetto alla ragione sociale di un'azienda", "value": { "country": "NGA", "account": { "bank_code": "000014", "account_number": "0123456789" }, "holder": { "business_name": "Northwind Trading Ltd" } } } } } } }, "responses": { "200": { "description": "La banca ha risposto. Il controllo viene fatturato, qualunque sia il risultato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckResponse" }, "examples": { "Close match": { "summary": "La banca detiene il conto sotto un nome simile", "value": { "request_id": "c2f4a9e0-7b1d-4c3a-9e55-1d0a6b8f2a47", "result": "close_match", "holder_name": "MARIA R OLIVEIRA", "account": "****0001", "vendor_data": "payout_20481", "created_at": "2026-10-21T14:32:08Z" } }, "Match": { "summary": "La banca detiene il conto sotto il nome inviato", "value": { "request_id": "5b0e2d7c-41a8-4f6e-9c3b-8e7d1a2f6c90", "result": "match", "holder_name": null, "account": "****6789", "vendor_data": null, "created_at": "2026-10-21T14:35:41Z" } } } } } }, "400": { "description": "Rifiutata così come inviata e non fatturata. `field` indica il campo del corpo da correggere e `reason` ne spiega il motivo, con le stesse motivazioni mostrate dal modulo dell'account ospitato. Viene segnalato solo il primo campo rifiutato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Missing field": { "summary": "La verifica del paese richiede un codice bancario", "value": { "detail": "The bank code is not valid (required).", "code": "invalid_account_input", "field": "account.bank_code", "reason": "required" } }, "Invalid IBAN": { "summary": "L'IBAN ha una lunghezza non valida per il rispettivo paese", "value": { "detail": "The iban is not valid (length).", "code": "invalid_account_input", "field": "account.iban", "reason": "length" } }, "Refused by the bank": { "summary": "La banca ha rifiutato il conto così come inviato", "value": { "detail": "The account was refused as typed (rejected).", "code": "invalid_account_input", "field": "account.account_number", "reason": "rejected" } }, "No name": { "summary": "`holder` non contiene né `full_name` né `business_name`", "value": { "detail": "Send full_name for a person or business_name for a company.", "code": "invalid_account_input", "field": "holder", "reason": "required" } }, "Consent required": { "summary": "La verifica del conto nel paese richiede il consenso del titolare del conto", "value": { "detail": "Account checks in this country need the account holder's explicit consent. Ask for it, then send `consent=true`.", "code": "invalid_account_input", "field": "consent", "reason": "required" } } } } } }, "401": { "description": "La chiave API con ambito è scaduta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "402": { "description": "Il controllo non può essere pagato, pertanto non è stato eseguito. Ricarica il tuo saldo, quindi invialo di nuovo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Out of credit": { "summary": "Il tuo saldo non copre un controllo", "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me", "code": "insufficient_credits" } }, "Not in your contract": { "summary": "Il tuo contratto non prevede un prezzo per l'API Account check", "value": { "detail": "Your contract does not price the Account check API. Contact your account manager.", "code": "contract_rate_missing" } } } } } }, "403": { "description": "L'intestazione `x-api-key` o il token bearer sono mancanti o non validi, la richiesta proviene da un indirizzo non presente nell'elenco IP della chiave, oppure una chiave con ambito limitato non ha permessi di scrittura per le sessioni.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna chiave API valida o token valido", "value": { "detail": "You do not have permission to perform this action." } }, "No sessions write": { "summary": "Una chiave con ambito limitato priva di accesso in scrittura alle sessioni", "value": { "detail": "This API key has no write access to sessions." } } } } } }, "404": { "description": "Nessun controllo del conto copre ancora questo conto, pertanto non è stato verificato né fatturato nulla. `country_not_covered`: nessuno copre il relativo paese o quel tipo di conto (persona o azienda) in tale paese. `bank_not_covered`: nessuno copre la relativa banca.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Country not covered": { "summary": "Nessun controllo del conto copre il paese", "value": { "detail": "No account check serves this country yet.", "code": "country_not_covered" } }, "Bank not covered": { "summary": "Nessun controllo del conto copre la banca del conto", "value": { "detail": "No account check serves this account's bank yet.", "code": "bank_not_covered" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" }, "503": { "description": "La banca non è riuscita a rispondere. Non è stato verificato né fatturato nulla; invia nuovamente il controllo più tardi.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Unavailable": { "summary": "La banca non ha risposto", "value": { "detail": "The account check is temporarily unavailable and this request was not charged. Please try again.", "code": "account_check_unavailable" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/bank/account-check/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"country\": \"NGA\",\n \"account\": {\"bank_code\": \"000014\", \"account_number\": \"0123450001\"},\n \"holder\": {\"full_name\": \"Maria Oliveira\"},\n \"vendor_data\": \"payout_20481\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.bank.account_check(\n country=\"NGA\",\n account={\n \"account_number\": \"0123450001\",\n \"bank_code\": \"000014\",\n },\n holder={\n \"full_name\": \"Maria Oliveira\",\n },\n vendor_data=\"payout_20481\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.bank.accountCheck({\n country: \"NGA\",\n account: {\n account_number: \"0123450001\",\n bank_code: \"000014\",\n },\n holder: {\n full_name: \"Maria Oliveira\",\n },\n vendor_data: \"payout_20481\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.AccountCheck(ctx, didit.BankAccountCheckRequest{\n\tCountry: \"NGA\",\n\tAccount: didit.BankAccountCheckRequestAccount{\n\t\tAccountNumber: didit.String(\"0123450001\"),\n\t\tBankCode: didit.String(\"000014\"),\n\t},\n\tHolder: didit.BankAccountCheckHolder{\n\t\tFullName: didit.String(\"Maria Oliveira\"),\n\t},\n\tVendorData: didit.String(\"payout_20481\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BankAccountCheckHolder;\nimport me.didit.types.BankAccountCheckPersonHolder;\nimport me.didit.types.BankAccountCheckRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.bank().accountCheck(BankAccountCheckRequest.builder()\n .country(\"NGA\")\n .account(BankAccountCheckRequest.Account.builder()\n .accountNumber(\"0123450001\")\n .bankCode(\"000014\")\n .build())\n .holder(BankAccountCheckHolder.ofBankAccountCheckPersonHolder(BankAccountCheckPersonHolder.builder()\n .fullName(\"Maria Oliveira\")\n .build()))\n .vendorData(\"payout_20481\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "bank->accountCheck([\n 'country' => 'NGA',\n 'account' => [\n 'account_number' => '0123450001',\n 'bank_code' => '000014',\n ],\n 'holder' => [\n 'full_name' => 'Maria Oliveira',\n ],\n 'vendor_data' => 'payout_20481',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.bank.account_check(\n country: \"NGA\",\n account: {\n account_number: \"0123450001\",\n bank_code: \"000014\",\n },\n holder: {\n full_name: \"Maria Oliveira\",\n },\n vendor_data: \"payout_20481\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Bank.AccountCheckAsync(new BankAccountCheckRequest\n{\n Country = \"NGA\",\n Account = new()\n {\n AccountNumber = \"0123450001\",\n BankCode = \"000014\",\n },\n Holder = new()\n {\n FullName = \"Maria Oliveira\",\n },\n VendorData = \"payout_20481\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/email/send/": { "post": { "summary": "Invia codice email", "description": "Invia un codice monouso (OTP) a un indirizzo email, quindi verificalo con [`POST /v3/email/check/`](/it/standalone-apis/email-check).\n\n**Come si abbinano invio e verifica.** Lo stato della verifica è associato alla tua applicazione e all'indirizzo `email` — la chiamata di verifica non richiede `request_id`. Ogni nuovo invio crea una verifica in sospeso valida per **5 minuti**: chiama l'endpoint di verifica con lo stesso indirizzo e il codice ricevuto dall'utente prima che la finestra temporale scada. Se chiami nuovamente l'invio per lo stesso indirizzo mentre una verifica è ancora in sospeso, viene generato un nuovo codice per quella stessa verifica (`status: \"Retry\"`, stesso `request_id`); il codice precedente smette di funzionare. È possibile associare al massimo un nuovo tentativo in questo modo (due invii in totale); un ulteriore invio avvia una nuova verifica con un nuovo `request_id`. La finestra di 5 minuti viene calcolata a partire dal primo invio e non viene prolungata dai nuovi tentativi.\n\n**Pre-verifica di recapitabilità.** Prima di qualsiasi invio, l'indirizzo viene sottoposto a una validazione della sintassi e dei record DNS/MX. Gli indirizzi non in grado di ricevere posta restituiscono `200` con `status: \"Undeliverable\"` e `reason: \"email_can_not_be_delivered\"` — non viene inviata alcuna email, non viene addebitato alcun costo e la verifica viene immediatamente finalizzata come `Declined` (un controllo successivo restituisce `Expired or Not Found`). Un invio che fallisce per un motivo non legato all'indirizzo (l'email non ha potuto essere presa in carico per la consegna) restituisce invece `503`: nessun codice viene inviato, non viene addebitato alcun costo, la verifica rimane aperta e la stessa richiesta può essere ripetuta.\n\n**Formato del codice e personalizzazione del brand.** I codici sono composti da 4–8 caratteri (`options.code_size`, predefinito 6), numerici per impostazione predefinita; imposta `options.alphanumeric_code: true` per lettere maiuscole e cifre (il confronto in fase di verifica non fa distinzione tra maiuscole e minuscole). Il modello email è localizzato tramite `options.locale` (54 lingue supportate) e può utilizzare la personalizzazione del brand white label della tua applicazione tramite `options.use_white_label_customization`.\n\n**Fatturazione.** Un credito API di Email Verification per ogni invio riuscito (`status: \"Success\"`), addebitato al momento dell'invio. Gli invii con esito `Retry` e `Undeliverable` sono gratuiti, così come le verifiche.\n\n**Persistenza della sessione.** Ogni nuova verifica viene salvata come sessione di tipo API: `request_id` è un vero ID sessione che puoi passare a `GET /v3/session/{sessionId}/decision/`, la verifica compare nella Business Console e i webhook `status.updated` vengono attivati man mano che procede.\n\n**Sandbox.** Le chiavi API sandbox ignorano la consegna e la fatturazione: dopo la validazione della richiesta (l'input non valido restituisce comunque `400`), l'endpoint restituisce un payload statico `Success` con un `request_id` casuale; non viene inviata alcuna email e nulla viene memorizzato. Usa il codice `123456` per il controllo in sandbox.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`.", "operationId": "post_v3email_send", "x-didit-sdk": { "resource": "email", "method": "send_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/email/send/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"alice@example.com\",\n \"options\": { \"code_size\": 6, \"locale\": \"en\" },\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.email.send_code(\n email=\"alice@example.com\",\n options={\n \"locale\": \"en\",\n },\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.email.sendCode({\n email: \"alice@example.com\",\n options: {\n locale: \"en\",\n },\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.SendCode(ctx, didit.EmailSendCodeParams{\n\tEmail: \"alice@example.com\",\n\tOptions: didit.Some(didit.EmailSendCodeParamsOptions{\n\t\tLocale: didit.Some(didit.EmailSendCodeParamsOptionsLocale(\"en\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EmailSendCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.email().sendCode(EmailSendCodeParams.builder()\n .email(\"alice@example.com\")\n .options(EmailSendCodeParams.Options.builder()\n .locale(EmailSendCodeParams.Options.Locale.of(\"en\"))\n .build())\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "email->sendCode([\n 'email' => 'alice@example.com',\n 'options' => [\n 'locale' => 'en',\n ],\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.email.send_code(\n email: \"alice@example.com\",\n options: {\n locale: \"en\",\n },\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Email.SendCodeAsync(new EmailSendCodeParams\n{\n Email = \"alice@example.com\",\n Options = new EmailSendCodeParamsOptions\n {\n Locale = new EmailSendCodeParamsOptionsLocale(\"en\"),\n },\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Indirizzo email del destinatario. Gli indirizzi non formattati correttamente restituiscono `400`; gli indirizzi sintatticamente validi che non possono ricevere posta (convalida DNS/MX non riuscita) restituiscono `200` con `status: \"Undeliverable\"`.", "example": "alice@example.com" }, "options": { "type": "object", "description": "Opzioni di formato, localizzazione e branding dell'OTP. Tutti i campi sono facoltativi.", "properties": { "code_size": { "type": "integer", "minimum": 4, "maximum": 8, "default": 6, "description": "Numero di caratteri nell'OTP (cifre per impostazione predefinita; lettere maiuscole e cifre quando `alphanumeric_code` è `true`)." }, "alphanumeric_code": { "type": "boolean", "default": false, "description": "Quando è `true`, l'OTP è composto da lettere maiuscole `A–Z` e cifre `0–9` anziché solo da cifre. Il confronto in `/v3/email/check/` non fa distinzione tra maiuscole e minuscole." }, "locale": { "type": "string", "maxLength": 5, "enum": [ "en", "ar", "bn", "bg", "bs", "ca", "cs", "da", "de", "el", "es", "et", "fa", "fi", "fr", "he", "hi", "hr", "hu", "hy", "id", "it", "ja", "ka", "kk", "ko", "ky", "lt", "lv", "cnr", "mk", "mn", "ms", "nl", "no", "pl", "pt-BR", "pt", "ro", "ru", "sk", "sl", "so", "sq", "sr", "sv", "th", "tr", "uk", "uz", "vi", "zh-CN", "zh-TW", "zh" ], "description": "Lingua del modello di email OTP. Il valore predefinito è `en`. I valori non supportati restituiscono `400` elencando tutte le impostazioni locali supportate.", "example": "en" }, "use_white_label_customization": { "type": "boolean", "default": false, "description": "Quando è `true`, l'email con l'OTP utilizza la personalizzazione white label della tua applicazione (logo, colori, personalizzazione del mittente) anziché il modello predefinito di Didit." } } }, "signals": { "type": "object", "description": "Segnali opzionali di dispositivo e rete relativi all'utente finale, inoltrati al livello antifrode per migliorare il rilevamento del traffico abusivo o automatizzato. Tutti i campi sono opzionali.", "properties": { "ip": { "type": "string", "description": "Indirizzo IP del dispositivo dell'utente finale. IPv4 o IPv6.", "example": "192.0.2.1" }, "device_id": { "type": "string", "maxLength": 255, "description": "Identificativo univoco del dispositivo dell'utente finale. Android: `ANDROID_ID`; iOS: `identifierForVendor`.", "example": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2" }, "device_platform": { "type": "string", "enum": [ "android", "ios", "ipados", "tvos", "web" ], "description": "Piattaforma del dispositivo dell'utente finale." }, "device_model": { "type": "string", "maxLength": 255, "description": "Modello del dispositivo dell'utente finale.", "example": "iPhone17,2" }, "os_version": { "type": "string", "maxLength": 64, "description": "Versione del sistema operativo del dispositivo dell'utente finale.", "example": "18.0.1" }, "app_version": { "type": "string", "maxLength": 64, "description": "Versione della tua applicazione.", "example": "1.2.34" }, "user_agent": { "type": "string", "maxLength": 512, "description": "User agent del browser o dell'app dell'utente finale.", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1" } } }, "vendor_data": { "type": "string", "description": "Identificatore opzionale controllato dal chiamante (il tuo ID utente interno, un'email, un UUID, ecc.) memorizzato nella sessione e restituito nella risposta di invio, nella risposta di verifica della corrispondenza, nei webhook e nella Business Console. Usalo per correlare il `request_id` di Didit con il record del tuo utente." }, "metadata": { "type": "object", "nullable": true, "description": "Oggetto JSON a struttura libera opzionale memorizzato nella sessione e restituito nella risposta di invio, nella risposta del controllo di corrispondenza, nei webhook e nella Business Console." } }, "required": [ "email" ] }, "examples": { "Numeric 6-digit code": { "summary": "Predefinito — codice numerico a 6 cifre in inglese", "value": { "email": "alice@example.com", "options": { "locale": "en" }, "vendor_data": "user-1234" } }, "Alphanumeric 8-character code": { "summary": "Lettere maiuscole + cifre, modello spagnolo", "value": { "email": "bob@example.com", "options": { "code_size": 8, "alphanumeric_code": true, "locale": "es" } } }, "White-label branding": { "summary": "Invia l'email OTP con la personalizzazione white label della tua applicazione", "value": { "email": "carol@example.com", "options": { "locale": "en", "use_white_label_customization": true }, "vendor_data": "user-5678" } } } } } }, "responses": { "200": { "description": "Invio confermato. Ispeziona `status`: `Success` e `Retry` indicano che un codice è in arrivo; `Undeliverable` indica che l'indirizzo non può ricevere posta e la verifica è già finalizzata come `Declined`. `request_id` è l'ID di sessione persistente (stesso ID in caso di `Retry`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationSendResponse" }, "examples": { "Success": { "summary": "OTP inviato via email per una nuova verifica (fatturato)", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Success", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Retry": { "summary": "Secondo invio entro la finestra di 5 minuti — nuovo codice, stesso request_id, gratuito", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Retry", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Undeliverable": { "summary": "L'indirizzo non ha superato la convalida DNS/MX: verifica completata come Rifiutata, nessun addebito", "value": { "request_id": "cb1a5011-344d-444d-bdce-218904745d7f", "status": "Undeliverable", "reason": "email_can_not_be_delivered", "vendor_data": "user-1234", "metadata": null } } } } } }, "400": { "description": "Errore di validazione — busta dell'errore di campo di DRF: un array di messaggi per campo non conforme, annidato sotto `options` per gli errori delle opzioni.", "content": { "application/json": { "examples": { "Invalid email": { "summary": "Indirizzo email non valido", "value": { "email": [ "Enter a valid email address." ] } }, "Unsupported locale": { "summary": "`options.locale` non compreso tra quelli supportati", "value": { "options": { "locale": [ "Invalid locale. Supported locales are en, ar, bn, bg, bs, ca, cs, da, de, el, es, et, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, kk, ko, ky, lt, lv, cnr, mk, mn, ms, nl, no, pl, pt-BR, pt, ro, ru, sk, sl, so, sq, sr, sv, th, tr, uk, uz, vi, zh-CN, zh-TW, zh." ] } } }, "Code size out of range": { "summary": "`options.code_size` non compreso tra 4 e 8", "value": { "options": { "code_size": [ "Ensure this value is less than or equal to 8." ] } } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante (`{\"detail\": ...}`); una chiave errata, revocata o scaduta restituisce `401`. Restituito inoltre prima di qualsiasi invio quando il saldo dell'organizzazione non è sufficiente a coprire un credito dell'API Verifica email (`{\"error\": ...}`).", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire il prezzo di invio", "value": { "error": "You don't have enough credits to perform this request." } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "description": "Impossibile inviare l'email per un motivo indipendente dall'indirizzo (il provider email non è raggiungibile, è andato in timeout o ha rifiutato l'invio stesso), quindi nessun codice è stato inviato e nulla è stato fatturato o conteggiato come tentativo di invio. Ripeti la stessa richiesta.", "content": { "application/json": { "examples": { "Email delivery unavailable": { "summary": "Il provider email non è riuscito a inviare l'email dopo un nuovo tentativo automatico", "value": { "detail": "Email delivery is temporarily unavailable. Please try again." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/email/check/": { "post": { "summary": "Verifica codice email", "description": "Verifica l'OTP recapitato da [`POST /v3/email/send/`](/it/standalone-apis/email-send) e ottieni il risultato finale di verifica oltre ai dati di intelligence sull'email: recapitabilità, esposizione a violazioni dei dati (`is_breached` e la lista `breaches` da un database di intelligence sulle violazioni), rilevamento di provider usa e getta e uso duplicato dell'indirizzo nelle varie sessioni.\n\n**Come la verifica individua il record.** Il confronto avviene in base alla tua applicazione e all'indirizzo `email` — `request_id` non è un input. Viene verificata la verifica più recente ancora in sospeso creata negli ultimi **5 minuti**. Se non ne esiste alcuna (mai inviata, già finalizzata, irrecapitabile al momento dell'invio o risalente a più di 5 minuti prima), l'endpoint restituisce `200` con `status: \"Expired or Not Found\"`.\n\n**Budget di tentativi.** Ogni verifica consente **3 tentativi di codice**. I primi due codici errati restituiscono `status: \"Failed\"` con i tentativi rimanenti e `email: null`; il terzo codice errato finalizza la verifica come `Declined` con un avviso `EMAIL_CODE_ATTEMPTS_EXCEEDED` e restituisce il report email completo. I codici vengono confrontati senza distinzione tra maiuscole e minuscole (rilevante per gli invii con `alphanumeric_code`); solo l'ultimo codice inviato è valido.\n\n**Esiti.** `Approved` — codice corretto e nessun rischio ostativo. `Declined` — terminale: il codice era corretto ma è stato rilevato un rischio ostativo (un'azione `DECLINE` indicata di seguito, un indirizzo in blocklist o un indirizzo risultato irrecapitabile alla finalizzazione), oppure il budget di tentativi è stato esaurito. `Failed` — codice errato, tentativi rimanenti. `Expired or Not Found` — nulla da verificare. Con `Approved`/`Declined` il valore `request_id` corrisponde al `request_id` dell'invio (l'ID di sessione) e `email` include il report completo (`is_breached`, `breaches`, `is_disposable`, `is_undeliverable`, `warnings`, `lifecycle`, `matches`); con `Failed` ed `Expired or Not Found` il `request_id` è un UUID casuale monouso.\n\n**Azioni di rischio.** `duplicated_email_action`, `breached_email_action` e `disposable_email_action` stabiliscono cosa accade quando viene rilevato il rischio corrispondente a fronte di un codice corretto: `DECLINE` converte lo stato finale in `Declined`; `NO_ACTION` (predefinito) registra il rischio in `email.warnings` senza modificare lo stato.\n\n**Fatturazione.** I controlli sono gratuiti — il credito viene consumato dall'invio riuscito.\n\n**Persistenza della sessione.** Un controllo finalizzato aggiorna la sessione creata dall'invio (visibile nella Business Console, consultabile tramite `GET /v3/session/{sessionId}/decision/`) e attiva un webhook `status.updated`.\n\n**Sandbox.** Le chiavi API sandbox ignorano tutte le elaborazioni: qualsiasi codice ben formato (`123456` incluso) restituisce un payload `Approved` statico con un oggetto `email` semplificato (`status`, `email`, `is_breached`, `is_disposable`, `is_undeliverable`); un input malformato restituisce comunque `400`. Nulla viene reso persistente.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`.\n\n**Impronta social.** Imposta `enable_social` su `true` per aggiungere un blocco `email_social`: le piattaforme online su cui questo indirizzo è registrato, con conteggi per categoria e gli eventuali dettagli del profilo disponibili. `profiles_registered: 0` indica che le piattaforme sono state verificate e che l'indirizzo non è stato trovato su nessuna di esse: una risposta valida e fatturabile. Il blocco è assente quando il componente aggiuntivo non è stato richiesto o non è stato possibile completare il controllo; in tal caso non viene fatturato. La fatturazione aggiunge un'unità `email_social` per richiesta oltre al prezzo proprio di questo endpoint.", "operationId": "post_v3email_check", "x-didit-sdk": { "resource": "email", "method": "check_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/email/check/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"alice@example.com\",\n \"code\": \"123456\",\n \"disposable_email_action\": \"DECLINE\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.email.check_code(\n email=\"alice@example.com\",\n code=\"123456\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.email.checkCode({\n email: \"alice@example.com\",\n code: \"123456\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.CheckCode(ctx, didit.EmailCheckCodeParams{\n\tEmail: \"alice@example.com\",\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EmailCheckCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.email().checkCode(EmailCheckCodeParams.builder()\n .email(\"alice@example.com\")\n .code(\"123456\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "email->checkCode([\n 'email' => 'alice@example.com',\n 'code' => '123456',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.email.check_code(\n email: \"alice@example.com\",\n code: \"123456\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Email.CheckCodeAsync(new EmailCheckCodeParams\n{\n Email = \"alice@example.com\",\n Code = \"123456\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Lo stesso indirizzo email utilizzato nella chiamata corrispondente [`POST /v3/email/send/`](/it/standalone-apis/email-send). Questo è ciò che collega la verifica all'invio.", "example": "alice@example.com" }, "code": { "type": "string", "maxLength": 10, "description": "L'OTP ricevuto dall'utente finale: 4–8 cifre, oppure 4–8 lettere/cifre quando è stato utilizzato `alphanumeric_code: true` al momento dell'invio. Il confronto non fa distinzione tra maiuscole e minuscole.", "example": "123456" }, "duplicated_email_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Cosa fare quando lo stesso indirizzo è già stato utilizzato e approvato da un utente diverso (contano solo le verifiche precedentemente approvate) (diverso `vendor_data`) della tua applicazione. `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il rischio in `email.warnings` e popola `email.matches`." }, "breached_email_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Cosa fare quando l'indirizzo compare in violazioni di dati note (`email.is_breached`). `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il rischio in `email.warnings`." }, "disposable_email_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Cosa fare quando il dominio appartiene a un provider di posta usa e getta/temporanea (`email.is_disposable`). `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il rischio in `email.warnings`." }, "enable_enrichment": { "type": "boolean", "default": false, "description": "Quando è `true`, esegue anche l'analisi dell'indirizzo email: un punteggio di rischio e la relativa cronologia delle violazioni. Fatturato come un'unità `email_intelligence_api` per richiesta ($0.05 a prezzo di listino) in aggiunta al prezzo di questo endpoint. La richiesta restituisce `403` quando il tuo saldo non è sufficiente a coprirlo.", "example": false }, "email_intelligence_score_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Azione quando il punteggio di rischio dell'intelligence delle email supera la soglia. `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il segnale senza rifiutare. Ha effetto solo quando `enable_enrichment` è `true`." }, "recent_email_breach_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Azione quando l'indirizzo compare in una recente violazione dei dati nota. `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il segnale senza rifiutare. Ha effetto solo quando `enable_enrichment` è `true`." }, "frequent_email_breach_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Azione quando l'indirizzo compare in molteplici violazioni dei dati note. `DECLINE` imposta lo `status` finale su `Declined`; `NO_ACTION` registra il segnale senza rifiutare. Ha effetto solo quando `enable_enrichment` è `true`." }, "enable_social": { "type": "boolean", "default": false, "description": "Se true, cerca anche l'impronta social dell'indirizzo: le piattaforme email, social, professionali, di e-commerce e di intrattenimento su cui è registrato. Fatturato come un'unità `email_social` per richiesta in aggiunta al prezzo di questo endpoint.", "example": true }, "email_no_social_presence_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "Azione quando il controllo dell'impronta social rileva che l'indirizzo non è registrato su nessuna delle piattaforme coperte. Solo NO_ACTION e DECLINE sono accettati su questo endpoint; REVIEW è disponibile sulla chiave di configurazione del workflow con lo stesso nome." } }, "required": [ "email", "code" ] }, "examples": { "Default": { "summary": "Registra eventuali rischi ma non rifiutare mai automaticamente", "value": { "email": "alice@example.com", "code": "123456" } }, "Strict risk policy": { "summary": "Rifiuta automaticamente caselle di posta monouso e compromesse", "value": { "email": "alice@example.com", "code": "123456", "disposable_email_action": "DECLINE", "breached_email_action": "DECLINE" } } } } } }, "responses": { "200": { "description": "Verifica completata: anche i codici errati e le verifiche mancanti restituiscono `200`; esamina `status`, non il codice HTTP. Il campo `email` viene popolato solo per gli esiti definitivi (`Approved`/`Declined`), è `null` per `Failed` ed è assente per `Expired or Not Found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationCheckResponse" }, "examples": { "Approved": { "summary": "Codice corretto — indirizzo pulito, report email completo", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Approved", "message": "The verification code is correct.", "email": { "status": "Approved", "email": "alice@example.com", "is_breached": false, "breaches": [], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Approved with breach exposure": { "summary": "Codice corretto; esposizione a violazioni registrata come avviso (breached_email_action=NO_ACTION)", "value": { "request_id": "3a1f2b6c-9d4e-4f7a-8b2c-1e5d6f7a8b9c", "status": "Approved", "message": "The verification code is correct.", "email": { "status": "Approved", "email": "bob@example.com", "is_breached": true, "breaches": [ { "name": "ExampleApp", "domain": "exampleapp.com", "breach_date": "2019-03-21", "breach_emails_count": 763117, "description": "In March 2019, the social platform ExampleApp suffered a data breach that exposed email addresses and passwords.", "logo_path": "https:///logos/ExampleApp.png", "data_classes": [ "email_addresses", "passwords" ], "is_verified": true } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [ { "feature": "EMAIL", "risk": "BREACHED_EMAIL_DETECTED", "additional_data": null, "log_type": "information", "short_description": "Breached email detected", "long_description": "This email address was found in one or more known data breaches." } ], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "835126", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0 } ], "matches": [] }, "vendor_data": "user-5678", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Failed (attempts remaining)": { "summary": "Codice errato: l'utente può riprovare; request_id qui è un UUID monouso", "value": { "request_id": "11111111-2222-3333-4444-555555555555", "status": "Failed", "message": "The verification code is incorrect. Attempts remaining: 2", "email": null, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:21.512340+00:00" } }, "Declined (risk policy)": { "summary": "Codice corretto, ma l'indirizzo è usa e getta e disposable_email_action=DECLINE", "value": { "request_id": "8c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "status": "Declined", "message": "The verification code is correct.", "email": { "status": "Declined", "email": "tempuser42@mailinator.com", "is_breached": false, "breaches": [], "is_disposable": true, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [ { "feature": "EMAIL", "risk": "DISPOSABLE_EMAIL_DETECTED", "additional_data": null, "log_type": "error", "short_description": "Disposable email detected", "long_description": "The system detected that the email is disposable, which is not allowed." } ], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_DECLINED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": { "reason": "DISPOSABLE_EMAIL_DETECTED" }, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Expired or Not Found": { "summary": "Nessuna verifica in sospeso per questo indirizzo negli ultimi 5 minuti", "value": { "request_id": "88808a77-06e9-4cb0-85f5-9c052ddfd987", "status": "Expired or Not Found", "message": "No pending email verification found in the last 5 minutes.", "vendor_data": null, "metadata": null, "created_at": "2026-06-12T01:24:59.887904+00:00" } } } } } }, "400": { "description": "Errore di validazione — busta dell'errore di campo di DRF: un array di messaggi per campo non conforme.", "content": { "application/json": { "examples": { "Invalid email": { "summary": "Indirizzo email non valido", "value": { "email": [ "Enter a valid email address." ] } }, "Missing code": { "summary": "`code` non incluso nel corpo", "value": { "code": [ "This field is required." ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante; una chiave errata, revocata o scaduta restituisce `401`. I controlli sono gratuiti, pertanto qui non viene eseguito alcun controllo del credito disponibile.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/workflows/": { "get": { "summary": "Elenca i workflow", "description": "Elenca i tuoi workflow, dal più recente al meno recente, in un contenitore di paginazione limit/offset (`{count, next, previous, results}`, dimensione predefinita della pagina 50). Ogni riga rappresenta una versione; `workflow_id` è l'ID di gruppo stabile e le nuove sessioni utilizzano l'ultima versione `published`.", "operationId": "list_workflows", "x-didit-sdk": { "resource": "workflows", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Dimensione della pagina (numero di workflow per pagina)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Numero di righe da saltare prima del primo workflow restituito." } ], "responses": { "200": { "description": "Una pagina di workflow ordinati per `created_at` in ordine decrescente, inclusi nella struttura di paginazione. Ciascun elemento in `results` è un `WorkflowListItem`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero totale di versioni del workflow per l'applicazione." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina successiva, o `null` nell'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina precedente, o `null` nella prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowListItem" } } } }, "examples": { "Two workflows": { "summary": "Un workflow KYC predefinito e una bozza di workflow KYC + AML", "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_id": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_label": "Standard KYC", "workflow_type": "kyc", "is_default": true, "is_archived": false, "is_white_label_enabled": false, "total_price": 0.15, "min_price": 0.15, "max_price": 0.15, "features": "OCR + LIVENESS + FACE_MATCH", "is_simple_workflow": true, "is_editable": false, "workflow_url": "https://verify.didit.me/u/_yljPOx8RWG3UAz5ZRQGVQ", "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 2, "status": "published", "has_draft": false, "created_by": { "name": "Alex Mateo", "email": "alex@example.com", "type": "user" }, "updated_at": "2026-04-12T10:30:00Z" }, { "uuid": "b2c3d4e5-6789-01bc-defa-222222222222", "workflow_id": "b2c3d4e5-6789-01bc-defa-222222222222", "workflow_label": "Full Verification + AML", "workflow_type": "kyc", "is_default": false, "is_archived": false, "is_white_label_enabled": false, "total_price": 0.25, "min_price": 0.25, "max_price": 0.25, "features": "OCR + LIVENESS + FACE_MATCH + AML", "is_simple_workflow": true, "is_editable": true, "workflow_url": "https://verify.didit.me/u/Aq3kPOx8RWG3UAz5ZRQGVQ", "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 1, "status": "draft", "has_draft": true, "created_by": null, "updated_at": "2026-04-15T18:05:21Z" } ] } } } } } }, "403": { "description": "La chiave API è mancante, malformata, scaduta o appartiene a un'applicazione diversa. Corpo: `{\"detail\": \"You do not have permission to perform this action.\"}`. Aggiorna il token tramite l'[Auth API](/it/auth-api/get-credentials) e riprova.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale e rispetta l'eventuale intestazione `Retry-After`." }, "500": { "description": "Errore imprevisto del server durante la compilazione dell'elenco. È possibile riprovare la richiesta in sicurezza." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/workflows/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Accept: application/json'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.workflows.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.workflows.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Workflows.ListAutoPaging(ctx, didit.WorkflowsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.workflows().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "workflows->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.workflows.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Workflows.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Crea workflow", "description": "Crea un workflow semplice. Invia `features` nell'ordine di esecuzione (si applicano le regole di ordinamento); il valore predefinito è `published` v1. Il corpo accetta SOLO i campi elencati in `SimpleWorkflowRequest`: qualsiasi altra chiave (incluso `workflow_type`) viene rifiutata con un 400. Non idempotente: ogni chiamata crea un nuovo workflow. Massimo 50 workflow per applicazione.", "operationId": "create_workflow", "x-didit-sdk": { "resource": "workflows", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleWorkflowRequest" }, "examples": { "Simple KYC": { "summary": "Workflow lineare di verifica dell'identità, rilevamento della vitalità e confronto facciale", "value": { "workflow_label": "Standard KYC", "features": [ { "feature": "OCR", "config": { "duplicated_user_action": "review" } }, { "feature": "LIVENESS", "config": { "face_liveness_method": "passive" } }, { "feature": "FACE_MATCH", "config": { "face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60 } } ] } }, "KYC + AML": { "summary": "Esegui AML dopo la verifica dell'identità", "value": { "workflow_label": "KYC with AML", "features": [ { "feature": "OCR" }, { "feature": "AML", "config": { "aml_score_review_threshold": 70, "aml_score_approve_threshold": 30 } } ] } }, "Questionnaire workflow": { "summary": "Esegui un questionario creato con POST /v3/questionnaires/", "value": { "workflow_label": "Source of Funds", "features": [ { "feature": "QUESTIONNAIRE", "config": { "questionnaire_uuid": "11111111-2222-3333-4444-555555555555", "review_questionnaire_manually": true } } ] } } } } } }, "responses": { "201": { "description": "Workflow creato. Il corpo della risposta contiene l'INTERA configurazione del workflow — la stessa serializzazione non elaborata di `VerificationSettings` restituita da `GET /v3/workflows/{settings_uuid}/` (~190 campi: ogni toggle di funzionalità, soglia, azione e il `workflow_graph` generato), non l'elemento sintetico dell'elenco. Salva lo `uuid` (esposto anche come `workflow_id`) per poterlo referenziare nelle successive chiamate di creazione della sessione. Nota: `features` è una stringa unita da `\" + \"` e i prezzi sono numeri JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetail" }, "examples": { "Created (abbreviated)": { "summary": "Campi chiave dell'oggetto di configurazione completo", "value": { "uuid": "c3d4e5f6-7890-12cd-ef34-333333333333", "workflow_id": "c3d4e5f6-7890-12cd-ef34-333333333333", "workflow_label": "Standard KYC", "workflow_type": null, "is_default": false, "is_archived": false, "total_price": 0.15, "min_price": 0.15, "max_price": 0.15, "features": "OCR + LIVENESS + FACE_MATCH", "is_simple_workflow": false, "is_editable": false, "workflow_url": "https://verify.didit.me/u/w9TkPOx8RWG3UAz5ZRQGVQ", "workflow_graph": { "start_node": "ocr", "nodes": "... one node per feature plus a final status node ..." }, "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 1, "status": "published", "published_at": "2026-05-17T10:30:00Z", "created_at": "2026-05-17T10:30:00Z", "updated_at": "2026-05-17T10:30:00Z" } } } } } }, "400": { "description": "Errore di validazione. Cause comuni: una chiave di primo livello esterna alla whitelist accettata (ad es. `workflow_type`), un valore `feature` sconosciuto, una funzionalità posizionata prima della relativa dipendenza (ad es. `FACE_MATCH` prima di `OCR`), una funzionalità passiva (`AML`, `IP_ANALYSIS`, `DATABASE_VALIDATION`, `KYB_KEY_PEOPLE`) utilizzata come primo passaggio, una funzionalità `QUESTIONNAIRE` il cui `config.questionnaire_uuid` non esiste per questa applicazione, una funzionalità `SIGNATURE` che andrebbe in produzione senza alcun documento da firmare, una funzionalità `SIGNATURE` con `signature_level: \"aes\"` mentre Advanced (AES) non è disponibile (`aes_not_available`, vedi `signature_availability` sul workflow), oppure una soglia fuori intervallo. Il corpo è un oggetto di errore di validazione DRF — le chiavi sono i nomi dei campi, i valori sono array di messaggi leggibili.", "content": { "application/json": { "examples": { "Advanced (AES) not available": { "value": { "features": { "signature_level": [ "Node 'signature': Advanced (AES) is not available yet (aes_not_available)." ] } } }, "Signature step with no document": { "value": { "features": { "non_field_errors": [ "Node 'signature': Add a document to sign, or let each session bring its own." ] } } }, "Missing feature": { "value": { "features": [ "At least one feature is required." ] } }, "Unknown top-level field": { "value": { "workflow_type": [ "The v3 workflow API only accepts `workflow_label`, `is_default`, `status`, `features`, `is_white_label_enabled`, `is_desktop_allowed`, `max_retry_attempts`, `retry_window_days`, `session_expiration_time`, `face_liveness_max_attempts`, `face_match_max_attempts`." ] } }, "Unknown feature": { "value": { "features": [ "Invalid feature 'FOO'. Allowed values: AGE_ESTIMATION, AML, DATABASE_VALIDATION, EMAIL_VERIFICATION, FACE_MATCH, IP_ANALYSIS, KYB_DOCUMENTS, KYB_KEY_PEOPLE, KYB_REGISTRY, LIVENESS, NFC, OCR, PHONE_VERIFICATION, PROOF_OF_ADDRESS, QUESTIONNAIRE." ] } }, "Ordering": { "value": { "features": [ "Feature 'FACE_MATCH' must appear after one of: OCR." ] } }, "Questionnaire not found": { "value": { "features": "Questionnaire '11111111-2222-3333-4444-555555555555' was not found for this application. Create the questionnaire first, then use its questionnaire_id." } } } } } }, "403": { "description": "La chiave API è mancante, malformata, scaduta o limitata a un'applicazione diversa. Esegui il refresh tramite l'[Auth API](/it/auth-api/get-credentials) e riprova.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "415": { "description": "Tipo di media non supportato. Imposta `Content-Type: application/json` e invia un corpo JSON." }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." }, "500": { "description": "Errore imprevisto del server durante la creazione del workflow. È sicuro effettuare un nuovo tentativo." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/workflows/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"workflow_label\": \"Standard KYC\",\n \"features\": [\n {\"feature\": \"OCR\"},\n {\"feature\": \"LIVENESS\", \"config\": {\"face_liveness_method\": \"passive\"}},\n {\"feature\": \"FACE_MATCH\", \"config\": {\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60}}\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.workflows.create(\n workflow_label=\"Standard KYC\",\n features=[{\n \"feature\": \"OCR\",\n \"config\": {\"duplicated_user_action\": \"review\"},\n }, {\n \"feature\": \"LIVENESS\",\n \"config\": {\"face_liveness_method\": \"passive\"},\n }, {\n \"feature\": \"FACE_MATCH\",\n \"config\": {\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60},\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.workflows.create({\n workflow_label: \"Standard KYC\",\n features: [{\n feature: \"OCR\",\n config: { duplicated_user_action: \"review\" },\n }, {\n feature: \"LIVENESS\",\n config: { face_liveness_method: \"passive\" },\n }, {\n feature: \"FACE_MATCH\",\n config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Create(ctx, didit.SimpleWorkflowRequest{\n\tWorkflowLabel: didit.String(\"Standard KYC\"),\n\tFeatures: []didit.SimpleWorkflowFeature{{\n\t\tFeature: \"OCR\",\n\t\tConfig: didit.Some(map[string]any{\"duplicated_user_action\": \"review\"}),\n\t}, {\n\t\tFeature: \"LIVENESS\",\n\t\tConfig: didit.Some(map[string]any{\"face_liveness_method\": \"passive\"}),\n\t}, {\n\t\tFeature: \"FACE_MATCH\",\n\t\tConfig: didit.Some(map[string]any{\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SimpleWorkflowFeature;\nimport me.didit.types.SimpleWorkflowRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.workflows().create(SimpleWorkflowRequest.builder()\n .workflowLabel(\"Standard KYC\")\n .features(List.of(\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"OCR\"))\n .config(Map.of(\"duplicated_user_action\", \"review\"))\n .build(),\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"LIVENESS\"))\n .config(Map.of(\"face_liveness_method\", \"passive\"))\n .build(),\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"FACE_MATCH\"))\n .config(Map.of(\"face_match_score_decline_threshold\", 40, \"face_match_score_review_threshold\", 60))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "workflows->create([\n 'workflow_label' => 'Standard KYC',\n 'features' => [[\n 'feature' => 'OCR',\n 'config' => ['duplicated_user_action' => 'review'],\n ], [\n 'feature' => 'LIVENESS',\n 'config' => ['face_liveness_method' => 'passive'],\n ], [\n 'feature' => 'FACE_MATCH',\n 'config' => ['face_match_score_decline_threshold' => 40, 'face_match_score_review_threshold' => 60],\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.workflows.create(\n workflow_label: \"Standard KYC\",\n features: [{\n feature: \"OCR\",\n config: { duplicated_user_action: \"review\" },\n }, {\n feature: \"LIVENESS\",\n config: { face_liveness_method: \"passive\" },\n }, {\n feature: \"FACE_MATCH\",\n config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Workflows.CreateAsync(new SimpleWorkflowRequest\n{\n WorkflowLabel = \"Standard KYC\",\n Features = new SimpleWorkflowFeature[]\n {\n new()\n {\n Feature = \"OCR\",\n Config = new Dictionary { [\"duplicated_user_action\"] = \"review\" },\n },\n new()\n {\n Feature = \"LIVENESS\",\n Config = new Dictionary { [\"face_liveness_method\"] = \"passive\" },\n },\n new()\n {\n Feature = \"FACE_MATCH\",\n Config = new Dictionary { [\"face_match_score_decline_threshold\"] = 40, [\"face_match_score_review_threshold\"] = 60 },\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/workflows/{settings_uuid}/": { "get": { "summary": "Recupera workflow", "description": "Recupera la configurazione completa per una versione del workflow tramite `settings_uuid`: attivazione delle funzionalità, soglie, documenti consentiti, grafo, criteri di nuovo tentativo, callback e prezzi.", "operationId": "get_workflow", "x-didit-sdk": { "resource": "workflows", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "settings_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID per versione del workflow (il valore `uuid` restituito dall'endpoint di elenco). Ogni versione di un workflow ha il proprio `settings_uuid`." } ], "responses": { "200": { "description": "Configurazione completa del workflow. Il formato corrisponde alla serializzazione grezza di `VerificationSettings` (~190 campi: ogni interruttore di funzionalità, soglia, azione di avviso, configurazione dei documenti consentiti, il `workflow_graph`, politica di nuovo tentativo, callback e prezzi). L'esempio seguente è abbreviato. Nota: `features` è una stringa unita da `\" + \"` (ad es. `\"OCR + LIVENESS\"`), i prezzi sono numeri JSON e `is_editable` è `true` solo per le versioni `draft`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetail" }, "examples": { "KYC workflow with face match (abbreviated)": { "value": { "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_id": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_label": "Standard KYC", "workflow_type": "kyc", "is_default": true, "is_archived": false, "is_liveness_enabled": true, "face_liveness_method": "passive", "face_liveness_score_decline_threshold": 50, "face_liveness_score_review_threshold": 70, "is_face_match_enabled": true, "face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60, "is_aml_enabled": false, "is_phone_verification_enabled": false, "is_email_verification_enabled": false, "is_database_validation_enabled": false, "is_ip_analysis_enabled": false, "is_nfc_enabled": false, "duplicated_user_action": "no_action", "documents_allowed": { "ESP": { "P": { "sides": 1, "enabled": 1, "subtypes": [ "EPASSPORT", "PASSPORT_GENERIC" ], "preferred_characters": "latin", "expiration_check_mode": "strict" } } }, "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 2, "status": "published", "published_at": "2026-04-12T10:30:00Z", "is_simple_workflow": false, "is_editable": false, "workflow_url": "https://verify.didit.me/u/_yljPOx8RWG3UAz5ZRQGVQ", "total_price": 0.15, "min_price": 0.15, "max_price": 0.15, "features": "OCR + LIVENESS + FACE_MATCH", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2026-04-12T10:30:00Z" } } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun workflow con questo `settings_uuid` esiste per l'applicazione autenticata. L'UUID non è corretto oppure appartiene a un'altra applicazione — Didit non distingue deliberatamente i due casi per evitare di rivelare l'esistenza di record tra applicazioni diverse.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." }, "500": { "description": "Errore imprevisto del server. È sicuro effettuare un nuovo tentativo." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/workflows/a1b2c3d4-5678-90ab-cdef-111111111111/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.workflows.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.workflows.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.workflows().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "workflows->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.workflows.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Workflows.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Aggiorna il workflow", "description": "Aggiorna un workflow. Il versionamento dipende dal campo `status` inviato e dallo stato corrente della versione: (1) nessun `status` su una versione **pubblicata** → la versione pubblicata viene aggiornata direttamente (stesso `uuid`, stessa `version`); (2) nessun `status` su una **bozza** → la bozza viene aggiornata e pubblicata immediatamente; (3) `status: \"published\"` su una versione **pubblicata** → viene creata e restituita una NUOVA versione pubblicata sotto lo stesso `workflow_id` (nuovo `uuid`, `version` + 1), ed eventuali bozze esistenti nel gruppo vengono eliminate; (4) `status: \"draft\"` mantiene la bozza come bozza (salvataggio automatico), ma viene rifiutato con 400 su una versione pubblicata (`\"Cannot revert a published version to draft.\"`). Il corpo accetta la stessa whitelist restrittiva dei campi della creazione: le chiavi sconosciute vengono rifiutate con 400.", "operationId": "update_workflow", "x-didit-sdk": { "resource": "workflows", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "settings_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID per versione del workflow da aggiornare." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleWorkflowUpdateRequest" }, "examples": { "Replace features": { "summary": "Invia l'ordine completo desiderato delle funzionalità", "value": { "features": [ { "feature": "OCR" }, { "feature": "AML" } ] } }, "Rename": { "summary": "Rinomina un workflow", "value": { "workflow_label": "Premium KYC" } }, "Set as default": { "summary": "Rendi questo workflow quello predefinito dell'applicazione", "value": { "is_default": true } }, "Update config": { "summary": "Modifica la configurazione della funzionalità", "value": { "features": [ { "feature": "OCR" }, { "feature": "LIVENESS", "config": { "face_liveness_method": "passive" } } ] } }, "Publish a draft": { "summary": "Pubblica una bozza", "value": { "status": "published" } } } } } }, "responses": { "200": { "description": "Workflow aggiornato. Il corpo contiene la configurazione COMPLETA della versione risultante (stessa struttura raw `VerificationSettings` di `GET /v3/workflows/{settings_uuid}/`). Quando l'aggiornamento ha creato una nuova versione (`status: \"published\"` inviato su una riga pubblicata), gli attributi `uuid` e `version` restituiti differiscono da quelli modificati: usa lo `uuid` restituito per le chiamate successive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetail" } } } }, "400": { "description": "Errore di validazione — chiave di primo livello non presente nell'elenco degli elementi consentiti, funzionalità sconosciuta, ordinamento non valido, soglia fuori intervallo, riferimento a un questionario inesistente, funzionalità `SIGNATURE` che andrebbe in produzione senza alcun documento da firmare, nuova funzionalità `SIGNATURE` con `signature_level: \"aes\"` mentre Advanced (AES) non è disponibile (`aes_not_available`, vedi `signature_availability` sul workflow; un passaggio che memorizza già `aes` lo mantiene), oppure `status: \"draft\"` inviato per una versione pubblicata (`\"Cannot revert a published version to draft.\"`). Il corpo della risposta è un errore di validazione DRF indicizzato per nome campo." }, "403": { "description": "Chiave API mancante o non valida.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun workflow con questo `settings_uuid` esiste per l'applicazione autenticata." }, "415": { "description": "Tipo di media non supportato. Imposta `Content-Type: application/json`." }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." }, "500": { "description": "Errore imprevisto del server. È sicuro effettuare un nuovo tentativo." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH 'https://verification.didit.me/v3/workflows/a1b2c3d4-5678-90ab-cdef-111111111111/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"workflow_label\": \"Premium KYC\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.workflows.update(\n \"11111111-2222-3333-4444-555555555555\",\n features=[{\n \"feature\": \"OCR\",\n }, {\n \"feature\": \"AML\",\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.workflows.update(\"11111111-2222-3333-4444-555555555555\", {\n features: [{\n feature: \"OCR\",\n }, {\n feature: \"AML\",\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SimpleWorkflowUpdateRequest{\n\tFeatures: didit.Some([]didit.SimpleWorkflowFeature{{\n\t\tFeature: \"OCR\",\n\t}, {\n\t\tFeature: \"AML\",\n\t}}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SimpleWorkflowFeature;\nimport me.didit.types.SimpleWorkflowUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.workflows().update(\"11111111-2222-3333-4444-555555555555\", SimpleWorkflowUpdateRequest.builder()\n .features(List.of(\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"OCR\"))\n .build(),\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"AML\"))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "workflows->update('11111111-2222-3333-4444-555555555555', [\n 'features' => [[\n 'feature' => 'OCR',\n ], [\n 'feature' => 'AML',\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.workflows.update(\n \"11111111-2222-3333-4444-555555555555\",\n features: [{\n feature: \"OCR\",\n }, {\n feature: \"AML\",\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Workflows.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new SimpleWorkflowUpdateRequest\n{\n Features = new SimpleWorkflowFeature[]\n {\n new()\n {\n Feature = \"OCR\",\n },\n new()\n {\n Feature = \"AML\",\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Elimina workflow", "description": "Elimina definitivamente una versione del workflow (operazione irreversibile). Le sessioni esistenti mantengono i risultati della verifica, ma il loro riferimento al workflow viene cancellato; le altre versioni nello stesso gruppo `workflow_id` non vengono eliminate.", "operationId": "delete_workflow", "x-didit-sdk": { "resource": "workflows", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "settings_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID per versione del workflow da eliminare." } ], "responses": { "204": { "description": "Workflow eliminato. Il corpo della risposta è vuoto." }, "403": { "description": "Chiave API mancante o non valida.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun workflow con questo `settings_uuid` esiste per l'applicazione autenticata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." }, "500": { "description": "Errore imprevisto del server. È sicuro effettuare un nuovo tentativo." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE 'https://verification.didit.me/v3/workflows/a1b2c3d4-5678-90ab-cdef-111111111111/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.workflows.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.workflows.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Workflows.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.workflows().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "workflows->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.workflows.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Workflows.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/questionnaires/": { "get": { "summary": "Elenca i questionari", "description": "Elenca i tuoi questionari, dal più recente al meno recente, in un contenitore di paginazione limit/offset (`{count, next, previous, results}`, dimensione predefinita della pagina 50). Ogni riga rappresenta una versione; `questionnaire_group_id` è l'ID di gruppo stabile risolto all'ultima versione `published`.", "operationId": "list_questionnaires", "x-didit-sdk": { "resource": "questionnaires", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "Dimensione della pagina (numero di questionari per pagina)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Numero di righe da saltare prima del primo questionario restituito." } ], "responses": { "200": { "description": "Una pagina di questionari ordinati per `created_at` in ordine decrescente, inclusi nella struttura di paginazione. Ciascun elemento in `results` è un `QuestionnaireListItem`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero totale di versioni del questionario per l'applicazione." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina successiva, o `null` nell'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina precedente, o `null` nella prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionnaireListItem" } } } }, "examples": { "One questionnaire": { "summary": "Un semplice questionario bilingue", "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "11111111-2222-3333-4444-555555555555", "title": "KYC Questionnaire", "description": "Additional verification questions", "languages": [ "en", "es" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "created_at": "2026-04-23T09:55:00Z", "updated_at": "2026-04-23T10:00:00Z", "question_types": [ "SHORT_TEXT", "MULTIPLE_CHOICE", "FILE_UPLOAD" ], "workflow_names": [], "questionnaire_group_id": "11111111-2222-3333-4444-555555555555", "version": 1, "status": "published", "published_at": "2026-04-23T10:00:00Z", "is_editable": false } ] } } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." }, "500": { "description": "Errore imprevisto del server durante la compilazione dell'elenco. È sicuro effettuare un nuovo tentativo." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/questionnaires/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.questionnaires.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.questionnaires.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Questionnaires.ListAutoPaging(ctx, didit.QuestionnairesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.questionnaires().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "questionnaires->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.questionnaires.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Questionnaires.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Crea questionario", "description": "Crea un questionario lineare semplice. Invia `form_elements` nell'ordine di visualizzazione; le diramazioni e i gruppi ripetibili richiedono la Console. Il valore predefinito è `published` v1.", "operationId": "create_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleQuestionnaireRequest" }, "examples": { "Simple": { "summary": "Questionario di base", "value": { "title": "Customer Onboarding", "description": "Additional information needed for verification", "default_language": "en", "languages": [ "en" ], "is_active": true, "form_elements": [ { "id": "occupation", "element_type": "short_text", "label": { "en": "What is your occupation?" }, "is_required": true, "placeholder": { "en": "Software engineer" } }, { "id": "source_of_funds", "element_type": "multiple_choice", "label": { "en": "Source of funds" }, "is_required": true, "options": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } }, { "value": "investments", "label": { "en": "Investments" } }, { "value": "other", "label": { "en": "Other" } } ] } ] } } } } } }, "responses": { "201": { "description": "Questionario creato. La risposta include il `questionnaire_id` — memorizzalo per fare riferimento a questo questionario dai workflow o dalle future chiamate di aggiornamento/eliminazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireDetail" }, "examples": { "Created": { "value": { "questionnaire_id": "11111111-2222-3333-4444-555555555555", "title": "Customer Onboarding", "description": "Additional information needed for verification", "languages": [ "en" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "graph": { "start_node": "occupation", "nodes": { "occupation": { "element_type": "SHORT_TEXT", "is_required": true, "title": { "en": "What is your occupation?" }, "next": "source_of_funds" }, "source_of_funds": { "element_type": "MULTIPLE_CHOICE", "is_required": true, "title": { "en": "Source of funds" }, "choices": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } } ], "next": null } } }, "sections": [], "questionnaire_group_id": "11111111-2222-3333-4444-555555555555", "version": 1, "status": "published", "published_at": "2026-04-23T10:00:00Z", "is_editable": false } } } } } }, "400": { "description": "Errore di validazione. Cause comuni: un `element_type` sconosciuto, un campo traducibile privo di traduzione per una delle lingue in `languages`, `languages` privo di `en`, `default_language` non presente in `languages`, un'opzione priva di `label`, una domanda che contiene `branches`/`required_if`/`repeatable_config` (non supportati da questo endpoint), o l'invio di un `graph` grezzo invece di `form_elements`. Il corpo è un errore di validazione DRF indicizzato per nome di campo.", "content": { "application/json": { "examples": { "Graph not accepted": { "value": { "graph": "The v3 questionnaire API only accepts simple `form_elements`, not `graph`." } }, "Missing label": { "value": { "form_elements": [ { "label": [ "This field is required." ] } ] } } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "415": { "description": "Tipo di media non supportato. Imposta `Content-Type: application/json` e invia un corpo JSON." }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." }, "500": { "description": "Errore imprevisto del server durante la creazione del questionario. È sicuro effettuare un nuovo tentativo." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/questionnaires/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"title\": \"Customer Onboarding\",\n \"default_language\": \"en\",\n \"languages\": [\"en\"],\n \"form_elements\": [\n {\n \"id\": \"occupation\",\n \"element_type\": \"short_text\",\n \"label\": {\"en\": \"What is your occupation?\"},\n \"is_required\": true\n }\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.questionnaires.create(\n title=\"Customer Onboarding\",\n description=\"Additional information needed for verification\",\n languages=[\"en\"],\n default_language=\"en\",\n is_active=True,\n form_elements=[{\n \"id\": \"occupation\",\n \"element_type\": \"short_text\",\n \"label\": {\"en\": \"What is your occupation?\"},\n \"placeholder\": {\"en\": \"Software engineer\"},\n \"is_required\": True,\n }, {\n \"id\": \"source_of_funds\",\n \"element_type\": \"multiple_choice\",\n \"label\": {\"en\": \"Source of funds\"},\n \"is_required\": True,\n \"options\": [{\n \"value\": \"employment\",\n \"label\": {\"en\": \"Employment\"},\n }, {\n \"value\": \"business\",\n \"label\": {\"en\": \"Business\"},\n }, {\n \"value\": \"investments\",\n \"label\": {\"en\": \"Investments\"},\n }, {\n \"value\": \"other\",\n \"label\": {\"en\": \"Other\"},\n }],\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.questionnaires.create({\n title: \"Customer Onboarding\",\n description: \"Additional information needed for verification\",\n languages: [\"en\"],\n default_language: \"en\",\n is_active: true,\n form_elements: [{\n id: \"occupation\",\n element_type: \"short_text\",\n label: { en: \"What is your occupation?\" },\n placeholder: { en: \"Software engineer\" },\n is_required: true,\n }, {\n id: \"source_of_funds\",\n element_type: \"multiple_choice\",\n label: { en: \"Source of funds\" },\n is_required: true,\n options: [{\n value: \"employment\",\n label: { en: \"Employment\" },\n }, {\n value: \"business\",\n label: { en: \"Business\" },\n }, {\n value: \"investments\",\n label: { en: \"Investments\" },\n }, {\n value: \"other\",\n label: { en: \"Other\" },\n }],\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Questionnaires.Create(ctx, didit.SimpleQuestionnaireRequest{\n\tTitle: \"Customer Onboarding\",\n\tDescription: didit.String(\"Additional information needed for verification\"),\n\tLanguages: []string{\"en\"},\n\tDefaultLanguage: didit.String(\"en\"),\n\tIsActive: didit.Bool(true),\n\tFormElements: []didit.SimpleQuestionnaireElement{{\n\t\tID: didit.String(\"occupation\"),\n\t\tElementType: \"short_text\",\n\t\tLabel: map[string]string{\"en\": \"What is your occupation?\"},\n\t\tPlaceholder: didit.Some(map[string]string{\"en\": \"Software engineer\"}),\n\t\tIsRequired: didit.Bool(true),\n\t}, {\n\t\tID: didit.String(\"source_of_funds\"),\n\t\tElementType: \"multiple_choice\",\n\t\tLabel: map[string]string{\"en\": \"Source of funds\"},\n\t\tIsRequired: didit.Bool(true),\n\t\tOptions: didit.Some([]didit.SimpleQuestionnaireElementOptions{{\n\t\t\tValue: didit.String(\"employment\"),\n\t\t\tLabel: map[string]string{\"en\": \"Employment\"},\n\t\t}, {\n\t\t\tValue: didit.String(\"business\"),\n\t\t\tLabel: map[string]string{\"en\": \"Business\"},\n\t\t}, {\n\t\t\tValue: didit.String(\"investments\"),\n\t\t\tLabel: map[string]string{\"en\": \"Investments\"},\n\t\t}, {\n\t\t\tValue: didit.String(\"other\"),\n\t\t\tLabel: map[string]string{\"en\": \"Other\"},\n\t\t}}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SimpleQuestionnaireElement;\nimport me.didit.types.SimpleQuestionnaireRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.questionnaires().create(SimpleQuestionnaireRequest.builder()\n .title(\"Customer Onboarding\")\n .description(\"Additional information needed for verification\")\n .languages(List.of(\"en\"))\n .defaultLanguage(\"en\")\n .isActive(true)\n .formElements(List.of(\n SimpleQuestionnaireElement.builder()\n .id(\"occupation\")\n .elementType(SimpleQuestionnaireElement.ElementType.of(\"short_text\"))\n .label(Map.of(\"en\", \"What is your occupation?\"))\n .placeholder(Map.of(\"en\", \"Software engineer\"))\n .isRequired(true)\n .build(),\n SimpleQuestionnaireElement.builder()\n .id(\"source_of_funds\")\n .elementType(SimpleQuestionnaireElement.ElementType.of(\"multiple_choice\"))\n .label(Map.of(\"en\", \"Source of funds\"))\n .isRequired(true)\n .options(List.of(\n SimpleQuestionnaireElement.Options.builder()\n .value(\"employment\")\n .label(Map.of(\"en\", \"Employment\"))\n .build(),\n SimpleQuestionnaireElement.Options.builder()\n .value(\"business\")\n .label(Map.of(\"en\", \"Business\"))\n .build(),\n SimpleQuestionnaireElement.Options.builder()\n .value(\"investments\")\n .label(Map.of(\"en\", \"Investments\"))\n .build(),\n SimpleQuestionnaireElement.Options.builder()\n .value(\"other\")\n .label(Map.of(\"en\", \"Other\"))\n .build()))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "questionnaires->create([\n 'title' => 'Customer Onboarding',\n 'description' => 'Additional information needed for verification',\n 'languages' => ['en'],\n 'default_language' => 'en',\n 'is_active' => true,\n 'form_elements' => [[\n 'id' => 'occupation',\n 'element_type' => 'short_text',\n 'label' => ['en' => 'What is your occupation?'],\n 'placeholder' => ['en' => 'Software engineer'],\n 'is_required' => true,\n ], [\n 'id' => 'source_of_funds',\n 'element_type' => 'multiple_choice',\n 'label' => ['en' => 'Source of funds'],\n 'is_required' => true,\n 'options' => [[\n 'value' => 'employment',\n 'label' => ['en' => 'Employment'],\n ], [\n 'value' => 'business',\n 'label' => ['en' => 'Business'],\n ], [\n 'value' => 'investments',\n 'label' => ['en' => 'Investments'],\n ], [\n 'value' => 'other',\n 'label' => ['en' => 'Other'],\n ]],\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.questionnaires.create(\n title: \"Customer Onboarding\",\n description: \"Additional information needed for verification\",\n languages: [\"en\"],\n default_language: \"en\",\n is_active: true,\n form_elements: [{\n id: \"occupation\",\n element_type: \"short_text\",\n label: { en: \"What is your occupation?\" },\n placeholder: { en: \"Software engineer\" },\n is_required: true,\n }, {\n id: \"source_of_funds\",\n element_type: \"multiple_choice\",\n label: { en: \"Source of funds\" },\n is_required: true,\n options: [{\n value: \"employment\",\n label: { en: \"Employment\" },\n }, {\n value: \"business\",\n label: { en: \"Business\" },\n }, {\n value: \"investments\",\n label: { en: \"Investments\" },\n }, {\n value: \"other\",\n label: { en: \"Other\" },\n }],\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Questionnaires.CreateAsync(new SimpleQuestionnaireRequest\n{\n Title = \"Customer Onboarding\",\n Description = \"Additional information needed for verification\",\n Languages = new string[] { \"en\" },\n DefaultLanguage = \"en\",\n IsActive = true,\n FormElements = new SimpleQuestionnaireElement[]\n {\n new()\n {\n Id = \"occupation\",\n ElementType = \"short_text\",\n Label = new Dictionary { [\"en\"] = \"What is your occupation?\" },\n Placeholder = new Dictionary { [\"en\"] = \"Software engineer\" },\n IsRequired = true,\n },\n new()\n {\n Id = \"source_of_funds\",\n ElementType = \"multiple_choice\",\n Label = new Dictionary { [\"en\"] = \"Source of funds\" },\n IsRequired = true,\n Options = new SimpleQuestionnaireElementOptions[]\n {\n new()\n {\n Value = \"employment\",\n Label = new Dictionary { [\"en\"] = \"Employment\" },\n },\n new()\n {\n Value = \"business\",\n Label = new Dictionary { [\"en\"] = \"Business\" },\n },\n new()\n {\n Value = \"investments\",\n Label = new Dictionary { [\"en\"] = \"Investments\" },\n },\n new()\n {\n Value = \"other\",\n Label = new Dictionary { [\"en\"] = \"Other\" },\n },\n },\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/questionnaires/{questionnaire_uuid}/": { "get": { "summary": "Recupera questionario", "description": "Recupera i dettagli completi del questionario per una versione tramite `questionnaire_uuid`: titolo, `languages`, `graph` canonico, `sections` derivate e metadati della versione.", "operationId": "get_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "questionnaire_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID per versione del questionario (il valore `uuid` restituito dall'endpoint di elenco, restituito anche come `questionnaire_id` sugli endpoint di dettaglio)." } ], "responses": { "200": { "description": "Dettaglio completo del questionario, inclusi il `graph` canonico, la vista derivata `sections`, i metadati di versione e `is_editable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireDetail" }, "examples": { "Published questionnaire": { "value": { "questionnaire_id": "11111111-2222-3333-4444-555555555555", "title": "Customer Onboarding", "description": "Additional information needed for verification", "languages": [ "en" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "graph": { "start_node": "occupation", "nodes": { "occupation": { "element_type": "SHORT_TEXT", "is_required": true, "title": { "en": "What is your occupation?" }, "next": "source_of_funds" }, "source_of_funds": { "element_type": "MULTIPLE_CHOICE", "is_required": true, "title": { "en": "Source of funds" }, "choices": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } } ], "next": null } } }, "sections": [ { "title": {}, "description": {}, "items": [ { "uuid": "11111111-2222-3333-4444-666666666666", "value": "occupation", "element_type": "SHORT_TEXT", "is_required": true, "title": { "en": "What is your occupation?" } } ] } ], "questionnaire_group_id": "11111111-2222-3333-4444-555555555555", "version": 1, "status": "published", "published_at": "2026-04-23T10:00:00Z", "is_editable": false } } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun questionario con questo `questionnaire_uuid` esiste per l'applicazione autenticata. L'UUID non è corretto oppure appartiene a un'altra applicazione — l'API non distingue deliberatamente i due casi.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." }, "500": { "description": "Errore imprevisto del server. È sicuro effettuare un nuovo tentativo." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/questionnaires/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.questionnaires.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.questionnaires.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Questionnaires.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.questionnaires().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "questionnaires->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.questionnaires.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Questionnaires.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Aggiorna il questionario", "description": "Aggiorna un questionario. Il controllo delle versioni dipende dal campo `status` inviato e dallo stato corrente della versione: (1) nessun `status` su una versione **pubblicata** → la versione pubblicata viene aggiornata direttamente (stesso `questionnaire_id`, stessa `version`); (2) nessun `status` su una **bozza** → la bozza viene aggiornata e pubblicata immediatamente; (3) `status: \"published\"` su una versione **pubblicata** → viene creata e restituita una NUOVA versione pubblicata all'interno dello stesso `questionnaire_group_id` (nuovo `questionnaire_id`, `version` + 1), ed eventuali bozze esistenti nel gruppo vengono eliminate; (4) `status: \"draft\"` mantiene la bozza come bozza (salvataggio automatico), ma viene rifiutato con 400 su una versione pubblicata (`\"Cannot revert a published version to draft.\"`).", "operationId": "update_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "questionnaire_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID per versione del questionario da aggiornare." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleQuestionnaireUpdateRequest" }, "examples": { "Rename": { "summary": "Rinomina un questionario", "value": { "title": "Updated Customer Onboarding" } }, "Replace questions": { "summary": "Sostituisci l'intero elenco lineare di domande", "value": { "form_elements": [ { "id": "occupation", "element_type": "short_text", "label": { "en": "What is your occupation?" }, "is_required": true }, { "id": "source_of_funds", "element_type": "multiple_choice", "label": { "en": "Source of funds" }, "options": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } } ] } ] } } } } } }, "responses": { "200": { "description": "Questionario aggiornato. Il corpo è lo stato più recente della versione risultante — la versione aggiornata sul posto, o la versione pubblicata appena creata quando hai inviato `status: \"published\"` su una riga pubblicata (in quel caso `questionnaire_id` e `version` differiscono da quelli modificati). `questionnaire_id` nella risposta è l'UUID per versione; usa `questionnaire_group_id` se hai bisogno dell'identificatore di gruppo stabile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireDetail" } } } }, "400": { "description": "Errore di validazione — `element_type` sconosciuto, traduzione mancante, campi condizionali/di diramazione non supportati, `languages` privo di `en`, `default_language` non presente in `languages`, opzione senza etichetta, invio di un `graph` grezzo, oppure `status: \"draft\"` su una versione pubblicata (`\"Cannot revert a published version to draft.\"`). Il corpo della risposta è un errore di validazione DRF indicizzato per nome di campo." }, "403": { "description": "Chiave API mancante o non valida.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun questionario con questo `questionnaire_uuid` esiste per l'applicazione autenticata." }, "415": { "description": "Tipo di media non supportato. Imposta `Content-Type: application/json`." }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." }, "500": { "description": "Errore imprevisto del server. È sicuro effettuare un nuovo tentativo." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH 'https://verification.didit.me/v3/questionnaires/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Updated Customer Onboarding\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.questionnaires.update(\n \"11111111-2222-3333-4444-555555555555\",\n title=\"Updated Customer Onboarding\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.questionnaires.update(\"11111111-2222-3333-4444-555555555555\", {\n title: \"Updated Customer Onboarding\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Questionnaires.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SimpleQuestionnaireUpdateRequest{\n\tTitle: didit.String(\"Updated Customer Onboarding\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SimpleQuestionnaireUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.questionnaires().update(\"11111111-2222-3333-4444-555555555555\", SimpleQuestionnaireUpdateRequest.builder()\n .title(\"Updated Customer Onboarding\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "questionnaires->update('11111111-2222-3333-4444-555555555555', [\n 'title' => 'Updated Customer Onboarding',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.questionnaires.update(\n \"11111111-2222-3333-4444-555555555555\",\n title: \"Updated Customer Onboarding\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Questionnaires.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new SimpleQuestionnaireUpdateRequest\n{\n Title = \"Updated Customer Onboarding\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Elimina questionario", "description": "Elimina definitivamente una versione del questionario (operazione irreversibile). Le risposte al questionario memorizzate e collegate a questa versione vengono eliminate insieme ad essa, e le sessioni che vi fanno riferimento perdono il collegamento; le altre versioni nello stesso gruppo non vengono eliminate. I workflow che vi facevano riferimento continuano a funzionare, ma il passaggio del questionario non può più caricarla.", "operationId": "delete_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "questionnaire_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID per versione del questionario da eliminare." } ], "responses": { "204": { "description": "Questionario eliminato. Il corpo della risposta è vuoto." }, "403": { "description": "Chiave API mancante o non valida.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun questionario con questo `questionnaire_uuid` esiste per l'applicazione autenticata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." }, "500": { "description": "Errore imprevisto del server. È sicuro effettuare un nuovo tentativo." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE 'https://verification.didit.me/v3/questionnaires/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.questionnaires.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.questionnaires.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Questionnaires.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.questionnaires().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "questionnaires->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.questionnaires.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Questionnaires.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/users/": { "get": { "summary": "Elenca gli utenti", "description": "Elenca gli [utenti](/entities/users) aggregati da Didit a partire dalle sessioni KYC che condividono lo stesso `vendor_data` (stringa a formato libero, NON un UUID), oltre agli utenti creati tramite API. Paginato, ordinato per `last_session_at` decrescente. Questo endpoint non supporta parametri di filtro o ricerca: recupera le pagine e applica i filtri sul client.", "operationId": "list_users", "x-didit-sdk": { "resource": "users", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Dimensione della pagina. Se omessa, il valore predefinito è 50. Non esiste un massimo imposto, ma mantieni le pagine piccole per ridurre la latenza." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Offset in base zero del primo record da restituire. È preferibile seguire l'URL `next` della pagina precedente invece di calcolarlo manualmente." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/users/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.users.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.users.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Users.ListAutoPaging(ctx, didit.UsersListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.users().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "users->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.users.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Users.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Elenco impaginato degli utenti con stato di verifica, conteggio delle sessioni e riepilogo delle funzionalità.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero di righe corrispondenti: esatto fino a 100, con limite massimo di 100 oltre tale soglia per motivi di prestazioni. Non utilizzarlo per rilevare l'ultima pagina; fai invece affidamento sul fatto che `next` sia `null`." }, "next": { "type": "string", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/UserListItem" } } } }, "examples": { "Example": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Michael Doe", "date_of_birth": "1990-05-15", "effective_name": "John Michael Doe", "status": "ACTIVE", "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2025-06-01T08:00:00Z" }, { "didit_internal_id": "6ed99d53-e8f5-4cf8-9ac1-4a506cb40f6b", "vendor_data": null, "display_name": "Jane S.", "full_name": "Jane Elizabeth Smith", "date_of_birth": "1985-11-22", "effective_name": "Jane S.", "status": "FLAGGED", "portrait_image_url": null, "session_count": 1, "approved_count": 0, "declined_count": 0, "in_review_count": 1, "issuing_states": [], "approved_emails": [], "approved_phones": [], "features": { "ID_VERIFICATION": "In Review" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "In Review" } ], "last_session_at": "2025-06-20T14:00:00Z", "last_activity_at": "2025-06-20T14:05:00Z", "first_session_at": "2025-06-20T14:00:00Z", "tags": [], "created_at": "2025-06-20T14:00:00Z" } ] } } } } } }, "401": { "description": "Nessuna credenziale fornita. Le richieste ai percorsi `/v3/users/*` senza un'intestazione `x-api-key` (o token `Authorization: Bearer`) vengono rifiutate dal middleware di autenticazione prima di raggiungere l'API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "La chiave non può elencare gli utenti per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/users/{vendor_data}/": { "get": { "summary": "Recupera utente", "description": "Recupera un [utente](/entities/users) in base a `vendor_data` (corrispondenza esatta). Aggiunge `metadata`, `comments` e `updated_at` alla visualizzazione a elenco e imposta `tags` sulla struttura dettagliata dei collegamenti ai tag.", "operationId": "get_user", "x-didit-sdk": { "resource": "users", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il tuo identificatore univoco per l'utente: una stringa a formato libero (NON un UUID). È lo stesso valore che hai passato come `vendor_data` durante la creazione della sessione che ha introdotto per la prima volta questo utente, confrontato esattamente come inviato.", "example": "user-abc-123" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/users/user-abc-123/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.retrieve(\n \"user-abc-123\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.retrieve(\"user-abc-123\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Retrieve(ctx, \"user-abc-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().retrieve(\"user-abc-123\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->retrieve('user-abc-123');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.retrieve(\"user-abc-123\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.RetrieveAsync(\"user-abc-123\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Dettaglio completo dell'utente inclusi metadati, commenti/registro delle attività e dati aggregati della sessione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetailItem" }, "examples": { "Active user": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Michael Doe", "date_of_birth": "1990-05-15", "effective_name": "John Michael Doe", "status": "ACTIVE", "metadata": { "tier": "premium", "source": "website" }, "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "tag": { "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "VIP", "color": "#2567FF", "description": null, "source": "custom", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-05-01T09:00:00Z" }, "added_by_email": "analyst@acme.com", "added_by_name": "Jane Analyst", "created_at": "2025-06-02T11:00:00Z" } ], "comments": [ { "uuid": "c1111111-2222-4333-8444-555555555555", "comment_type": "STATUS_CHANGED", "comment": null, "actor_email": "analyst@acme.com", "actor_name": "Jane Analyst", "previous_status": "FLAGGED", "new_status": "ACTIVE", "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "mentioned_emails": [], "created_at": "2025-06-01T10:30:00Z" } ], "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-15T10:30:00Z" } } } } } }, "401": { "description": "Nessuna credenziale fornita. Le richieste ai percorsi `/v3/users/*` senza un'intestazione `x-api-key` (o token `Authorization: Bearer`) vengono rifiutate dal middleware di autenticazione prima di raggiungere l'API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "Chiave API non valida o revocata, oppure la chiave non può leggere gli utenti di questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun utente con il `vendor_data` fornito esiste per questa applicazione.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna l'utente", "description": "Aggiornamento parziale di un utente: `display_name`, `full_name`, `date_of_birth`, `status`, `metadata`, `approved_emails`/`approved_phones`/`issuing_states`. `metadata` sostituisce completamente. Modificare `status` qui funziona come [Aggiorna stato utente](#patch-/v3/users/-vendor_data-/update-status/): registra un'attività `STATUS_CHANGED` con il `reason` facoltativo, e `BLOCKED` aggiunge `vendor_data` alla blocklist di sistema (uscire da `BLOCKED` rimuove tale voce). Le modifiche a `display_name`, `full_name`, `date_of_birth` o `metadata` vengono registrate come attività `PROFILE_UPDATED`.", "operationId": "update_user", "x-didit-sdk": { "resource": "users", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il tuo identificatore univoco per l'utente (stringa a formato libero, NON un UUID).", "example": "user-abc-123" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"display_name\": \"Jane S.\", \"status\": \"FLAGGED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.update(\n \"user-abc-123\",\n display_name=\"Jane S.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.update(\"user-abc-123\", {\n display_name: \"Jane S.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Update(ctx, \"user-abc-123\", didit.UsersUpdateParams{\n\tDisplayName: didit.String(\"Jane S.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.UsersUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().update(\"user-abc-123\", UsersUpdateParams.builder()\n .displayName(\"Jane S.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->update('user-abc-123', [\n 'display_name' => 'Jane S.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.update(\n \"user-abc-123\",\n display_name: \"Jane S.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.UpdateAsync(\"user-abc-123\", new UsersUpdateParams\n{\n DisplayName = \"Jane S.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Utente aggiornato. Viene restituito il record utente aggiornato completo (stessa struttura di Get User).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetailItem" }, "examples": { "Updated": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": "Jane S.", "full_name": "Jane Elizabeth Smith", "date_of_birth": "1985-11-22", "effective_name": "Jane S.", "status": "FLAGGED", "metadata": { "tier": "premium" }, "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "tag": { "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "VIP", "color": "#2567FF", "description": null, "source": "custom", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-05-01T09:00:00Z" }, "added_by_email": "analyst@acme.com", "added_by_name": "Jane Analyst", "created_at": "2025-06-02T11:00:00Z" } ], "comments": [], "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-15T10:30:00Z" } } } } } }, "400": { "description": "Corpo non valido — in genere uno `status` sconosciuto o una `date_of_birth` non nel formato `YYYY-MM-DD`.", "content": { "application/json": { "examples": { "Bad status": { "value": { "status": [ "\"INVALID\" is not a valid choice." ] } }, "Bad date_of_birth": { "value": { "date_of_birth": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "401": { "description": "Nessuna credenziale fornita. Le richieste ai percorsi `/v3/users/*` senza un'intestazione `x-api-key` (o token `Authorization: Bearer`) vengono rifiutate dal middleware di autenticazione prima di raggiungere l'API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "La chiave non può aggiornare gli utenti per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun utente con il `vendor_data` fornito esiste per questa applicazione.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "full_name": { "type": "string", "nullable": true, "maxLength": 512, "description": "Nome completo dell'utente" }, "display_name": { "type": "string", "nullable": true, "description": "Nome visualizzato personalizzato per questo utente" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data di nascita nel formato YYYY-MM-DD" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Stato del ciclo di vita dell'utente. Una modifica viene registrata come attività `STATUS_CHANGED`, e `BLOCKED` aggiunge il `vendor_data` alla blocklist di sistema (passando a uno stato diverso da `BLOCKED` la voce viene rimossa)." }, "metadata": { "type": "object", "nullable": true, "description": "Oggetto JSON arbitrario da allegare all'utente. **Sostituisce completamente** i metadati esistenti in caso di aggiornamento: esegui l'unione lato client se desideri solo aggiungere chiavi." }, "approved_emails": { "type": "array", "items": { "type": "string" }, "description": "Indirizzi email verificati per questo utente, ad es. `[\"john@example.com\"]`. Sostituisce completamente l'elenco memorizzato." }, "approved_phones": { "type": "array", "items": { "type": "string" }, "description": "Numeri di telefono verificati per questo utente. Sostituisce completamente l'elenco memorizzato." }, "issuing_states": { "type": "array", "items": { "type": "string" }, "description": "Paesi di emissione (ISO 3166-1 alpha-3), ad es. `[\"USA\"]`. Sostituisce completamente l'elenco memorizzato." }, "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Il motivo per cui lo stato è cambiato. Registrato nella voce di cambio di stato dell'attività dell'utente (`comments[].comment` e **Activity** nella Business Console), solo quando lo stato cambia effettivamente. I webhook non lo includono." } } }, "examples": { "Rename": { "summary": "Imposta il nome visualizzato", "value": { "display_name": "Jane S." } }, "Override status": { "summary": "Segnala l'utente per la revisione", "value": { "status": "FLAGGED" } }, "Add metadata": { "summary": "Sostituisci il JSON dei metadati", "value": { "metadata": { "tier": "premium", "risk_level": "low" } } }, "Fix extracted DOB": { "summary": "Campi del profilo estratti corretti", "value": { "full_name": "Jane Elizabeth Smith", "date_of_birth": "1985-11-22" } }, "Flag with reason": { "summary": "Segnala l'utente e registra il motivo", "value": { "status": "FLAGGED", "reason": "Address does not match the billing country" } } } } } } } }, "/v3/users/{vendor_data}/generate-pdf/": { "get": { "summary": "Scarica il report PDF della cronologia utente completa", "description": "Genera e scarica un PDF pronto per la compliance contenente la cronologia completa delle verifiche dell'utente identificato da `vendor_data`. È lo stesso documento prodotto dalla Console da **User detail → Actions → Download PDF**, quindi le esportazioni periodiche per la compliance non richiedono più l'intervento manuale di una persona nella Console.\n\n**Cosa contiene il report.** Un frontespizio con il riepilogo del profilo (nome, data di nascita, stati di emissione, email e telefoni approvati), lo stato più recente di ciascuna funzionalità, i contatori delle sessioni e un indice delle sessioni incluse — seguiti dal report standard di ciascuna sessione inclusa, in ordine cronologico (dalla meno recente alla più recente). Ciascun report di sessione è lo stesso documento restituito da `GET /v3/session/{sessionId}/generate-pdf/` per quella sessione.\n\n**Sessioni idonee.** Sono incluse solo le sessioni di Verifica degli utenti (KYC) in stato `Approved`, `Declined`, `In Review` o `Kyc Expired`; le sessioni in qualsiasi altro stato vengono ignorate. Se l'utente non ha alcuna sessione in uno di questi stati, l'endpoint restituisce `403` — vedi sotto.\n\n**Limite.** Il report è limitato alle **20 sessioni più recenti** rendicontabili. Quando un utente ne ha di più, vengono incluse le 20 più recenti e il frontespizio indica quante sessioni meno recenti sono state escluse. Usa `GET /v3/sessions/?vendor_data=…` per l'elenco completo in formato JSON.\n\n**Branding.** Se la tua applicazione dispone della personalizzazione White label, il frontespizio e il report di ciascuna sessione vengono generati con il tuo logo e l'URL dell'informativa sulla privacy; in caso contrario, riportano il branding di Didit. I report sono generati in inglese — non è presente alcun parametro per la lingua.\n\n**Nessuna memorizzazione nella cache.** Ogni chiamata rigenera il PDF a partire dai dati correnti, quindi un report generato dopo una revisione manuale riflette la decisione del revisore. Due chiamate per lo stesso utente possono produrre file differenti a livello di byte — archivia il file scaricato se necessiti di una copia immutabile.\n\n**Latenza.** La generazione è sincrona e scarica ogni immagine archiviata di ciascuna sessione inclusa, quindi per un utente con molte sessioni ricche di contenuti multimediali possono essere necessarie decine di secondi. Utilizza un timeout di lettura lato client generoso (consigliati 120 s) ed esegui lo streaming del body su disco. La generazione si interrompe al raggiungimento di un limite di tempo lato server invece di continuare fino al timeout del client: se tale limite viene raggiunto, la risposta è comunque un PDF valido contenente le sessioni più recenti, e il frontespizio indica quante sono state omesse.\n\n**Ambito.** L'utente viene risolto all'interno dell'applicazione a cui appartiene la chiave API. Una chiave non può mai esportare un utente di un'altra applicazione — per essa tale utente non esiste e l'endpoint restituisce `404`.\n\n**Barra finale.** Il percorso canonico termina con una barra finale (`…/generate-pdf/`). Una richiesta priva di barra viene gestita direttamente con la stessa risposta — non c'è alcun reindirizzamento `301`, quindi nessun client deve seguire i reindirizzamenti e `curl` non necessita di `-L`. Usa l'URL con la barra finale come negli esempi.", "operationId": "get_user_generate_pdf", "x-didit-sdk": { "resource": "users", "method": "generate_pdf", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il tuo identificatore univoco per l'utente: una stringa a formato libero (NON un UUID). È lo stesso valore che hai passato come `vendor_data` durante la creazione delle sessioni dell'utente, confrontato esattamente come inviato. Codificalo come URL; un valore contenente `/` non può essere indirizzato tramite questo percorso.", "example": "user-abc-123" } ], "responses": { "200": { "description": "Il documento PDF renderizzato, restituito direttamente come binario `application/pdf` — non sono presenti wrapper JSON né reindirizzamenti tramite URL di download. Il corpo inizia con i byte magici `%PDF`. Salvalo in un file `.pdf` o trasmettilo in streaming al tuo chiamante.", "headers": { "Content-Disposition": { "description": "`attachment; filename=user_{didit_internal_id}.pdf` — il file prende il nome dall'identificatore Didit stabile dell'utente (`didit_internal_id` su `GET /v3/users/{vendor_data}/`), non da `vendor_data`.", "schema": { "type": "string", "example": "attachment; filename=user_f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418.pdf" } }, "Content-Length": { "description": "Dimensione totale del PDF in byte; il corpo non è frammentato in blocchi.", "schema": { "type": "integer", "example": 148213 } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Nessuna credenziale fornita. Le richieste ai percorsi `/v3/users/*` senza un'intestazione `x-api-key` (o token `Authorization: Bearer`) vengono rifiutate dal middleware di autenticazione prima di raggiungere l'API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "Errore di autorizzazione o di idoneità. Distingui i due casi tramite la stringa `detail`:\n\n- `\"You do not have permission to perform this action.\"` — la chiave API non è valida o è stata revocata, oppure la richiesta include un token utente della Console anziché una chiave API dell'applicazione.\n- `\"This user has no sessions in review, declined, approved or kyc expired to report.\"` — l'utente esiste nella tua applicazione ma nessuna delle sue sessioni è ancora in uno stato idoneo per la generazione del report (ad esempio ogni sessione è ancora `In Progress`, oppure l'utente è stato creato tramite `POST /v3/users/create/` e non ha mai eseguito la verifica). Attendi un webhook `status.updated` prima di richiedere il report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "This user has no sessions in review, declined, approved or kyc expired to report." } } }, "examples": { "Invalid credentials": { "summary": "Chiave API revocata o non valida, oppure un token utente della Console", "value": { "detail": "You do not have permission to perform this action." } }, "No reportable sessions": { "summary": "L'utente esiste ma non ha una sessione Approved / Declined / In Review / Kyc Expired", "value": { "detail": "This user has no sessions in review, declined, approved or kyc expired to report." } } } } } }, "404": { "description": "Nessun utente con il `vendor_data` fornito esiste nell'applicazione associata alla chiave API. Gli utenti di altre applicazioni sono invisibili a questa chiave e restituiscono lo stesso errore `404`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "User not found." } } }, "examples": { "Unknown user": { "summary": "vendor_data non corrisponde ad alcun utente di questa applicazione", "value": { "detail": "User not found." } } } } } }, "429": { "description": "Limite di frequenza superato. La generazione di PDF ha un limite dedicato di **50 richieste al minuto per credenziale** (chiave API, token Bearer o IP di origine se non autenticato), condiviso tra questo endpoint e `GET /v3/session/{sessionId}/generate-pdf/`, oltre al limite globale di 600 richieste GET al minuto. Attendi i secondi indicati in `Retry-After` (riportati anche nelle intestazioni `X-RateLimit-*`), poi riprova. I report non vengono memorizzati in cache lato server, pertanto scarica ciascun report una sola volta e archivia il file invece di recuperarlo nuovamente.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di riprovare la richiesta.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Numero massimo di generazioni di PDF consentite nella finestra temporale corrente (50).", "schema": { "type": "integer", "example": 50 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Timestamp Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1750000000 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Spiegazione di facile lettura del superamento del limite di frequenza.", "example": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } }, "examples": { "Throttled": { "summary": "Più di 50 generazioni di PDF in un minuto dalla stessa credenziale", "value": { "detail": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --fail \\\n 'https://verification.didit.me/v3/users/user-abc-123/generate-pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output user-history.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.users.generate_pdf(\n \"user-abc-123\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.users.generatePdf(\"user-abc-123\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Users.GeneratePDF(ctx, \"user-abc-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.users().generatePdf(\"user-abc-123\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "users->generatePdf('user-abc-123');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.users.generate_pdf(\"user-abc-123\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Users.GeneratePdfAsync(\"user-abc-123\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/users/delete/": { "post": { "summary": "Elimina utenti in blocco", "description": "**Elimina definitivamente** gli utenti: i record utente vengono rimossi in modo permanente. Per il blocco ordinario preferisci [Aggiorna stato utente](#patch-/v3/users/-vendor_data-/update-status/) con `BLOCKED`. Seleziona gli utenti con `vendor_data_list`, con `didit_internal_id_list` o con entrambi contemporaneamente; oppure passa `delete_all: true`. Questo endpoint non restringe mai `delete_all` con i filtri. I filtri Persone della Console vengono rifiutati con un `400` (vedi la risposta `400`), in modo che un intento più restrittivo non si trasformi in una cancellazione totale. Due eccezioni: `filter_has_approved_sessions` e `filter_has_declined_sessions` non vengono rifiutati e non vengono applicati, quindi con `delete_all: true` eliminano comunque ogni utente; non inviarli.\n\n**Modelli biometrici:** a meno che tu non imposti `retain_face_embeddings` su `true`, ogni modello biometrico privo di immagini conservato per questi utenti dopo l'eliminazione della sessione (vedi `/v3/biometric-templates/`) viene rimosso prima che l'utente venga eliminato, così la persona non viene più riconosciuta come corrispondenza nel rilevamento dei duplicati e nella Ricerca facciale. Con `retain_face_embeddings: true` e `face_retention_days`, scegli di conservare un modello biometrico privo di immagini per persona per quel numero di giorni, e non viene conservato nient'altro sulla persona. Se non è possibile eliminare un modello perché un archivio biometrico non è disponibile, la chiamata restituisce `503`, nessun utente nella richiesta viene eliminato e la ripetizione della richiesta completa l'operazione.\n\n**Report normativi presentati:** se i dati selezionati sono presenti in un report normativo finalizzato, l'intera richiesta viene rifiutata con `409` e non viene eliminato nulla. Il corpo usa `code: in_filed_report` e indica ciascun report con `uuid`, `report_number`, `report_type` e `case_uuid`. Elimina i report, quindi ripeti la richiesta.", "operationId": "batch_delete_users", "x-didit-sdk": { "resource": "users", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Fornisci `vendor_data_list`, `didit_internal_id_list` o `delete_all: true`. Le due liste possono essere combinate e vengono valutate in OR. Quando `delete_all` è `true`, ha la precedenza ed entrambe le liste vengono ignorate.", "properties": { "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "I tuoi identificatori da eliminare, confrontati esattamente come inviati." }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "ID utente interni Didit da eliminare: il `didit_internal_id` restituito dagli endpoint di creazione e recupero." }, "delete_all": { "type": "boolean", "default": false, "description": "Se `true`, elimina ogni utente nell'applicazione." }, "retain_face_embeddings": { "type": "boolean", "default": false, "description": "La tua scelta esplicita di conservare un modello biometrico privo di immagini di ciascuna persona eliminata per il rilevamento di duplicati, per `face_retention_days`. Tutti gli altri dati della persona vengono eliminati. Omettilo o invia `false` per eliminare i modelli insieme agli utenti. Quando è `true`, `face_retention_days` è obbligatorio." }, "face_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Numero di giorni per cui viene conservato il modello biometrico senza immagini quando `retain_face_embeddings` è `true`. Obbligatorio con esso, e rifiutato senza di esso con un errore `400` su `face_retention_days`.", "example": 365 } } }, "examples": { "Specific users": { "summary": "Elimina utenti tramite vendor_data", "value": { "vendor_data_list": [ "user-123", "user-456" ] } }, "By Didit internal ID": { "summary": "Elimina utenti tramite didit_internal_id", "value": { "didit_internal_id_list": [ "3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11" ] } }, "All users": { "summary": "Elimina tutti gli utenti in questa applicazione", "value": { "delete_all": true } }, "Keep face templates": { "summary": "Elimina gli utenti e conserva i modelli facciali anonimi per 365 giorni", "value": { "vendor_data_list": [ "user-123" ], "retain_face_embeddings": true, "face_retention_days": 365 } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/users/delete/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data_list\": [\"user-123\", \"user-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.batch_delete(\n vendor_data_list=[\"user-123\", \"user-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.batchDelete({\n vendor_data_list: [\"user-123\", \"user-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.BatchDelete(ctx, didit.UsersBatchDeleteParams{\n\tVendorDataList: didit.Some([]string{\"user-123\", \"user-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.UsersBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().batchDelete(UsersBatchDeleteParams.builder()\n .vendorDataList(List.of(\"user-123\", \"user-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->batchDelete([\n 'vendor_data_list' => ['user-123', 'user-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.batch_delete(vendor_data_list: [\"user-123\", \"user-456\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.BatchDeleteAsync(new UsersBatchDeleteParams\n{\n VendorDataList = new string[] { \"user-123\", \"user-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Utenti eliminati. Restituisce il numero di utenti effettivamente eliminati.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer", "description": "Numero di utenti eliminati (esclude i valori vendor_data che non corrispondevano a nulla)." } } }, "examples": { "Deleted some": { "value": { "deleted": 2 } }, "Nothing matched": { "value": { "deleted": 0 } } } } } }, "400": { "description": "Errore di validazione; non viene eliminato nulla. Gli errori sono indicizzati per nome di campo. In assenza di un selettore (nessuna delle due liste e `delete_all` non `true`), il corpo è `{\"vendor_data_list\": [\"This field is required unless delete_all is true.\"]}`; una lista vuota viene rifiutata sotto la propria chiave con `\"This list may not be empty.\"`. Un filtro riservato alla Console (`filter_search`, `filter_status`, `filter_country`, `filter_date_from`, `filter_date_to`, `filter_tag`, `filter_latest_verification_status`, `filter_risk`, `filter_has_sessions`, `filter_has_open_alerts`, `filter_aml_monitoring`, `filter_can_sign_in`, `filter_auth_status`, `filter_auth_method` o `filter_auth_mfa_enabled`) viene rifiutato ogni volta che contiene un valore, anche `false`, con un oggetto indicizzato per ciascuno di tali campi. Qualsiasi altra chiave `filter_*` sconosciuta viene rifiutata con `\"Unknown filter.\"`.", "content": { "application/json": { "examples": { "Missing selector": { "summary": "Né list né delete_all forniti", "value": { "vendor_data_list": [ "This field is required unless delete_all is true." ] } }, "Console-only filter": { "value": { "filter_has_sessions": "This filter is Console-only and is not supported by this endpoint." } } } } } }, "401": { "description": "Nessuna credenziale fornita. Le richieste ai percorsi `/v3/users/*` senza un'intestazione `x-api-key` (o token `Authorization: Bearer`) vengono rifiutate dal middleware di autenticazione prima di raggiungere l'API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "Chiave API non valida o revocata, oppure la chiave non può eliminare utenti per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } }, "503": { "description": "Un archivio biometrico non era disponibile durante la conservazione o l'eliminazione definitiva di un modello biometrico. Non è stato eliminato nulla; ripeti la stessa richiesta. I nuovi tentativi sono idempotenti e convergono su un unico modello.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Retryable": { "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } }, "409": { "description": "Non viene eliminato nulla. `code` ne indica il motivo: `in_filed_report` quando la selezione include una persona presente in un report normativo finalizzato, `subject_deletion_in_progress` quando un'altra richiesta sta ancora eliminando una delle persone selezionate. Ripeti la richiesta una volta completata tale eliminazione.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InFiledReportError" }, { "$ref": "#/components/schemas/SubjectDeletionInProgressError" } ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/sessions/delete/": { "post": { "summary": "Elimina sessioni KYC in blocco tramite session_number", "description": "Elimina in blocco le sessioni di Verifica degli utenti (KYC) in base al loro `session_number` numerico, oppure tutte le sessioni KYC nella tua applicazione con `delete_all: true`.\n\n`session_number` è il contatore incrementale di facile lettura mostrato nell'elenco delle sessioni della Console e restituito come `session_number` dagli endpoint di creazione della sessione e di decisione; **non** è l'UUID `session_id`. Per eliminare una sessione tramite UUID, o per eliminare una sessione di Verifica aziendale (KYB), che questo endpoint non gestisce mai, utilizza invece `DELETE /v3/session/{sessionId}/delete/`.\n\n**Fino a 20 sessioni vengono eliminate nella richiesta; un numero superiore viene invece elaborato come job.** Il numero di sessioni corrispondenti determina la modalità di elaborazione, indipendentemente dal fatto che siano selezionate tramite `session_numbers` o con `delete_all`:\n- Fino a 20 sessioni corrispondenti: vengono eliminate prima della risposta, che è `200` con una voce per sessione in `results[]`.\n- Più di 20: la risposta è `202` con un job di eliminazione, e le sessioni vengono eliminate in background. Esegui il polling di `GET /v3/sessions/delete/{job_id}/` finché `status` non è `COMPLETED` o `FAILED`. Un job segnala i conteggi per esito, mai quali sessioni ha eliminato. Un job `delete_all` elimina solo le sessioni create prima della richiesta; le sessioni avviate durante la sua esecuzione non vengono eliminate.\n\nOgni sessione eliminata riceve esattamente lo stesso trattamento dell'endpoint di eliminazione della singola sessione: la sessione, ogni tentativo di verifica in essa contenuto, la sua decisione e i dati estratti, i record delle funzionalità correlate (verifica dell'identità, volto, rilevamento della vitalità, confronto facciale e così via) e tutti i relativi file archiviati vengono eliminati, scompare da ogni endpoint di lettura e gli URL dei file multimediali precedentemente emessi smettono di risolversi. Le consegne dei webhook ancora in coda per una sessione eliminata, e i relativi nuovi tentativi, vengono ignorate; i webhook già consegnati non vengono modificati. Le voci della blocklist **non** vengono rimosse, i crediti già consumati **non** vengono rimborsati e le entità User padre **non** vengono eliminate (utilizza `POST /v3/users/delete/` per quelle); non viene emesso alcun webhook per l'eliminazione. L'eliminazione è permanente e irreversibile.\n\n**Semantica di selezione:**\n- Con `delete_all: true` puoi restringere la selezione con i filtri di `GET /v3/sessions/`, ciascuno preceduto da `filter_` (ad esempio `filter_status`, `filter_workflow_id`, `filter_date_from`). I filtri che accettano più valori in List Sessions (`status`, `workflow_id`, `country`, `region`, `document_type`, `document_name`, `session_type`, `warning`, `organization_name`) accettano una stringa separata da virgole o un array; gli altri accettano un solo valore. Un valore vuoto viene ignorato. I filtri si applicano solo insieme a `delete_all`, e un job di eliminazione applica gli stessi filtri.\n- Una chiave `filter_*` sconosciuta, o un valore di filtro illeggibile, rifiuta l'intera richiesta con `400` prima che venga eliminato qualcosa, garantendo che un filtro digitato male non estenda mai l'eliminazione a tutte le sessioni.\n- Le voci in `session_numbers` che non corrispondono a una sessione KYC attiva nella tua applicazione (numeri sconosciuti, sessioni già eliminate o sessioni di proprietà di un'altra applicazione) vengono **ignorate silenziosamente**: non compaiono in `results` e non vengono conteggiate nel `total` di un job.\n- Gli errori di validazione (una voce non numerica, un elenco vuoto, né `session_numbers` né `delete_all` forniti, o una conservazione dei modelli che l'applicazione non può rispettare) rifiutano l'**intera richiesta** con `400` e non eliminano nulla.\n- Le sessioni vengono eliminate in gruppi. Se un gruppo non può essere eliminato (ad esempio perché un servizio di archiviazione non è disponibile), ogni sessione di quel gruppo viene segnalata come `face_retention_outcome: failed_retryable` e rimane invariata; gli altri gruppi non sono interessati. Ripeti la richiesta per tali sessioni. Un job ritenta automaticamente tale gruppo.\n- Non esiste un limite documentato per la lunghezza dell'elenco; il limite di frequenza di scrittura condiviso (sotto) rappresenta il vincolo pratico.\n\n**Dati biometrici facciali:** i campi opzionali `retain_face_embeddings`, `face_retention_days`, `face_retention_deadline`, `deletion_instruction` e `instruction_id` hanno lo stesso significato che in `DELETE /v3/session/{sessionId}/delete/` e si applicano a ogni sessione corrispondente. Ciascun risultato segnala il proprio `face_retention_outcome`.\n\n**Risposta:** `200 OK` con `results[]` per un massimo di 20 sessioni corrispondenti, oppure `202 Accepted` con un job di eliminazione per un numero superiore. Ogni risultato conferma l'eliminazione tranne `face_retention_outcome: failed_retryable`, che segnala una sessione che NON è stata eliminata e per cui è necessario riprovare. Le versioni precedenti di questo endpoint restituivano `204 No Content`; aggiorna i client che verificano la presenza di `204`.\n\n**Idempotenza:** ripetere la stessa richiesta non elimina altro: i numeri che non corrispondono più a una sessione vengono ignorati.\n\n**`delete_all: true` (distruttivo):** elimina **ogni** sessione KYC rimanente nell'applicazione; `session_numbers` viene ignorato quando impostato. Non è previsto alcun passaggio di conferma né annullamento.\n\n**Autenticazione:** chiave API nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`); questa API non restituisce mai `401`.\n\n**Limite di frequenza:** budget di scrittura condiviso di 300 richieste/min per chiave API su tutti gli endpoint POST/PATCH/DELETE; il superamento restituisce `429`.\n\nQuesto endpoint accetta solo chiavi API. I token Bearer degli utenti della Business Console vengono rifiutati con `403` (a differenza dell'eliminazione di una singola sessione, che accetta entrambi).\n\n**Report normativi inviati:** se i dati selezionati si trovano in un report normativo finalizzato, l'intera richiesta viene rifiutata con `409` e non viene eliminato nulla. Il corpo utilizza `code: in_filed_report` e specifica ciascun report con `uuid`, `report_number`, `report_type` e `case_uuid`. Elimina i report, quindi ripeti la richiesta.", "operationId": "batch_delete_sessions", "x-didit-sdk": { "resource": "sessions", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_numbers": { "type": "array", "description": "Valori numerici `session_number` delle sessioni KYC da eliminare, sotto forma di stringhe di sole cifre (sono accettati e convertiti anche i numeri JSON). Obbligatorio a meno che `delete_all` non sia `true`; un elenco vuoto restituisce `400`. Qualsiasi voce non composta da sole cifre comporta il rifiuto dell'intera richiesta con `400` (a meno che `delete_all` non sia `true`, nel qual caso la validazione viene saltata e le voci ignorate). I numeri che non corrispondono a una sessione attiva nella tua applicazione vengono ignorati senza generare errori.", "items": { "type": "string", "pattern": "^[0-9]+$", "example": "1001" }, "minItems": 1, "example": [ "1001", "1002", "1003" ] }, "delete_all": { "type": "boolean", "description": "Quando è `true`, tutte le sessioni KYC rimanenti nell'applicazione chiamante vengono eliminate e `session_numbers` viene ignorato, a meno che tu non restringa la selezione con le chiavi `filter_*`. Se ci sono più di 20 sessioni corrispondenti, l'operazione viene eseguita come processo di eliminazione (`202`) che copre solo le sessioni create prima della richiesta. Il valore predefinito è `false`. Azione irreversibile; non è previsto alcun passaggio di conferma.", "default": false, "example": false }, "retain_face_embeddings": { "type": "boolean", "nullable": true, "description": "Esegui l'override della `face_retention_policy` dell'applicazione per questa eliminazione. `true` mantiene un modello biometrico facciale privo di immagini associato all'Utente della sessione dopo l'eliminazione della sessione; `false` elimina l'embedding facciale insieme alla sessione; ometti o imposta su `null` per seguire la politica dell'applicazione. Ignorato per le sessioni KYB e per le sessioni senza un embedding facciale.", "example": true }, "face_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Periodo di conservazione limitato, in giorni, per un modello conservato. Obbligatorio quando un modello viene conservato, a meno che l'applicazione non imposti già `face_retention_days`. Il campo `expires_at` del modello corrisponde al valore più anticipato tra questa durata, la finestra generale di conservazione dei dati dell'applicazione e `face_retention_deadline`.", "example": 365 }, "face_retention_deadline": { "type": "string", "format": "date-time", "description": "Scadenza definitiva opzionale per un modello conservato. Deve essere nel futuro.", "example": "2027-08-28T00:00:00Z" }, "deletion_instruction": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ], "default": "operational_session_delete", "description": "La classe di istruzione che stai fornendo. `operational_session_delete` elimina la sessione e conserva un modello solo quando la policy o `retain_face_embeddings` lo prevede. `privacy_erasure` elimina definitivamente ogni modello biometrico conservato e associato all'Utente della sessione prima di eliminarla, non può essere sovrascritta dalla policy dell'applicazione e non può essere combinata con `retain_face_embeddings: true` (`400`).", "example": "operational_session_delete" }, "instruction_id": { "type": "string", "maxLength": 255, "description": "Il tuo riferimento permanente per questa istruzione di eliminazione (ad esempio l'ID di un ticket di cancellazione). Registrato nel registro di audit e su qualsiasi modello conservato. Generato da Didit se omesso.", "example": "dsar-2026-0142" }, "filter_status": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `status` di [List Sessions](/it/sessions-api/list-sessions), con gli stessi valori. Una stringa separata da virgole o un array. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_vendor_data": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `vendor_data` di [List Sessions](/it/sessions-api/list-sessions), con lo stesso valore. Un singolo valore, non un elenco: un array viene unito in un unico testo separato da virgole, quindi più valori non vengono confrontati come alternative. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "string" }, "filter_search": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `search` di [List Sessions](/it/sessions-api/list-sessions), con lo stesso valore. Un singolo valore, non un elenco: un array viene unito in un unico testo separato da virgole, quindi più valori non vengono confrontati come alternative. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "string" }, "filter_workflow_id": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `workflow_id` di [List Sessions](/it/sessions-api/list-sessions), con gli stessi valori. Una stringa separata da virgole o un array. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_date_from": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `date_from` di [Elenca sessioni](/it/sessions-api/list-sessions), con lo stesso valore. Un solo valore, non un elenco: un array viene unito in un unico valore separato da virgole, pertanto più valori vengono rifiutati con `400`. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "string", "format": "date" }, "filter_date_to": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `date_to` di [Elenca sessioni](/it/sessions-api/list-sessions), con lo stesso valore. Un solo valore, non un elenco: un array viene unito in un unico valore separato da virgole, pertanto più valori vengono rifiutati con `400`. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "string", "format": "date" }, "filter_country": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `country` di [Elenca sessioni](/it/sessions-api/list-sessions), con gli stessi valori. Una stringa separata da virgole o un array. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_document_type": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `document_type` di [Elenca sessioni](/it/sessions-api/list-sessions), con gli stessi valori. Una stringa separata da virgole o un array. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_document_name": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `document_name` di [Elenca sessioni](/it/sessions-api/list-sessions), con gli stessi valori. Una stringa separata da virgole o un array. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_region": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `region` di [List Sessions](/it/sessions-api/list-sessions), con gli stessi valori. Una stringa separata da virgole o un array. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_didit_internal_id": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `didit_internal_id` di [Elenca sessioni](/it/sessions-api/list-sessions), con lo stesso valore. Un solo valore, non un elenco: un array viene unito in un unico valore separato da virgole, pertanto più valori vengono rifiutati con `400`. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "string", "format": "uuid" }, "filter_session_type": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `session_type` di [List Sessions](/it/sessions-api/list-sessions), con gli stessi valori. Una stringa separata da virgole o un array. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_api_service": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `api_service` di [Elenca sessioni](/it/sessions-api/list-sessions), con lo stesso valore. Un solo valore, non un elenco: un array viene unito in un unico valore separato da virgole, pertanto più valori vengono rifiutati con `400`. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "string" }, "filter_screened_full_name": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `screened_full_name` di [List Sessions](/it/sessions-api/list-sessions), con lo stesso valore. Un singolo valore, non un elenco: un array viene unito in un unico testo separato da virgole, quindi più valori non vengono confrontati come alternative. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "string" }, "filter_warning": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `warning` di [List Sessions](/it/sessions-api/list-sessions), con gli stessi valori. Una stringa separata da virgole o un array. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_status_initialized_as_in_review": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `status_initialized_as_in_review` di [List Sessions](/it/sessions-api/list-sessions), con gli stessi valori. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "boolean" }, "filter_is_kyc_to_be_reviewed": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `is_kyc_to_be_reviewed` di [Elenca sessioni](/it/sessions-api/list-sessions), con gli stessi valori. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "boolean" }, "filter_euuid": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `euuid` di [Elenca sessioni](/it/sessions-api/list-sessions), con lo stesso valore. Un solo valore, non un elenco: un array viene unito in un unico valore separato da virgole, pertanto più valori vengono rifiutati con `400`. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "type": "string", "format": "uuid" }, "filter_organization_name": { "description": "Limita `delete_all` alle sessioni che corrispondono al filtro `organization_name` di [List Sessions](/it/sessions-api/list-sessions), con gli stessi valori. Una stringa separata da virgole o un array. Con una chiave API può corrispondere solo al nome della tua organizzazione, quindi seleziona tutte le tue sessioni o nessuna. Ignorato senza `delete_all`. Un valore vuoto viene ignorato e non limita la selezione.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "examples": { "Specific sessions": { "summary": "Elimina sessioni specifiche in base al numero", "value": { "session_numbers": [ "1001", "1002", "1003" ] } }, "All sessions": { "summary": "Elimina ogni sessione KYC nell'applicazione", "value": { "delete_all": true } }, "Delete and retain templates": { "summary": "Elimina le sessioni ma conserva i modelli biometrici privi di immagini per 365 giorni", "value": { "session_numbers": [ "1001", "1002" ], "retain_face_embeddings": true, "face_retention_days": 365, "instruction_id": "post-approval-cleanup-2026-08" } }, "Privacy erasure": { "summary": "Elimina le sessioni ed elimina definitivamente ogni modello conservato per i relativi utenti", "value": { "session_numbers": [ "1001" ], "deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142" } }, "Filtered delete_all": { "summary": "Elimina ogni sessione rifiutata di un workflow creata a settembre 2026", "value": { "delete_all": true, "filter_status": [ "Declined" ], "filter_workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "filter_date_from": "2026-09-01", "filter_date_to": "2026-09-30" } } } } } }, "responses": { "200": { "description": "Fino a 20 sessioni corrispondenti sono state elaborate nella richiesta. Un risultato per ogni sessione corrispondente; i numeri che non corrispondono a nulla (sconosciuti o già eliminati) vengono ignorati e non compaiono. Un risultato conferma l'eliminazione tranne quando `face_retention_outcome` è `failed_retryable`: tale sessione NON è stata eliminata e va ritentata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "La sessione eliminata." }, "session_number": { "type": "integer", "nullable": true, "description": "Il numero della sessione eliminata." }, "face_retention_outcome": { "type": "string", "enum": [ "retained_with_user", "deleted", "none", "ineligible_no_vendor_user", "failed_retryable" ], "description": "Cosa è successo ai dati biometrici facciali della sessione. `deleted`: l'embedding facciale è stato eliminato insieme alla sessione (impostazione predefinita). `retained_with_user`: la sessione viene eliminata e un modello biometrico senza immagini rimane associato all'Utente; vedi `biometric_template_uuid`. `none`: la sessione non aveva alcun embedding facciale (ad esempio una sessione KYC di soli documenti senza selfie per il rilevamento della vitalità; le sessioni KYB non vengono mai selezionate da questo endpoint). `ineligible_no_vendor_user`: la conservazione era stata richiesta ma la sessione non ha alcun Utente collegato, quindi l'embedding è stato eliminato con la sessione. `failed_retryable` (solo per l'endpoint batch): non è stato possibile eliminare il gruppo insieme al quale questa sessione è stata eliminata (un servizio di archiviazione, uno store biometrico o un fornitore di monitoraggio non era disponibile); questa sessione è ancora presente, ripeti la richiesta per essa." }, "biometric_template_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del modello biometrico conservato quando `face_retention_outcome` è `retained_with_user`; `null` altrimenti. Gestiscilo tramite `/v3/biometric-templates/{template_uuid}/`." }, "biometric_template_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il modello biometrico conservato viene eliminato, se `face_retention_outcome` è `retained_with_user`; `null` quando nessun modello viene conservato." }, "deleted_child_verifications": { "type": "integer", "description": "Sempre `0` su questo endpoint, che elimina solo le sessioni KYC. L'eliminazione di una sessione di Verifica aziendale (KYB) con `DELETE /v3/session/{sessionId}/delete/` segnala le verifiche create che sono state eliminate insieme ad essa." } } } } } }, "examples": { "Mixed outcomes": { "value": { "results": [ { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1001, "face_retention_outcome": "deleted", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 }, { "session_id": "b8e1d2c3-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "session_number": 1002, "face_retention_outcome": "retained_with_user", "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "biometric_template_expires_at": "2027-10-09T10:15:00Z", "deleted_child_verifications": 0 }, { "session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c", "session_number": 1003, "face_retention_outcome": "ineligible_no_vendor_user", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 }, { "session_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "session_number": 1004, "face_retention_outcome": "failed_retryable", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } ] } } } } } }, "202": { "description": "Più di 20 sessioni corrispondenti. Vengono eliminate in secondo piano; esegui il polling di `GET /v3/sessions/delete/{job_id}/` finché `status` non è `COMPLETED` o `FAILED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDeletionJob" }, "examples": { "Job accepted": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "PENDING", "total": 250, "processed": 0, "outcomes": { "deleted": 0, "none": 0, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": null } } } } } }, "400": { "description": "Errore di validazione — non è stato eliminato nulla. I valori di errore sono array di stringhe di messaggio indicizzati per nome campo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_numbers": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": { "description": "Altre chiavi: una chiave `filter_*` che non è un filtro di List Sessions (`\"Unknown filter.\"`), oppure una chiave `filter_*` il cui valore non può essere letto (indicizzata da tale chiave `filter_*`, con un array di messaggi)." } }, "examples": { "Missing selector": { "summary": "Né session_numbers né delete_all forniti", "value": { "session_numbers": [ "This field is required unless delete_all is true." ] } }, "Empty list": { "summary": "session_numbers è un array vuoto", "value": { "session_numbers": [ "This list may not be empty." ] } }, "Non-numeric entry": { "summary": "session_numbers contiene una stringa non numerica", "value": { "session_numbers": [ "All session_numbers must be numeric." ] } }, "Privacy erasure cannot retain": { "summary": "deletion_instruction privacy_erasure combinato con retain_face_embeddings true", "value": { "retain_face_embeddings": [ "Privacy erasure cannot retain biometric templates." ] } }, "No finite retention duration": { "summary": "Conservazione richiesta senza face_retention_days nella richiesta o nell'applicazione", "value": { "detail": "A finite biometric-template retention duration is required." } }, "Unknown filter": { "summary": "Una chiave filter_* non presente in List Sessions", "value": { "filter_reviewer": "Unknown filter." } }, "Unreadable filter value": { "summary": "Un valore di filtro illeggibile", "value": { "filter_date_from": [ "Enter a valid date." ] } } } } } }, "403": { "description": "Chiave API mancante. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione x-api-key, oppure la chiave non è valida", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza di scrittura condiviso superato (300 richieste POST/PATCH/DELETE al minuto per chiave API). Esamina `Retry-After` e le intestazioni di risposta `X-RateLimit-*` prima di effettuare un nuovo tentativo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Budget di scrittura esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } }, "409": { "description": "Una sessione selezionata fa parte di un report normativo finalizzato. Non viene eliminato nulla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/sessions/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"session_numbers\": [\"1001\", \"1002\", \"1003\"]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.batch_delete(\n session_numbers=[\"1001\", \"1002\", \"1003\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.batchDelete({\n session_numbers: [\"1001\", \"1002\", \"1003\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.BatchDelete(ctx, didit.SessionsBatchDeleteParams{\n\tSessionNumbers: didit.Some([]string{\"1001\", \"1002\", \"1003\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().batchDelete(SessionsBatchDeleteParams.builder()\n .sessionNumbers(List.of(\"1001\", \"1002\", \"1003\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->batchDelete([\n 'session_numbers' => ['1001', '1002', '1003'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.batch_delete(session_numbers: [\"1001\", \"1002\", \"1003\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.BatchDeleteAsync(new SessionsBatchDeleteParams\n{\n SessionNumbers = new string[] { \"1001\", \"1002\", \"1003\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/sessions/delete/{job_id}/": { "get": { "summary": "Recupera un job di eliminazione massiva delle sessioni", "description": "Avanzamento di un'eliminazione massiva di sessioni a cui `POST /v3/sessions/delete/` ha risposto con `202` (più di 20 sessioni corrispondenti, selezionate tramite `session_numbers` o con `delete_all`). Esegui il polling ogni pochi secondi mentre `status` è `PENDING` o `PROCESSING`; interrompi quando è `COMPLETED` o `FAILED`.\n\nIl job riporta quante sessioni hanno avuto ciascun esito e quante ne ha elaborate, mai quali sessioni ha eliminato. Un job `FAILED` riporta il motivo in `error`; le sessioni non ancora raggiunte rimangono invariate, quindi ripeti la richiesta di eliminazione per eliminarle.\n\n**Autenticazione:** chiave API nell'intestazione `x-api-key`. Un job è visibile solo all'applicazione che lo ha creato; qualsiasi altro `job_id` restituisce `404`. Credenziali mancanti o non valide restituiscono `403`; questa API non restituisce mai `401`.", "operationId": "get_session_deletion_job", "x-didit-sdk": { "resource": "sessions", "method": "retrieve_deletion_job", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Il `job_id` restituito con il `202` da `POST /v3/sessions/delete/`." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl 'https://verification.didit.me/v3/sessions/delete/JOB_ID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.retrieve_deletion_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.retrieveDeletionJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.RetrieveDeletionJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().retrieveDeletionJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->retrieveDeletionJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.retrieve_deletion_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.RetrieveDeletionJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDeletionJob" }, "examples": { "Processing": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "PROCESSING", "total": 250, "processed": 100, "outcomes": { "deleted": 82, "none": 18, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": null } }, "Completed": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "COMPLETED", "total": 250, "processed": 250, "outcomes": { "deleted": 204, "none": 44, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 2 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": "2026-10-09T10:16:40Z" } }, "Failed": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "FAILED", "total": 250, "processed": 100, "outcomes": { "deleted": 82, "none": 18, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": "The deletion stopped before it finished. The sessions it had not reached are still in place; repeat the request to delete them.", "created_at": "2026-10-09T10:15:00Z", "completed_at": "2026-10-09T10:15:52Z" } } } } } }, "403": { "description": "Chiave API mancante. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione x-api-key, oppure la chiave non è valida", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Non esiste alcun job di eliminazione con questo `job_id` per l'applicazione chiamante. I job sono visibili solo all'applicazione che li ha creati." } } } }, "/v3/sessions/{session_id}/reviews/": { "get": { "summary": "Elenca revisioni della sessione e registro delle attività", "description": "Restituisce il registro di audit / feed delle attività per una sessione di Verifica degli utenti (KYC), dai più recenti ai meno recenti, in un envelope impaginato (`count` / `next` / `previous` / `results`, 50 voci per pagina per impostazione predefinita).\n\nLe voci del feed vengono registrate da qualsiasi entità che interagisce con la sessione: decisioni manuali prese tramite `PATCH /v3/session/{session_id}/update-status/` (che registra `previous_status` → `new_status`), attività del revisore nella Console (commenti con menzioni `@email`, modifiche ai dati KYC/POA, caricamenti/rimozioni di file, modifiche ai tag, visualizzazioni della pagina di dettaglio), corrispondenze del monitoraggio continuo AML e note aggiunte tramite `POST` su questo stesso percorso. La lettura di questo feed equivale, lato API, al pannello **Activity** nella visualizzazione della sessione della Didit Console.\n\nSolo le sessioni di Verifica degli utenti (KYC) sono indirizzabili qui; gli ID di sessione di Verifica aziendale (KYB) restituiscono `404`.", "operationId": "list_session_reviews", "x-didit-sdk": { "resource": "sessions.reviews", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "UUID della sessione di Verifica degli utenti (KYC). Deve appartenere alla stessa applicazione della chiave API: gli UUID appartenenti ad altre applicazioni, le sessioni eliminate e gli ID di sessione di Verifica aziendale (KYB) restituiscono tutti `404`.", "schema": { "type": "string", "format": "uuid", "example": "8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d" } }, { "name": "limit", "in": "query", "required": false, "description": "Dimensione della pagina. Il valore predefinito è `50`.", "schema": { "type": "integer", "default": 50, "example": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Numero di voci da saltare dall'inizio del feed (ordinato). Il valore predefinito è `0`. Gli URL `next` / `previous` nella risposta contengono i valori corretti per scorrere il feed.", "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "ordering", "in": "query", "required": false, "description": "Ordinamento. Il feed mostra per impostazione predefinita i più recenti per primi (`-created_at`); passa `created_at` per leggerlo dai meno recenti. I valori sconosciuti vengono ignorati senza errori (viene utilizzato l'ordine predefinito); sono accettati anche altri nomi di campo del serializzatore.", "schema": { "type": "string", "default": "-created_at", "example": "created_at" } } ], "responses": { "200": { "description": "Feed delle attività impaginato, per impostazione predefinita in ordine dalla più recente. `count` è il numero totale di voci; `next` / `previous` sono URL di pagina già pronti (`null` agli estremi). Un `count` pari a `0` con `results` vuoto indica che non è stata ancora registrata alcuna attività.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero totale di voci del feed per questa sessione (su tutte le pagine).", "example": 3 }, "next": { "type": "string", "nullable": true, "description": "URL della pagina successiva, o `null` nell'ultima pagina.", "example": null }, "previous": { "type": "string", "nullable": true, "description": "URL della pagina precedente, o `null` nella prima pagina.", "example": null }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewItem" }, "description": "Voci del feed per questa pagina." } } }, "examples": { "DecisionTrail": { "summary": "Approvazione manuale con note aggiunte tramite API", "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "de0561bc-5583-4409-9171-1a31a4c8a5f4", "activity_type": "STATUS_UPDATED", "actor_display": "API Client", "actor_email": null, "actor_type": "API_KEY", "new_status": "Approved", "previous_status": "In Review", "comment": "Document re-checked manually; address matches.", "mentioned_emails": [], "previous_value": { "status": "In Review" }, "new_value": { "status": "Approved" }, "changed_fields": [ "status" ], "metadata": null, "created_at": "2026-06-12T00:19:31.918735Z" }, { "uuid": "35370f58-5098-44ee-8a06-8c9af80b2455", "activity_type": "STATUS_UPDATED", "actor_display": "Unknown", "actor_email": null, "actor_type": "CONSOLE_USER", "new_status": null, "previous_status": null, "comment": "Note without status.", "mentioned_emails": [], "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "created_at": "2026-06-12T00:18:44.504157Z" }, { "uuid": "00338f82-f1c5-4f57-8614-c49bb258af1a", "activity_type": "STATUS_UPDATED", "actor_display": "Unknown", "actor_email": null, "actor_type": "CONSOLE_USER", "new_status": "In Review", "previous_status": null, "comment": "Flagging for manual document re-check.", "mentioned_emails": [], "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "created_at": "2026-06-12T00:18:44.466537Z" } ] } }, "PaginatedFirstPage": { "summary": "Prima pagina con limit=2 — next contiene l'URL successivo", "value": { "count": 4, "next": "https://verification.didit.me/v3/sessions/8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d/reviews/?limit=2&offset=2", "previous": null, "results": [ { "uuid": "de0561bc-5583-4409-9171-1a31a4c8a5f4", "activity_type": "STATUS_UPDATED", "actor_display": "API Client", "actor_email": null, "actor_type": "API_KEY", "new_status": "Approved", "previous_status": "In Review", "comment": "Document re-checked manually; address matches.", "mentioned_emails": [], "previous_value": { "status": "In Review" }, "new_value": { "status": "Approved" }, "changed_fields": [ "status" ], "metadata": null, "created_at": "2026-06-12T00:19:31.918735Z" }, { "uuid": "bd4e6227-bdd2-42b2-a726-1d12f785a457", "activity_type": "STATUS_UPDATED", "actor_display": "Unknown", "actor_email": null, "actor_type": "CONSOLE_USER", "new_status": null, "previous_status": null, "comment": null, "mentioned_emails": [], "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "created_at": "2026-06-12T00:18:44.540238Z" } ] } }, "Empty": { "summary": "Sessione senza ancora alcuna attività registrata", "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "403": { "description": "`x-api-key` mancante, malformata, scaduta o revocata. L'autenticazione viene verificata prima della ricerca della sessione, quindi una chiave mancante restituisce `403` anche quando l'UUID della sessione non esiste.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." } } }, "examples": { "InvalidKey": { "summary": "Intestazione x-api-key mancante o non valida", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessuna sessione di Verifica degli utenti (KYC) con questo UUID è visibile alla tua applicazione: l'UUID non esiste, la sessione è stata eliminata o appartiene a un'altra applicazione. Anche gli ID di sessione di Verifica aziendale (KYB) restituiscono `404` qui — il feed delle revisioni è accessibile solo per le sessioni KYC.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Session not found." } } }, "examples": { "NotFound": { "summary": "UUID della sessione sconosciuto, eliminato o appartenente a un'altra applicazione", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite di frequenza superato. Esamina le intestazioni di risposta `Retry-After` e `X-RateLimit-*`. Consulta [Limiti di frequenza](/it/integration/rate-limiting)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s 'https://verification.didit.me/v3/sessions/8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d/reviews/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.reviews.list(\n \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.reviews.list(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.Reviews.ListAutoPaging(ctx, \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", didit.SessionsReviewsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().reviews().list(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->reviews->list('8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.reviews.list(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.Reviews.ListAsync(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Aggiungi una nota di revisione al registro di audit di una sessione", "description": "Aggiunge una nota al feed di revisione / attività di una sessione di Verifica degli utenti (KYC). **Questo endpoint registra solo una voce: non modifica mai la sessione.** Lo `status` della sessione rimane invariato, non viene eseguita alcuna convalida della transizione di stato e non viene attivato alcun webhook. Per approvare, rifiutare o riaprire effettivamente una sessione (operazione che registra anche una voce `STATUS_UPDATED` con attribuzione completa in questo feed), utilizzare invece `PATCH /v3/session/{session_id}/update-status/`.\n\nEntrambi i campi del corpo sono facoltativi e viene accettato un oggetto JSON vuoto. `new_status` viene memorizzato esclusivamente come etichetta della voce e accetta uno qualsiasi dei dieci valori di stato della sessione (case-sensitive). Le menzioni `@email` all'interno di `comment` vengono memorizzate solo come testo normale: non attivano notifiche su questo endpoint e il campo `mentioned_emails` della voce rimane vuoto.\n\nNota sull'attribuzione: le voci create qui non contengono informazioni sull'autore. Nel feed mostrano `actor_display: \"Unknown\"`, `actor_type: \"CONSOLE_USER\"` e `activity_type: \"STATUS_UPDATED\"` (valori predefiniti di archiviazione), e il campo `user` del corpo della risposta `201` è `\"Unknown\"`.", "operationId": "create_session_review", "x-didit-sdk": { "resource": "sessions.reviews", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": false, "description": "Imposta su `application/json` quando invii un corpo JSON.", "schema": { "type": "string", "example": "application/json" } }, { "name": "session_id", "in": "path", "required": true, "description": "UUID della sessione di Verifica degli utenti (KYC). Deve appartenere alla stessa applicazione della chiave API: gli UUID appartenenti ad altre applicazioni, le sessioni eliminate e gli ID di sessione di Verifica aziendale (KYB) restituiscono tutti `404`.", "schema": { "type": "string", "format": "uuid", "example": "8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Etichetta di stato opzionale da registrare nella voce. Accetta qualsiasi valore di stato della sessione, con distinzione tra maiuscole e minuscole (`\"approved\"` viene rifiutato con `400`). La registrazione di uno stato qui **non** modifica lo stato effettivo della sessione: usa l'endpoint di aggiornamento dello stato a tale scopo.", "example": "In Review" }, "comment": { "type": "string", "nullable": true, "description": "Nota opzionale a testo libero (nessun limite di lunghezza imposto). Memorizzata letteralmente; le menzioni `@email` non vengono elaborate su questo endpoint.", "example": "Flagging for manual document re-check." } } }, "examples": { "NoteWithStatusLabel": { "summary": "Nota con un'etichetta di stato (lo stato della sessione rimane invariato)", "value": { "new_status": "In Review", "comment": "Flagging for manual document re-check." } }, "CommentOnly": { "summary": "Nota semplice senza un'etichetta di stato", "value": { "comment": "Customer emailed an updated utility bill; awaiting upload." } } } } } }, "responses": { "201": { "description": "Voce registrata nel registro di audit della sessione. La sessione stessa rimane invariata: il suo `status` mantiene il valore precedente e non viene inviato alcun webhook. La nuova voce compare anche in cima a `GET …/reviews/` (con `actor_display: \"Unknown\"`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "Nome visualizzato dell'autore della voce. Sempre `\"Unknown\"` per le voci create tramite questo endpoint, poiché non registra l'autore.", "example": "Unknown" }, "new_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "L'etichetta di stato registrata sulla voce, oppure `null` se non ne è stata inviata alcuna. Lo stato effettivo della sessione non viene modificato.", "example": "In Review" }, "comment": { "type": "string", "nullable": true, "description": "La nota registrata sulla voce, o `null` se non ne è stata inviata alcuna.", "example": "Flagging for manual document re-check." }, "created_at": { "type": "string", "format": "date-time", "description": "Data e ora di scrittura della voce, ISO 8601 UTC.", "example": "2026-06-12T00:18:44.466537Z" } } }, "examples": { "NoteWithStatusLabel": { "summary": "Nota con un'etichetta di stato", "value": { "user": "Unknown", "new_status": "In Review", "comment": "Flagging for manual document re-check.", "created_at": "2026-06-12T00:18:44.466537Z" } }, "CommentOnly": { "summary": "Nota semplice", "value": { "user": "Unknown", "new_status": null, "comment": "Note without status.", "created_at": "2026-06-12T00:18:44.504157Z" } } } } } }, "400": { "description": "Errore di validazione, restituito come mappa di messaggi per singolo campo. La causa abituale è un valore `new_status` che non rientra tra i dieci stati consentiti — il controllo rileva la distinzione tra maiuscole e minuscole.", "content": { "application/json": { "schema": { "type": "object", "properties": { "new_status": { "type": "array", "items": { "type": "string" }, "example": [ "\"approved\" is not a valid choice." ] } } }, "examples": { "InvalidStatusChoice": { "summary": "Valore di stato minuscolo / sconosciuto", "value": { "new_status": [ "\"approved\" is not a valid choice." ] } } } } } }, "403": { "description": "`x-api-key` mancante, malformata, scaduta o revocata. L'autenticazione viene verificata prima della ricerca della sessione, quindi una chiave mancante restituisce `403` anche quando l'UUID della sessione non esiste.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." } } }, "examples": { "InvalidKey": { "summary": "Intestazione x-api-key mancante o non valida", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessuna sessione di Verifica degli utenti (KYC) con questo UUID è visibile alla tua applicazione: l'UUID non esiste, la sessione è stata eliminata o appartiene a un'altra applicazione. Anche gli ID di sessione di Verifica aziendale (KYB) restituiscono `404` qui — il feed delle revisioni è accessibile solo per le sessioni KYC.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Session not found." } } }, "examples": { "NotFound": { "summary": "UUID della sessione sconosciuto, eliminato o appartenente a un'altra applicazione", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite di frequenza superato. Esamina le intestazioni di risposta `Retry-After` e `X-RateLimit-*`. Consulta [Limiti di frequenza](/it/integration/rate-limiting)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "# Records an audit-trail note only -- the session's status does NOT change.\ncurl -s -X POST https://verification.didit.me/v3/sessions/8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d/reviews/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"new_status\": \"In Review\",\n \"comment\": \"Flagging for manual document re-check.\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.reviews.create(\n \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\",\n new_status=\"In Review\",\n comment=\"Flagging for manual document re-check.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.reviews.create(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", {\n new_status: \"In Review\",\n comment: \"Flagging for manual document re-check.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Reviews.Create(ctx, \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", didit.SessionsReviewsCreateParams{\n\tNewStatus: didit.Some(didit.SessionsReviewsCreateParamsNewStatus(\"In Review\")),\n\tComment: didit.String(\"Flagging for manual document re-check.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsReviewsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().reviews().create(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", SessionsReviewsCreateParams.builder()\n .newStatus(SessionsReviewsCreateParams.NewStatus.of(\"In Review\"))\n .comment(\"Flagging for manual document re-check.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->reviews->create('8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d', [\n 'new_status' => 'In Review',\n 'comment' => 'Flagging for manual document re-check.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.reviews.create(\n \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\",\n new_status: \"In Review\",\n comment: \"Flagging for manual document re-check.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Reviews.CreateAsync(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", new SessionsReviewsCreateParams\n{\n NewStatus = new SessionsReviewsCreateParamsNewStatus(\"In Review\"),\n Comment = \"Flagging for manual document re-check.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/billing/balance/": { "get": { "summary": "Recupera saldo crediti", "description": "Recupera il saldo attuale dei crediti prepagati in USD (a livello di organizzazione) e la configurazione di ricarica automatica. Gli importi sono stringhe decimali: analizzali con una libreria per numeri decimali.", "operationId": "get_billing_balance", "x-didit-sdk": { "resource": "billing", "method": "retrieve_balance", "auth": "api_key", "server": true }, "tags": [ "Billing" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/billing/balance/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.billing.retrieve_balance()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.billing.retrieveBalance();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Billing.RetrieveBalance(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.billing().retrieveBalance();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "billing->retrieveBalance();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.billing.retrieve_balance\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Billing.RetrieveBalanceAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Saldo crediti attuale più la configurazione di ricarica automatica dell'organizzazione.", "content": { "application/json": { "schema": { "type": "object", "required": [ "balance", "auto_refill_enabled" ], "properties": { "balance": { "type": "string", "description": "Saldo attuale dei crediti prepagati in USD, come stringa decimale a virgola fissa. Diminuisce man mano che le verifiche vengono fatturate e aumenta quando una ricarica va a buon fine." }, "auto_refill_enabled": { "type": "boolean", "description": "Quando è `true`, Didit addebiterà automaticamente il metodo di pagamento salvato per aggiungere crediti non appena il saldo supera `auto_refill_threshold`. Si configura da Console → Fatturazione." }, "auto_refill_amount": { "type": "string", "nullable": true, "description": "Importo in USD che verrà addebitato e aggiunto al saldo a ogni ricarica automatica, al valore nominale. Impostabile da \\$50 a \\$20,000 in Console → Fatturazione. `null` quando la ricarica automatica è disabilitata o non impostata." }, "auto_refill_threshold": { "type": "string", "nullable": true, "description": "Soglia di trigger in USD. La ricarica automatica si attiva quando `balance` scende al di sotto di questo valore. `null` quando la ricarica automatica è disabilitata o non impostata." } } }, "examples": { "Healthy balance with auto-refill": { "value": { "balance": "1234.5600", "auto_refill_enabled": true, "auto_refill_amount": "500.00", "auto_refill_threshold": "100.00" } }, "Low balance, manual top-up only": { "value": { "balance": "12.0000", "auto_refill_enabled": false, "auto_refill_amount": null, "auto_refill_threshold": null } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può leggere i dati di fatturazione per questa organizzazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/billing/top-up/": { "post": { "summary": "Ricaricare i crediti", "description": "Aggiungi crediti tramite una sessione ospitata di Stripe Checkout (**\\$50 a \\$20,000** per ricarica). Le ricariche sono disponibili sui piani Free, Growth e Scale, vengono aggiunte al valore nominale senza sconti o bonus e hanno una validità di 12 mesi; i contratti annuali Enterprise non possono effettuare ricariche. Reindirizza il cliente al `checkout_session_url` restituito.", "operationId": "billing_top_up", "x-didit-sdk": { "resource": "billing", "method": "top_up", "auth": "api_key", "server": true }, "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_in_dollars" ], "properties": { "amount_in_dollars": { "type": "number", "minimum": 50, "maximum": 20000, "description": "Importo da addebitare, in USD. **Deve essere compreso tra 50 e 20.000.** Il saldo riceve lo stesso importo, senza sconti o bonus. Le imposte vengono aggiunte automaticamente al checkout in base all'indirizzo di fatturazione del cliente." }, "success_url": { "type": "string", "format": "uri", "description": "URL a cui il checkout ospitato reindirizza il cliente dopo un pagamento riuscito. Attualmente il valore predefinito è `https://console.didit.me`. Passa esplicitamente un URL funzionante; l'host predefinito non è disponibile. Aggiungi il segnaposto letterale `{CHECKOUT_SESSION_ID}` se desideri che il checkout ospitato sostituisca l'ID sessione." }, "cancel_url": { "type": "string", "format": "uri", "description": "URL a cui il checkout ospitato reindirizza il cliente quando interrompe o chiude la finestra di checkout. Attualmente il valore predefinito è `https://console.didit.me`. Passa esplicitamente un URL funzionante; l'host predefinito non è disponibile." } } }, "examples": { "Minimum top-up": { "value": { "amount_in_dollars": 50 } }, "Custom amount with redirects": { "value": { "amount_in_dollars": 500, "success_url": "https://yourapp.com/billing/top-up/success", "cancel_url": "https://yourapp.com/billing/top-up/cancel" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/billing/top-up/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"amount_in_dollars\": 500,\n \"success_url\": \"https://yourapp.com/billing/success\",\n \"cancel_url\": \"https://yourapp.com/billing/cancel\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.billing.top_up(\n amount_in_dollars=50.0,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.billing.topUp({\n amount_in_dollars: 50.0,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Billing.TopUp(ctx, didit.BillingTopUpParams{\n\tAmountInDollars: 50.0,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BillingTopUpParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.billing().topUp(BillingTopUpParams.builder()\n .amountInDollars(50.0)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "billing->topUp([\n 'amount_in_dollars' => 50.0,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.billing.top_up(amount_in_dollars: 50.0)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Billing.TopUpAsync(new BillingTopUpParams\n{\n AmountInDollars = 50.0,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Sessione di checkout ospitata creata. Reindirizza l'utente a `checkout_session_url` per completare il pagamento.", "content": { "application/json": { "schema": { "type": "object", "required": [ "checkout_session_id", "checkout_session_url" ], "properties": { "checkout_session_id": { "type": "string", "description": "Identificatore della sessione di checkout ospitata (ad es. `cs_test_a1B2c3...`). Utile per la riconciliazione lato server." }, "checkout_session_url": { "type": "string", "format": "uri", "description": "URL monouso della pagina di pagamento ospitata. Reindirizza il cliente qui per completare il pagamento." } } }, "examples": { "Created": { "value": { "checkout_session_id": "cs_test_a1B2c3D4e5F6g7H8i9J0", "checkout_session_url": "https://checkout.example.com/c/pay/cs_test_a1B2c3D4e5F6g7H8i9J0" } } } } } }, "400": { "description": "Payload non valido: l'importo è mancante, non è un numero, è inferiore al minimo di \\$50 o superiore al massimo di \\$20,000, oppure l'organizzazione dispone di un contratto annuale Enterprise. Il corpo dell'errore è un array JSON.", "content": { "application/json": { "examples": { "Missing amount": { "value": [ "amount_in_dollars is required." ] }, "Not a number": { "value": [ "amount_in_dollars must be a number." ] }, "Below minimum": { "value": [ "Amount must be at least $50." ] }, "Above maximum": { "value": [ "Amount must be at most $20,000." ] }, "Annual plan": { "value": [ "You have an annual plan. Contact your account manager to top up." ] } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può creare sessioni di ricarica per questa organizzazione. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/": { "get": { "summary": "Elenca le destinazioni webhook", "description": "Elenca tutte le destinazioni webhook (array non paginato, dalla meno recente). Ogni elemento include la configurazione della destinazione, le sue metriche di consegna per gli ultimi 30 giorni (`metrics_window_days`) con una voce `daily_points` al giorno e il suo stato (`health_status`, `failing_streak`, `failing_since`, `last_success_at`). L'elenco non include alcun oggetto `summary` e non riporta mai il segreto di firma: ogni voce mostra solo `secret_last4`. Recupera una singola destinazione (`GET /v3/webhook/destinations/{destination_uuid}/`) per leggere `secret_shared_key`.", "operationId": "list_webhook_destinations", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.list()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.list();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.List(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().list();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->list();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.webhooks.destinations.list.each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.ListAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Elenca le destinazioni webhook (senza paginazione, dalla meno recente alla più recente).", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificatore stabile della destinazione; da usare come `{destination_uuid}` per aggiornamento/eliminazione." }, "label": { "type": "string", "description": "Nome di facile lettura mostrato nella Console." }, "url": { "type": "string", "format": "uri", "description": "URL di destinazione che riceve richieste `POST` con il payload del webhook." }, "enabled": { "type": "boolean", "description": "Quando è `false`, Didit ignora silenziosamente la consegna a questa destinazione." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versione dello schema del payload inviata a questa destinazione. `v3` è il formato attuale/consigliato." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "subscribed_events_count": { "type": "integer", "description": "Lunghezza memorizzata nella cache di `subscribed_events`, utile per il rendering dell'interfaccia utente." }, "deliveries_count": { "type": "integer", "description": "Tentativi di consegna (inclusi i nuovi tentativi) effettuati verso questa destinazione negli ultimi 30 giorni." }, "failed_deliveries_count": { "type": "integer", "description": "Tentativi di consegna negli ultimi 30 giorni a cui la destinazione ha risposto con HTTP 400 o superiore, oppure non ha risposto (timeout, connessione rifiutata o indirizzo bloccato)." }, "average_response_time_ms": { "type": "integer", "nullable": true, "description": "Tempo medio di risposta in millisecondi negli ultimi 30 giorni, arrotondato a un numero intero. `null` in assenza di consegne in tale intervallo." }, "error_rate_percentage": { "type": "integer", "description": "`round(failed_deliveries_count / deliveries_count * 100)` negli ultimi 30 giorni; `0` quando non ci sono consegne." }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp del tentativo di consegna più recente (riuscito o fallito). `null` se non è mai stata consegnata." }, "metrics_window_days": { "type": "integer", "description": "Durata in giorni dell'intervallo coperto da `deliveries_count`, `failed_deliveries_count`, `average_response_time_ms`, `error_rate_percentage` e `daily_points`. Sempre `30`." }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "Stato della consegna. `failing`: 3 o più eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta riuscita della destinazione (vedere `failing_streak`). `degraded`: non in errore, ma un tentativo di consegna è fallito nelle ultime 24 ore e nessun tentativo successivo ha consegnato quell'evento; un nuovo tentativo o reinvio che lo consegna cancella questa condizione. `healthy`: nessuno dei due. Indipendente da `enabled`. Un tentativo fallito è quello a cui è stato risposto con HTTP 400 o superiore, o a cui non è stata data alcuna risposta." }, "failing_streak": { "type": "integer", "description": "Quanti eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta positiva della destinazione, negli ultimi 30 giorni. I nuovi tentativi non vengono conteggiati e qualsiasi tentativo riuscito, inclusi nuovi tentativi o reinvii, interrompe la serie. `0` quando nessun evento ha fallito dall'ultimo successo." }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora del primo tentativo fallito dell'attuale `failing_streak`. `null` quando `failing_streak` è `0`." }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultima risposta della destinazione a una consegna con uno stato HTTP inferiore a 400, negli ultimi 30 giorni. `null` se non ha risposto in tale intervallo." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente dell'applicazione proprietaria della destinazione." }, "daily_points": { "type": "array", "description": "Una voce per ogni giorno UTC degli ultimi 30 giorni, a partire dal più vecchio, inclusi i giorni senza consegne. Conteggia ogni tentativo, nuovi tentativi inclusi.", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Il giorno UTC." }, "total_deliveries": { "type": "integer", "description": "Tentativi di consegna effettuati in quel giorno." }, "failed_deliveries": { "type": "integer", "description": "Tentativi effettuati in quel giorno che hanno ricevuto una risposta HTTP 400 o superiore oppure non hanno ricevuto alcuna risposta." } } } }, "secret_last4": { "type": "string", "description": "Ultimi quattro caratteri del segreto di firma attuale della destinazione, per consentirti di distinguere i segreti. Non sufficienti per verificare una firma." }, "created_by_email": { "type": "string", "nullable": true, "description": "Email del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API." }, "created_by_name": { "type": "string", "nullable": true, "description": "Nome del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "examples": { "Two destinations": { "value": [ { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "subscribed_events": [ "status.updated", "data.updated" ], "subscribed_events_count": 2, "deliveries_count": 12453, "failed_deliveries_count": 14, "average_response_time_ms": 187, "error_rate_percentage": 0, "last_delivery_at": "2026-05-17T09:21:18Z", "metrics_window_days": 30, "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": "2026-05-17T09:21:18Z", "environment": "live", "daily_points": [ { "date": "2026-04-18", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-19", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-20", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-21", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-22", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-23", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-24", "total_deliveries": 415, "failed_deliveries": 9 }, { "date": "2026-04-25", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-26", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-27", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-28", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-29", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-30", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-01", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-02", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-03", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-04", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-05", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-06", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-07", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-08", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-09", "total_deliveries": 415, "failed_deliveries": 5 }, { "date": "2026-05-10", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-11", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-12", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-13", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-14", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-15", "total_deliveries": 416, "failed_deliveries": 0 }, { "date": "2026-05-16", "total_deliveries": 416, "failed_deliveries": 0 }, { "date": "2026-05-17", "total_deliveries": 416, "failed_deliveries": 0 } ], "secret_last4": "0xnQ", "created_by_email": null, "created_by_name": null, "created_at": "2026-01-04T08:00:00Z", "updated_at": "2026-04-22T14:09:11Z" }, { "uuid": "22222222-3333-4444-5555-666666666666", "label": "Staging mirror", "url": "https://staging.yourapp.com/webhooks/didit", "enabled": false, "webhook_version": "v3", "subscribed_events": [ "status.updated" ], "subscribed_events_count": 1, "deliveries_count": 0, "failed_deliveries_count": 0, "average_response_time_ms": null, "error_rate_percentage": 0, "last_delivery_at": null, "metrics_window_days": 30, "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": null, "environment": "live", "daily_points": [ { "date": "2026-04-18", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-19", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-20", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-21", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-22", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-23", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-24", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-25", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-26", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-27", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-28", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-29", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-30", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-01", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-02", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-03", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-04", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-05", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-06", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-07", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-08", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-09", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-10", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-11", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-12", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-13", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-14", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-15", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-16", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-17", "total_deliveries": 0, "failed_deliveries": 0 } ], "secret_last4": "k9Qe", "created_by_email": "reviewer@example.com", "created_by_name": "Example Reviewer", "created_at": "2026-03-12T10:15:02Z", "updated_at": "2026-03-12T10:15:02Z" } ] } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea destinazione webhook", "description": "Crea una destinazione webhook. La risposta include il segreto di firma HMAC `secret_shared_key` generato automaticamente (leggibile anche in seguito tramite `GET /v3/webhook/destinations/{destination_uuid}/`). Invia sempre `subscribed_events` con almeno un evento (senza caratteri jolly): una lista esplicitamente vuota viene rifiutata con 400, mentre l'omissione del campo crea una destinazione non iscritta ad alcun evento, che non riceverà mai un webhook. La coppia `(application, url)` deve essere univoca tra le destinazioni dell'applicazione.", "operationId": "create_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"label\": \"Production session webhooks\",\n \"url\": \"https://yourapp.com/webhooks/didit\",\n \"webhook_version\": \"v3\",\n \"subscribed_events\": [\"status.updated\", \"data.updated\"]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.create(\n label=\"Production session webhooks\",\n url=\"https://yourapp.com/webhooks/didit\",\n webhook_version=\"v3\",\n subscribed_events=[\"status.updated\", \"data.updated\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.create({\n label: \"Production session webhooks\",\n url: \"https://yourapp.com/webhooks/didit\",\n webhook_version: \"v3\",\n subscribed_events: [\"status.updated\", \"data.updated\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.WebhookEvent;\nimport me.didit.types.WebhooksDestinationsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder()\n .label(\"Production session webhooks\")\n .url(\"https://yourapp.com/webhooks/didit\")\n .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of(\"v3\"))\n .subscribedEvents(List.of(WebhookEvent.of(\"status.updated\"), WebhookEvent.of(\"data.updated\")))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->create([\n 'label' => 'Production session webhooks',\n 'url' => 'https://yourapp.com/webhooks/didit',\n 'webhook_version' => 'v3',\n 'subscribed_events' => ['status.updated', 'data.updated'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.create(\n label: \"Production session webhooks\",\n url: \"https://yourapp.com/webhooks/didit\",\n webhook_version: \"v3\",\n subscribed_events: [\"status.updated\", \"data.updated\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.CreateAsync(new WebhooksDestinationsCreateParams\n{\n Label = \"Production session webhooks\",\n Url = \"https://yourapp.com/webhooks/didit\",\n WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion(\"v3\"),\n SubscribedEvents = new WebhookEvent[] { \"status.updated\", \"data.updated\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "url" ], "properties": { "label": { "type": "string", "maxLength": 255, "description": "Nome di facile lettura visualizzato in Console → Webhooks. Aiuta a distinguere le destinazioni quando ne hai diverse (ad es. \"Prod\", \"Staging mirror\")." }, "url": { "type": "string", "format": "uri", "description": "URL HTTPS che riceverà le richieste `POST`. Deve essere univoco tra le destinazioni dell'applicazione. Usa un endpoint stabile e protetto: Didit ritenta le consegne non riuscite secondo una pianificazione con backoff.", "maxLength": 2000 }, "enabled": { "type": "boolean", "default": true, "description": "Quando è `false`, la destinazione viene salvata ma Didit non invierà alcun webhook ad essa. Utile per le configurazioni di staging che desideri mantenere in sospeso." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versione dello schema del payload che Didit invierà. `v3` è il formato attuale/consigliato; le versioni precedenti vengono mantenute per retrocompatibilità con le integrazioni legacy." }, "subscribed_events": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscribedEvents" } ], "description": "Eventi da consegnare. Di fatto obbligatorio: un `[]` esplicito viene rifiutato con 400, e omettendo il campo si crea una destinazione senza abbonamenti che non riceve nulla." } } }, "examples": { "session_updates": { "summary": "Aggiornamenti sui dati e sullo stato della sessione", "value": { "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": [ "status.updated", "data.updated" ] } }, "transaction_updates": { "summary": "Aggiornamenti del monitoraggio delle transazioni", "value": { "label": "Transaction monitoring webhooks", "url": "https://yourapp.com/webhooks/didit-transactions", "webhook_version": "v3", "subscribed_events": [ "transaction.created", "transaction.status.updated" ] } }, "entity_updates": { "summary": "Aggiornamenti delle entità utente e azienda", "value": { "label": "Entity lifecycle webhooks", "url": "https://yourapp.com/webhooks/didit-entities", "webhook_version": "v3", "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } } } } } }, "responses": { "201": { "description": "Destinazione creata. `secret_shared_key` è il segreto di firma HMAC: conservalo ora.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificatore stabile della destinazione. Da usare come `{destination_uuid}` nelle chiamate successive." }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ] }, "secret_shared_key": { "type": "string", "description": "Segreto di firma HMAC generato automaticamente e associato a questa destinazione (token URL-safe di 43 caratteri). Usalo per verificare le intestazioni di firma sui webhook in arrivo. Viene sempre restituito per intero a chi chiama tramite chiave API; gli utenti della Console necessitano dell'autorizzazione `read:webhooks`, altrimenti visualizzano una stringa vuota." }, "secret_last4": { "type": "string", "description": "Ultimi quattro caratteri del segreto di firma attuale della destinazione, per consentirti di distinguere i segreti. Non sufficienti per verificare una firma." }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Impostato per 24 ore dopo la rotazione del segreto di firma della destinazione nella Business Console. Fino a tale momento, ogni consegna alla destinazione include anche `X-Signature-Previous`, `X-Signature-V2-Previous` e `X-Signature-Simple-Previous`, generati con il segreto sostituito (vedi [Verifica della firma](/it/integration/webhooks#verifica-della-firma)). `null` quando non si è verificata alcuna rotazione nelle ultime 24 ore." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "created_by_email": { "type": "string", "nullable": true, "description": "Email del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API." }, "created_by_name": { "type": "string", "nullable": true, "description": "Nome del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "Stato della consegna. `failing`: 3 o più eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta riuscita della destinazione (vedere `failing_streak`). `degraded`: non in errore, ma un tentativo di consegna è fallito nelle ultime 24 ore e nessun tentativo successivo ha consegnato quell'evento; un nuovo tentativo o reinvio che lo consegna cancella questa condizione. `healthy`: nessuno dei due. Indipendente da `enabled`. Un tentativo fallito è quello a cui è stato risposto con HTTP 400 o superiore, o a cui non è stata data alcuna risposta." }, "failing_streak": { "type": "integer", "description": "Quanti eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta positiva della destinazione, negli ultimi 30 giorni. I nuovi tentativi non vengono conteggiati e qualsiasi tentativo riuscito, inclusi nuovi tentativi o reinvii, interrompe la serie. `0` quando nessun evento ha fallito dall'ultimo successo." }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora del primo tentativo fallito dell'attuale `failing_streak`. `null` quando `failing_streak` è `0`." }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultima risposta della destinazione a una consegna con uno stato HTTP inferiore a 400, negli ultimi 30 giorni. `null` se non ha risposto in tale intervallo." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente dell'applicazione proprietaria della destinazione." }, "summary": { "type": "object", "description": "Metriche di consegna per gli ultimi `metrics_window_days` (30) giorni. `last_delivery_at` è il tentativo più recente, a prescindere da quando è stato effettuato.", "properties": { "total_deliveries": { "type": "integer" }, "failed_deliveries": { "type": "integer" }, "error_rate_percentage": { "type": "integer" }, "min_response_time_ms": { "type": "integer", "nullable": true }, "avg_response_time_ms": { "type": "integer", "nullable": true }, "max_response_time_ms": { "type": "integer", "nullable": true }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "metrics_window_days": { "type": "integer", "description": "Durata in giorni dell'intervallo coperto dalle altre metriche di riepilogo. Sempre `30`." } } } } }, "examples": { "Created": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ", "secret_last4": "0xnQ", "previous_secret_expires_at": null, "subscribed_events": [ "status.updated", "data.updated" ], "created_by_email": null, "created_by_name": null, "created_at": "2026-05-17T10:00:00Z", "updated_at": "2026-05-17T10:00:00Z", "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": null, "environment": "live", "summary": { "total_deliveries": 0, "failed_deliveries": 0, "error_rate_percentage": 0, "min_response_time_ms": null, "avg_response_time_ms": null, "max_response_time_ms": null, "last_delivery_at": null, "metrics_window_days": 30 } } } } } } }, "400": { "description": "Validazione non riuscita — solitamente un URL duplicato, `subscribed_events` mancante o non valido, oppure un nome di evento sconosciuto.", "content": { "application/json": { "examples": { "Duplicate URL": { "value": { "url": [ "This webhook destination already exists for the application." ] } }, "Empty events list": { "value": { "subscribed_events": [ "At least one subscribed event is required." ] } }, "Unknown event": { "value": { "subscribed_events": [ "Unsupported webhook events: foo.bar" ] } } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/": { "get": { "summary": "Recupera destinazione webhook", "description": "Recupera una destinazione webhook con il relativo segreto di firma `secret_shared_key`, il suo stato (`health_status`, `failing_streak`, `failing_since`, `last_success_at`) e un riepilogo delle consegne (`summary`) per gli ultimi 30 giorni. Chi effettua chiamate con chiave API riceve sempre il segreto per intero; gli utenti della Console senza `read:webhooks` visualizzano una stringa vuota.", "operationId": "get_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID della destinazione (lo `uuid` restituito dalla creazione/elenco).", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Dettagli della destinazione webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ] }, "secret_shared_key": { "type": "string", "description": "Segreto di firma HMAC (token URL-safe di 43 caratteri). Viene sempre restituito per intero a chi chiama tramite chiave API; gli utenti della Console necessitano di `read:webhooks`, altrimenti viene restituita una stringa vuota." }, "secret_last4": { "type": "string", "description": "Ultimi quattro caratteri del segreto di firma attuale della destinazione, per consentirti di distinguere i segreti. Non sufficienti per verificare una firma." }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Impostato per 24 ore dopo la rotazione del segreto di firma della destinazione nella Business Console. Fino a tale momento, ogni consegna alla destinazione include anche `X-Signature-Previous`, `X-Signature-V2-Previous` e `X-Signature-Simple-Previous`, generati con il segreto sostituito (vedi [Verifica della firma](/it/integration/webhooks#verifica-della-firma)). `null` quando non si è verificata alcuna rotazione nelle ultime 24 ore." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "created_by_email": { "type": "string", "nullable": true, "description": "Email del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API." }, "created_by_name": { "type": "string", "nullable": true, "description": "Nome del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "Stato della consegna. `failing`: 3 o più eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta riuscita della destinazione (vedere `failing_streak`). `degraded`: non in errore, ma un tentativo di consegna è fallito nelle ultime 24 ore e nessun tentativo successivo ha consegnato quell'evento; un nuovo tentativo o reinvio che lo consegna cancella questa condizione. `healthy`: nessuno dei due. Indipendente da `enabled`. Un tentativo fallito è quello a cui è stato risposto con HTTP 400 o superiore, o a cui non è stata data alcuna risposta." }, "failing_streak": { "type": "integer", "description": "Quanti eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta positiva della destinazione, negli ultimi 30 giorni. I nuovi tentativi non vengono conteggiati e qualsiasi tentativo riuscito, inclusi nuovi tentativi o reinvii, interrompe la serie. `0` quando nessun evento ha fallito dall'ultimo successo." }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora del primo tentativo fallito dell'attuale `failing_streak`. `null` quando `failing_streak` è `0`." }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultima risposta della destinazione a una consegna con uno stato HTTP inferiore a 400, negli ultimi 30 giorni. `null` se non ha risposto in tale intervallo." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente dell'applicazione proprietaria della destinazione." }, "summary": { "type": "object", "description": "Metriche di consegna per gli ultimi `metrics_window_days` (30) giorni. `last_delivery_at` è il tentativo più recente, a prescindere da quando è stato effettuato.", "properties": { "total_deliveries": { "type": "integer" }, "failed_deliveries": { "type": "integer" }, "error_rate_percentage": { "type": "integer" }, "min_response_time_ms": { "type": "integer", "nullable": true }, "avg_response_time_ms": { "type": "integer", "nullable": true }, "max_response_time_ms": { "type": "integer", "nullable": true }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "metrics_window_days": { "type": "integer", "description": "Durata in giorni dell'intervallo coperto dalle altre metriche di riepilogo. Sempre `30`." } } } } }, "examples": { "Healthy destination": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ", "secret_last4": "0xnQ", "previous_secret_expires_at": null, "subscribed_events": [ "status.updated", "data.updated" ], "created_by_email": null, "created_by_name": null, "created_at": "2026-01-04T08:00:00Z", "updated_at": "2026-04-22T14:09:11Z", "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": "2026-05-17T09:21:18Z", "environment": "live", "summary": { "total_deliveries": 12453, "failed_deliveries": 14, "error_rate_percentage": 0, "min_response_time_ms": 41, "avg_response_time_ms": 187, "max_response_time_ms": 2103, "last_delivery_at": "2026-05-17T09:21:18Z", "metrics_window_days": 30 } } } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessuna destinazione con questo UUID esiste, oppure appartiene a un'applicazione diversa o è stata eliminata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna la destinazione webhook", "description": "Aggiorna una destinazione webhook. **`subscribed_events` viene SOSTITUITO interamente, non unito**: recupera prima, aggiungi e reinvia. Il segreto non viene ruotato. Un `uuid` nel corpo viene ignorato: il percorso identifica la destinazione.", "operationId": "update_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID della destinazione da aggiornare.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Nuovo nome leggibile." }, "url": { "type": "string", "format": "uri", "description": "Nuovo URL di destinazione. Deve essere univoco all'interno dell'applicazione." }, "enabled": { "type": "boolean", "description": "Imposta su `false` per sospendere le consegne a questa destinazione senza eliminarla." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Nuova versione dello schema del payload per le consegne future." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" } } }, "examples": { "Pause destination": { "value": { "enabled": false } }, "Add transaction events": { "value": { "subscribed_events": [ "status.updated", "data.updated", "transaction.created", "transaction.status.updated" ] } }, "Move target URL": { "value": { "label": "Production session webhooks v2", "url": "https://api.yourapp.com/webhooks/didit/v2" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"subscribed_events\": [\n \"status.updated\",\n \"data.updated\",\n \"transaction.created\"\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.update(\n \"11111111-2222-3333-4444-555555555555\",\n enabled=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.update(\"11111111-2222-3333-4444-555555555555\", {\n enabled: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsUpdateParams{\n\tEnabled: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WebhooksDestinationsUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().update(\"11111111-2222-3333-4444-555555555555\", WebhooksDestinationsUpdateParams.builder()\n .enabled(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->update('11111111-2222-3333-4444-555555555555', [\n 'enabled' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.update(\n \"11111111-2222-3333-4444-555555555555\",\n enabled: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new WebhooksDestinationsUpdateParams\n{\n Enabled = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Destinazione webhook aggiornata. Il corpo ha la stessa struttura di `GET /v3/webhook/destinations/{destination_uuid}/`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ] }, "secret_shared_key": { "type": "string" }, "secret_last4": { "type": "string", "description": "Ultimi quattro caratteri del segreto di firma attuale della destinazione, per consentirti di distinguere i segreti. Non sufficienti per verificare una firma." }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Impostato per 24 ore dopo la rotazione del segreto di firma della destinazione nella Business Console. Fino a tale momento, ogni consegna alla destinazione include anche `X-Signature-Previous`, `X-Signature-V2-Previous` e `X-Signature-Simple-Previous`, generati con il segreto sostituito (vedi [Verifica della firma](/it/integration/webhooks#verifica-della-firma)). `null` quando non si è verificata alcuna rotazione nelle ultime 24 ore." }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "created_by_email": { "type": "string", "nullable": true, "description": "Email del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API." }, "created_by_name": { "type": "string", "nullable": true, "description": "Nome del membro della Business Console che ha creato la destinazione. `null` per una destinazione creata con una chiave API." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "Stato della consegna. `failing`: 3 o più eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta riuscita della destinazione (vedere `failing_streak`). `degraded`: non in errore, ma un tentativo di consegna è fallito nelle ultime 24 ore e nessun tentativo successivo ha consegnato quell'evento; un nuovo tentativo o reinvio che lo consegna cancella questa condizione. `healthy`: nessuno dei due. Indipendente da `enabled`. Un tentativo fallito è quello a cui è stato risposto con HTTP 400 o superiore, o a cui non è stata data alcuna risposta." }, "failing_streak": { "type": "integer", "description": "Quanti eventi consecutivi hanno fallito il primo tentativo di consegna dall'ultima risposta positiva della destinazione, negli ultimi 30 giorni. I nuovi tentativi non vengono conteggiati e qualsiasi tentativo riuscito, inclusi nuovi tentativi o reinvii, interrompe la serie. `0` quando nessun evento ha fallito dall'ultimo successo." }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora del primo tentativo fallito dell'attuale `failing_streak`. `null` quando `failing_streak` è `0`." }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultima risposta della destinazione a una consegna con uno stato HTTP inferiore a 400, negli ultimi 30 giorni. `null` se non ha risposto in tale intervallo." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente dell'applicazione proprietaria della destinazione." }, "summary": { "type": "object", "properties": { "total_deliveries": { "type": "integer" }, "failed_deliveries": { "type": "integer" }, "error_rate_percentage": { "type": "integer" }, "min_response_time_ms": { "type": "integer", "nullable": true }, "avg_response_time_ms": { "type": "integer", "nullable": true }, "max_response_time_ms": { "type": "integer", "nullable": true }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "metrics_window_days": { "type": "integer", "description": "Durata in giorni dell'intervallo coperto dalle altre metriche di riepilogo. Sempre `30`." } }, "description": "Metriche di consegna per gli ultimi `metrics_window_days` (30) giorni. `last_delivery_at` è il tentativo più recente, a prescindere da quando è stato effettuato." } } }, "examples": { "Paused": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": false, "webhook_version": "v3", "secret_shared_key": "tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ", "secret_last4": "0xnQ", "previous_secret_expires_at": null, "subscribed_events": [ "status.updated", "data.updated" ], "created_by_email": null, "created_by_name": null, "created_at": "2026-01-04T08:00:00Z", "updated_at": "2026-05-17T11:02:55Z", "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": "2026-05-17T09:21:18Z", "environment": "live", "summary": { "total_deliveries": 12453, "failed_deliveries": 14, "error_rate_percentage": 0, "min_response_time_ms": 41, "avg_response_time_ms": 187, "max_response_time_ms": 2103, "last_delivery_at": "2026-05-17T09:21:18Z", "metrics_window_days": 30 } } } } } } }, "400": { "description": "Validazione fallita (URL duplicato, elenco di eventi vuoto o contenente eventi sconosciuti, corpo malformato).", "content": { "application/json": { "examples": { "Duplicate URL": { "value": { "url": [ "This webhook destination already exists for the application." ] } }, "Empty events": { "value": { "subscribed_events": [ "At least one subscribed event is required." ] } } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "La destinazione con questo UUID non esiste (o è stata eliminata, o appartiene a un'altra applicazione).", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Elimina destinazione webhook", "description": "Elimina permanentemente una destinazione webhook, il suo segreto di firma e l'intero registro di consegna. L'operazione non può essere annullata. Nessun nuovo webhook viene inviato all'URL della destinazione; le altre destinazioni iscritte agli stessi eventi continuano a riceverli. In seguito, la destinazione non compare più in `GET /v3/webhook/destinations/`, e qualsiasi route sotto `/v3/webhook/destinations/{destination_uuid}/`, comprese le relative consegne, il dettaglio di una consegna e il relativo nuovo invio, risponde 404. Il valore legacy `webhook_url` dell'applicazione viene impostato sull'URL della destinazione abilitata rimasta più vecchia, o cancellato quando non rimane alcuna destinazione abilitata. Chiamando nuovamente DELETE si riceve 404.", "operationId": "delete_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID della destinazione da eliminare.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.webhooks.destinations.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.webhooks.destinations.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Webhooks.Destinations.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.webhooks().destinations().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.webhooks.destinations.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Webhooks.Destinations.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "Destinazione, segreto di firma e registro delle consegne eliminati definitivamente. Nessun corpo di risposta." }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessuna destinazione con questo UUID esiste per l'applicazione (già eliminata o mai esistita).", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/wallet-screening/": { "post": { "summary": "Esegui lo screening di un indirizzo", "description": "Esegui lo screening AML su richiesta per un singolo wallet/indirizzo crypto senza creare una transazione. Determina il provider di analisi blockchain configurato per la tua applicazione, effettua lo screening dell'indirizzo in modo sincrono e restituisce il risultato di rischio normalizzato. LIGHTNING è disponibile solo con una connessione BYOK Elliptic o Chainalysis aggiunta tramite il Marketplace. Non viene scritto nulla nella tabella delle transazioni. Viene fatturato un utilizzo di monitoraggio AML per ogni screening riuscito (le applicazioni sandbox non vengono fatturate).", "operationId": "screenWallet", "x-didit-sdk": { "resource": "wallet_screening", "method": "screen", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet_address" ], "properties": { "wallet_address": { "type": "string", "description": "L'indirizzo crypto o l'identificatore di rete da sottoporre a screening. Deve corrispondere alla rete selezionata (ad es. un indirizzo di 40 caratteri esadecimali con prefisso `0x` per le blockchain EVM). Alias: `address`.", "example": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a" }, "blockchain": { "type": "string", "description": "Identificatore di rete opzionale. Se omesso, la rete viene ricavata dal formato dell'indirizzo: gli indirizzi `bc1`, `1` e `3` sono Bitcoin (BTC), gli indirizzi `T` sono Tron (TRX) e le chiavi pubbliche base58 sono Solana (SOL). Un indirizzo `0x` è valido su ogni rete EVM, quindi l'omissione di `blockchain` per tale indirizzo restituisce 422 con le reti candidate in `candidate_chains`. Lo screening gestito supporta BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE (Base), OP (Optimism), ARB (Arbitrum One), AVAX (Avalanche C-Chain), ADA (Cardano), XLM (Stellar) e HBAR (Hedera). USDT e USDC sono alias legacy di Ethereum, non ricerche multirete. La copertura dei provider connessi varia. LIGHTNING richiede un provider connesso supportato. CELO (Celo), MODE (Mode) e PLUME (Plume) vengono sottoposti a screening tramite un account TRM Labs connesso; lo screening gestito restituisce 400 per questi ultimi. Alias: `currency`.", "enum": [ "BTC", "LIGHTNING", "ETH", "LTC", "XRP", "BCH", "DOGE", "TRX", "SOL", "MATIC", "BNB", "USDT", "USDC", "BASE", "OP", "ARB", "AVAX", "ADA", "XLM", "HBAR", "CELO", "MODE", "PLUME" ], "example": "ETH" }, "direction": { "type": "string", "description": "Opzionale. Indica se l'indirizzo viene sottoposto a screening come controparte in entrata (deposito) o in uscita (prelievo). Accetta `inbound`, `outbound`, `deposit` o `withdrawal`. Se omesso, il valore predefinito è uno screening neutro precedente al trasferimento. Questo dato viene passato al provider esclusivamente come contesto; non modifica il `risk_score`, la `severity` o le suddivisioni di `source_of_funds`/`destination_of_funds` restituite, che vengono sempre fornite entrambe indipendentemente da `direction`. La modifica o l'omissione di `direction` non richiede pertanto un nuovo screening dell'indirizzo.", "enum": [ "inbound", "outbound", "deposit", "withdrawal" ] } } }, "example": { "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", "blockchain": "ETH" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/wallet-screening/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"wallet_address\": \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n \"blockchain\": \"ETH\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.wallet_screening.screen(\n wallet_address=\"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n blockchain=\"ETH\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.walletScreening.screen({\n wallet_address: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n blockchain: \"ETH\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.WalletScreening.Screen(ctx, didit.WalletScreeningScreenParams{\n\tWalletAddress: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n\tBlockchain: didit.Some(didit.WalletScreeningScreenParamsBlockchain(\"ETH\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WalletScreeningScreenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.walletScreening().screen(WalletScreeningScreenParams.builder()\n .walletAddress(\"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\")\n .blockchain(WalletScreeningScreenParams.Blockchain.of(\"ETH\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "walletScreening->screen([\n 'wallet_address' => '0x94f1b9b64e2932f6a2db338f616844400cd58e8a',\n 'blockchain' => 'ETH',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.wallet_screening.screen(\n wallet_address: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n blockchain: \"ETH\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.WalletScreening.ScreenAsync(new WalletScreeningScreenParams\n{\n WalletAddress = \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n Blockchain = new WalletScreeningScreenParamsBlockchain(\"ETH\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il risultato normalizzato dello screening dei wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletScreeningResult" }, "example": { "provider": "merklescience", "screening_type": "WALLET_SCREENING", "risk_score": 95, "severity": "CRITICAL", "status": "SCREENED", "summary": "Merkle Science risk: Critical (5/5). SANCTIONS HIT. Dominant risk: sanctioned. Driven by: the address is attributed to Sanctions / OFAC (Example Sanctions)", "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", "transaction_hash": null, "blockchain": "ETH", "block_timestamp": null, "total_value_usd": null, "fee_usd": null, "sender_rows": [], "receiver_rows": [], "transaction_flows": [], "transaction_flows_status": null, "transaction_flows_error": null, "source_of_funds": [ { "category": "sanctioned", "percentage": 100.0, "amount_usd": 9813695.0, "entity_name": "Example Sanctions", "entity_type": "Sanctions", "entity_subtype": "OFAC", "hops": null, "description": "Sanctions / OFAC", "is_direct": true, "exposure_direction": "incoming", "exposure_type": "direct", "provider_entity_id": "118885", "provider_entity_type_id": "30", "provider_entity_subtype_id": "125", "country": "", "raw_amount": null, "raw_currency": null } ], "destination_of_funds": [ { "category": "defi", "percentage": 84.824453, "amount_usd": 7783414.38, "entity_name": "Example DeFi 7", "entity_type": "DeFi", "entity_subtype": "Bridges", "hops": null, "description": "DeFi / Bridges", "is_direct": false, "exposure_direction": "outgoing", "exposure_type": "indirect", "provider_entity_id": "118459", "provider_entity_type_id": "33", "provider_entity_subtype_id": "143", "country": "", "raw_amount": null, "raw_currency": null }, { "category": "defi", "percentage": 15.175547, "amount_usd": 1392494.37, "entity_name": "Example DeFi 2", "entity_type": "DeFi", "entity_subtype": "Yield Aggregator", "hops": null, "description": "DeFi / Yield Aggregator", "is_direct": false, "exposure_direction": "outgoing", "exposure_type": "indirect", "provider_entity_id": "90192", "provider_entity_type_id": "33", "provider_entity_subtype_id": "142", "country": "", "raw_amount": null, "raw_currency": null } ], "counterparty_connections": [ { "entity_name": "Example Sanctions", "entity_type": "Sanctions", "entity_subtype": "OFAC", "risk_level": "critical", "categories": [ "sanctioned" ], "received_usd": null, "sent_usd": null, "received_hops": null, "sent_hops": null, "percentage": 0.0, "is_direct": true, "country": null, "provider_entity_id": null }, { "entity_name": "Example Sanctions", "entity_type": "Sanctions", "entity_subtype": "OFAC", "risk_level": "critical", "categories": [ "sanctioned" ], "received_usd": null, "sent_usd": null, "received_hops": null, "sent_hops": null, "percentage": 0.0, "is_direct": true, "country": null, "provider_entity_id": null } ], "network_nodes": [], "network_edges": [], "sanctions_hit": true, "pep_counterparty": null, "dominant_risk_category": "sanctioned", "risk_factors": [ { "source": "attribution", "category": "sanctioned", "label": "Sanctions / OFAC", "entity_name": "Example Sanctions", "direction": "attribution", "exposure_type": "attribution", "amount_usd": null, "percentage": 0.0, "is_high_risk": true, "description": "the address is attributed to Sanctions / OFAC (Example Sanctions)" }, { "source": "exposure", "category": "sanctioned", "label": "Sanctions / OFAC", "entity_name": "Example Sanctions", "direction": "incoming", "exposure_type": "direct", "amount_usd": 9813695.0, "percentage": 51.679304, "is_high_risk": true, "description": "51.6793% direct incoming exposure to Sanctions / OFAC (Example Sanctions)" }, { "source": "exposure", "category": "defi", "label": "DeFi / Bridges", "entity_name": "Example DeFi 7", "direction": "outgoing", "exposure_type": "indirect", "amount_usd": 7783414.38, "percentage": 40.987766, "is_high_risk": false, "description": "40.9878% indirect outgoing exposure to DeFi / Bridges (Example DeFi 7)" }, { "source": "exposure", "category": "defi", "label": "DeFi / Yield Aggregator", "entity_name": "Example DeFi 2", "direction": "outgoing", "exposure_type": "indirect", "amount_usd": 1392494.37, "percentage": 7.33293, "is_high_risk": false, "description": "7.33293% indirect outgoing exposure to DeFi / Yield Aggregator (Example DeFi 2)" } ], "raw_response": { "...": "provider-specific details" }, "report_signature": "" } } } }, "400": { "description": "Errore di validazione — indirizzo non valido, `wallet_address` mancante, `blockchain` non supportata, `blockchain` omessa per un indirizzo il cui formato non indica alcuna rete, oppure LIGHTNING senza una connessione Marketplace BYOK di Elliptic o Chainalysis." }, "401": { "description": "`x-api-key` mancante o non valida." }, "409": { "description": "Nessun provider AML è configurato per l'applicazione, oppure il provider configurato non supporta ancora lo screening dei wallet. Configura prima il monitoraggio delle transazioni." }, "422": { "description": "`blockchain` omesso per un indirizzo `0x`, condiviso da ogni rete EVM. Non viene eseguito alcuno screening né addebitato alcun costo; invia nuovamente impostando `blockchain` su una delle `candidate_chains`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchain": { "type": "array", "items": { "type": "string" }, "example": [ "A 0x address is valid on every EVM chain. Send blockchain as one of: ETH, BNB, MATIC, BASE, ARB, OP, CELO, MODE, PLUME." ] }, "candidate_chains": { "type": "array", "items": { "type": "string" }, "example": [ "ETH", "BNB", "MATIC", "BASE", "ARB", "OP", "CELO", "MODE", "PLUME" ] } } } } } }, "502": { "description": "Il fornitore AML non è riuscito a completare lo screening. Riprova più tardi." } } } }, "/v3/wallet-screening/pdf/": { "post": { "summary": "Genera il risultato di uno screening dei wallet in formato PDF", "description": "Complemento senza stato di `POST /v3/wallet-screening/`: invia nuovamente l'esatto corpo JSON restituito da quell'endpoint — compresa la `report_signature` aggiunta — e ricevi un PDF con marchio Didit dello stesso risultato. Nessun provider viene chiamato e nulla viene fatturato o memorizzato; questo esegue solo un nuovo rendering di un risultato già prodotto da Didit. La firma vincola il PDF a un risultato non modificato: la modifica di `risk_score`, `severity`, `sanctions_hit` o qualsiasi altro campo firmato prima del nuovo invio fallisce con `400`.", "operationId": "screenWalletPdf", "x-didit-sdk": { "resource": "wallet_screening", "method": "screen_pdf", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "description": "L'oggetto JSON non modificato restituito da `POST /v3/wallet-screening/`, incluso `report_signature`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WalletScreeningResult" } ], "required": [ "report_signature" ], "description": "Stessa struttura della risposta di `POST /v3/wallet-screening/` — restituisci quel corpo della risposta esattamente così com'è, incluso `report_signature`." } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "# $RESULT is the saved JSON body from POST /v3/wallet-screening/\ncurl -X POST 'https://verification.didit.me/v3/wallet-screening/pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d \"$RESULT\" \\\n -o wallet_screening_report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.wallet_screening.screen_pdf(\n provider=\"your-provider\",\n screening_type=\"WALLET_SCREENING\",\n risk_score=1,\n severity=\"UNKNOWN\",\n status=\"SCREENED\",\n summary=\"your-summary\",\n wallet_address=\"your-wallet-address\",\n blockchain=\"your-blockchain\",\n source_of_funds=[{}],\n destination_of_funds=[{}],\n counterparty_connections=[{}],\n sanctions_hit=True,\n dominant_risk_category=\"your-dominant-risk-category\",\n report_signature=\"your-report-signature\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.walletScreening.screenPdf({\n provider: \"your-provider\",\n screening_type: \"WALLET_SCREENING\",\n risk_score: 1,\n severity: \"UNKNOWN\",\n status: \"SCREENED\",\n summary: \"your-summary\",\n wallet_address: \"your-wallet-address\",\n blockchain: \"your-blockchain\",\n source_of_funds: [{}],\n destination_of_funds: [{}],\n counterparty_connections: [{}],\n sanctions_hit: true,\n dominant_risk_category: \"your-dominant-risk-category\",\n report_signature: \"your-report-signature\",\n});\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.WalletScreening.ScreenPDF(ctx, didit.WalletScreeningResultParam{\n\tProvider: \"your-provider\",\n\tScreeningType: \"WALLET_SCREENING\",\n\tRiskScore: 1,\n\tSeverity: \"UNKNOWN\",\n\tStatus: \"SCREENED\",\n\tSummary: \"your-summary\",\n\tWalletAddress: \"your-wallet-address\",\n\tBlockchain: \"your-blockchain\",\n\tSourceOfFunds: []didit.WalletScreeningResultParamSourceOfFunds{{}},\n\tDestinationOfFunds: []didit.WalletScreeningResultParamDestinationOfFunds{{}},\n\tCounterpartyConnections: []didit.WalletScreeningResultParamCounterpartyConnections{{}},\n\tSanctionsHit: true,\n\tDominantRiskCategory: didit.String(\"your-dominant-risk-category\"),\n\tReportSignature: \"your-report-signature\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.WalletScreeningResult;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.walletScreening().screenPdf(WalletScreeningResult.builder()\n .provider(\"your-provider\")\n .screeningType(WalletScreeningResult.ScreeningType.of(\"WALLET_SCREENING\"))\n .riskScore(1L)\n .severity(WalletScreeningResult.Severity.of(\"UNKNOWN\"))\n .status(WalletScreeningResult.Status.of(\"SCREENED\"))\n .summary(\"your-summary\")\n .walletAddress(\"your-wallet-address\")\n .blockchain(\"your-blockchain\")\n .sourceOfFunds(List.of(WalletScreeningResult.SourceOfFunds.builder()\n .build()))\n .destinationOfFunds(List.of(WalletScreeningResult.DestinationOfFunds.builder()\n .build()))\n .counterpartyConnections(List.of(WalletScreeningResult.CounterpartyConnections.builder()\n .build()))\n .sanctionsHit(true)\n .dominantRiskCategory(\"your-dominant-risk-category\")\n .reportSignature(\"your-report-signature\")\n .build())\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "walletScreening->screenPdf([\n 'provider' => 'your-provider',\n 'screening_type' => 'WALLET_SCREENING',\n 'risk_score' => 1,\n 'severity' => 'UNKNOWN',\n 'status' => 'SCREENED',\n 'summary' => 'your-summary',\n 'wallet_address' => 'your-wallet-address',\n 'blockchain' => 'your-blockchain',\n 'source_of_funds' => [[]],\n 'destination_of_funds' => [[]],\n 'counterparty_connections' => [[]],\n 'sanctions_hit' => true,\n 'dominant_risk_category' => 'your-dominant-risk-category',\n 'report_signature' => 'your-report-signature',\n]);\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.wallet_screening.screen_pdf(\n provider: \"your-provider\",\n screening_type: \"WALLET_SCREENING\",\n risk_score: 1,\n severity: \"UNKNOWN\",\n status: \"SCREENED\",\n summary: \"your-summary\",\n wallet_address: \"your-wallet-address\",\n blockchain: \"your-blockchain\",\n source_of_funds: [{}],\n destination_of_funds: [{}],\n counterparty_connections: [{}],\n sanctions_hit: true,\n dominant_risk_category: \"your-dominant-risk-category\",\n report_signature: \"your-report-signature\"\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.WalletScreening.ScreenPdfAsync(new WalletScreeningResult\n{\n Provider = \"your-provider\",\n ScreeningType = \"WALLET_SCREENING\",\n RiskScore = 1,\n Severity = \"UNKNOWN\",\n Status = \"SCREENED\",\n Summary = \"your-summary\",\n WalletAddress = \"your-wallet-address\",\n Blockchain = \"your-blockchain\",\n SourceOfFunds = new WalletScreeningResultSourceOfFunds[] { new() },\n DestinationOfFunds = new WalletScreeningResultDestinationOfFunds[] { new() },\n CounterpartyConnections = new WalletScreeningResultCounterpartyConnections[] { new() },\n SanctionsHit = true,\n DominantRiskCategory = \"your-dominant-risk-category\",\n ReportSignature = \"your-report-signature\",\n});\nawait content.SaveToAsync(\"download.pdf\");" } ], "responses": { "200": { "description": "Il documento PDF renderizzato, restituito direttamente come binario `application/pdf` — non è presente alcun wrapper JSON.", "headers": { "Content-Disposition": { "description": "`attachment; filename=wallet_screening_{address}.pdf`, ricavato da `wallet_address` (o `transaction_hash`) nel risultato ripubblicato.", "schema": { "type": "string", "example": "attachment; filename=wallet_screening_0x28c6c06298d514db0899.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Il body non è un oggetto JSON conforme alla struttura del risultato dello screening dei wallet, oppure `report_signature` è assente o non corrisponde ai campi ripubblicati (modificati o troncati prima della ripubblicazione).", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Not an object": { "value": { "non_field_errors": [ "Expected a JSON object matching a wallet-screening result." ] } }, "Missing or invalid signature": { "value": { "report_signature": [ "This wallet-screening result is missing or fails its report signature - repost the exact JSON returned by the wallet-screening endpoint, unmodified." ] } } } } } }, "401": { "description": "`x-api-key` mancante o non valida." } } } }, "/v3/transactions/": { "get": { "summary": "Elenca le transazioni", "description": "Elenco impaginato delle transazioni monitorate, dalla più recente (`txn_date` decrescente). `count` è limitato a 100; usa `total_transactions` per il conteggio effettivo delle righe. Questo endpoint non supporta parametri di filtro o di ricerca.", "operationId": "listTransactions", "x-didit-sdk": { "resource": "transactions", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Dimensione della pagina. Se omessa, il valore predefinito è 50. Non esiste un massimo imposto, ma mantieni le pagine piccole per ridurre la latenza." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Offset in base zero del primo record da restituire. È preferibile seguire l'URL `next` della pagina precedente." }, { "name": "travel_rule_status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restituisce solo le transazioni il cui trasferimento Travel Rule si trova esattamente in questo stato (ad esempio `ON_HOLD` o `AWAITING_COUNTERPARTY`). Il campo `count` segue questo filtro; `total_transactions` continua a conteggiare ogni transazione nell'applicazione." }, { "name": "assignee", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Valori separati da virgola; una transazione corrisponde quando soddisfa un qualsiasi valore. `unassigned` indica ciò che non è ancora assegnato a nessuno, `rules` indica ciò che le regole hanno deciso autonomamente senza un revisore e l'email di un membro corrisponde al revisore assegnato. `me` indica il revisore connesso alla Console, pertanto una chiave API che invia `me` riceve `400`." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.ListAutoPaging(ctx, didit.TransactionsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Elenco impaginato dei riepiloghi delle transazioni, dal più recente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Conteggio limitato delle transazioni corrispondenti (esatto fino a 100, poi limitato). Usa `total_transactions` per il conteggio effettivo durante la paginazione." }, "next": { "type": "string", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "total_transactions": { "type": "integer", "description": "Conteggio totale esatto delle transazioni (non eliminate) per l'applicazione. Presente nelle risposte paginate." }, "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificatore stabile della transazione Didit. Da usare come `{transaction_id}` nelle chiamate di dettaglio/note/correlate." }, "transaction_number": { "type": "integer", "description": "Numero sequenziale della transazione con ambito limitato all'applicazione mostrato nella Console (es. `4123`)." }, "txn_id": { "type": "string", "description": "Identificativo fornito dal cliente dalla chiamata di creazione (massimo 128 caratteri). Univoco per applicazione." }, "transaction_type": { "type": "string", "description": "Categoria di primo livello così come memorizzata: `finance`, `kyc`, `travelRule`, `userPlatformEvent`, `gamblingBet`, `gamblingLimitChange`, `gamblingBonusChange`, `auditTrailEvent`. Nota che i valori composti da più parole vengono restituiti in camelCase anche se inviati in snake_case." }, "action_type": { "type": "string", "description": "Sottotipo all'interno della categoria (ad es. `deposit`, `withdrawal`, `transfer`)." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Verdetto di monitoraggio attuale." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direzione rispetto al soggetto. Memorizzato in maiuscolo indipendentemente dal formato inviato." }, "amount": { "type": "string", "description": "Importo della transazione come stringa decimale senza zeri finali (es. `\"1500\"`, `\"0.5\"`, `\"0.123456789012345678\"`). Fino a 18 cifre decimali." }, "currency": { "type": "string", "description": "Codice valuta di `amount`. Viene accettato qualsiasi codice alfabetico ISO 4217 (ad es. `EUR`, `USD`, `NGN`), così come il simbolo di un asset crypto (ad es. `BTC`). È preferibile utilizzare un codice attualmente in circolazione. Non tutti i codici accettati hanno un tasso di cambio: quando non ne è disponibile alcuno per il codice (ad esempio l'unità di conto ISO `XSU` o un simbolo crypto di cui Didit non calcola il prezzo), la conversione automatica non riesce e `preferred_currency_amount` viene restituito null a meno che la richiesta non abbia fornito un `amount_in_default_currency` pre-convertito." }, "preferred_currency_amount": { "type": "string", "nullable": true, "description": "`amount` convertito nella valuta preferita dell'applicazione, se disponibile." }, "preferred_currency_code": { "type": "string", "nullable": true, "description": "Codice valuta preferito utilizzato per `preferred_currency_amount` - la valuta di base dell'applicazione, qualsiasi codice ISO 4217 attualmente in circolazione. Un codice senza tasso di cambio disponibile lascia `preferred_currency_amount` null a meno che la richiesta non abbia fornito un `amount_in_default_currency` pre-convertito." }, "payment_details": { "type": "string", "nullable": true, "description": "Riferimento di pagamento o promemoria in formato testo libero derivante dall'invio." }, "score": { "type": "integer", "description": "Punteggio di rischio (in genere 0–100). Più alto = più rischioso." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Gravità categoriale del rischio impostata da regole/provider (`UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`). `null` finché non viene impostata." }, "subject_name": { "type": "string", "nullable": true, "description": "Nome completo della parte `APPLICANT`." }, "subject_vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore interno utente/azienda per il richiedente." }, "subject_country": { "type": "string", "nullable": true, "description": "Codice del paese del richiedente, ricavato dal valore `address.country` inviato (in genere ISO 3166-1 alpha-3)." }, "counterparty_name": { "type": "string", "nullable": true, "description": "Nome completo della parte `COUNTERPARTY`, se presente." }, "counterparty_vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore interno per la controparte." }, "counterparty_country": { "type": "string", "nullable": true, "description": "Codice del paese della controparte, ricavato dal valore `address.country` inviato." }, "tags": { "type": "array", "description": "Tag associati alla transazione (manualmente o tramite regole).", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "Indica se il tag è predefinito da Didit o personalizzato." } } } }, "txn_date": { "type": "string", "format": "date-time", "description": "Quando è avvenuta la transazione (da `transaction_at` al momento della creazione)." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando Didit ha registrato l'invio." }, "decision_reason_code": { "type": "string", "nullable": true, "description": "Motivo leggibile dalla macchina per il `status` attuale (ad es. `WALLET_HIGH_RISK`)." }, "decision_reason_label": { "type": "string", "nullable": true, "description": "Etichetta di facile lettura per `decision_reason_code`." }, "assigned_to_name": { "type": "string", "nullable": true, "description": "Nome visualizzato del revisore della Console assegnato a questa transazione." }, "travel_rule_status": { "type": "string", "nullable": true, "description": "Stato del trasferimento Travel Rule della transazione (ad esempio `COMPLETED`), o `null` se non ne ha nessuno." }, "travel_rule": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TransactionTravelRule" } ], "description": "Il trasferimento Travel Rule della transazione, lo stesso blocco di `travel_rule` su `GET /v3/transactions/{transaction_id}/`, oppure `null` quando la transazione non ne ha alcuno." } } } } } }, "examples": { "Single transaction": { "value": { "count": 1, "next": null, "previous": null, "total_transactions": 1, "results": [ { "uuid": "abcdef12-3456-4890-abcd-ef1234567890", "transaction_number": 4123, "txn_id": "your-txn-2026-05-17-001", "transaction_type": "finance", "action_type": "withdrawal", "status": "IN_REVIEW", "direction": "OUTBOUND", "amount": "1500", "currency": "EUR", "preferred_currency_amount": "1620.45", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "txn_date": "2026-05-17T08:42:00Z", "created_at": "2026-05-17T08:42:11Z", "score": 78, "severity": "HIGH", "decision_reason_code": "WALLET_HIGH_RISK", "decision_reason_label": "Destination wallet flagged as high risk", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Manual review", "color": "#F59E0B", "description": null, "source": "custom" } ], "subject_name": "Maria Garcia", "subject_vendor_data": "user-12345", "counterparty_name": null, "counterparty_vendor_data": null, "counterparty_country": null, "subject_country": null, "assigned_to_name": "Alex Reviewer", "travel_rule_status": null, "travel_rule": null } ] } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può elencare le transazioni per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea transazione", "description": "Invia una transazione per il monitoraggio sincrono AML/del rischio. La transazione viene creata come `APPROVED`, poi le tue regole (e lo screening crypto, se applicabile) vengono eseguite inline e possono modificare lo `status` restituito in `IN_REVIEW` o `DECLINED`. **`transaction_id` è la tua chiave di idempotenza** (max 128 caratteri, univoca per app); riutilizzarla restituisce 400. Un webhook `transaction.created` viene inviato in caso di esito positivo per le applicazioni in produzione. Le applicazioni in sandbox non vengono fatturate e non emettono webhook `transaction.created` o `transaction.status.updated`. Gli scambi Travel Rule in sandbox emettono invece webhook `travel_rule.status.updated` con `environment: sandbox`. Un trasferimento Travel Rule viene memorizzato e restituito prima che qualsiasi controparte venga contattata: `travel_rule.status` restituisce `AWAITING_COUNTERPARTY` (o `NOT_APPLICABLE` sotto la tua soglia, `UNCONFIRMED_OWNERSHIP` per un wallet in autocustodia dichiarato, `COMPLETED` quando l'altro wallet è il tuo wallet verificato) e `travel_rule.protocol` è null. Didit sceglie quindi il canale e invia lo scambio, e ogni successiva modifica di stato del trasferimento, incluso `COUNTERPARTY_VASP_NOT_FOUND` quando nessun canale raggiunge la controparte, arriva come webhook `travel_rule.status.updated`. Le tue regole vengono eseguite nuovamente quando cambiano il canale o lo stato.", "operationId": "createTransaction", "tags": [ "Transactions" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"transaction_id\": \"your-txn-2026-05-17-001\",\n \"transaction_category\": \"finance\",\n \"transaction_details\": {\n \"direction\": \"outbound\",\n \"amount\": 1500,\n \"currency\": \"EUR\",\n \"action_type\": \"withdrawal\"\n },\n \"subject\": {\n \"entity_type\": \"individual\",\n \"vendor_data\": \"user-12345\",\n \"full_name\": \"Maria Garcia\"\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.create(\n transaction_id=\"your-txn-2026-05-17-001\",\n transaction_category=\"finance\",\n transaction_details={\n \"direction\": \"outbound\",\n \"amount\": 1500.0,\n \"currency\": \"EUR\",\n \"action_type\": \"withdrawal\",\n },\n subject={\n \"entity_type\": \"individual\",\n \"vendor_data\": \"user-12345\",\n \"full_name\": \"Maria Garcia\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.create({\n transaction_id: \"your-txn-2026-05-17-001\",\n transaction_category: \"finance\",\n transaction_details: {\n direction: \"outbound\",\n amount: 1500.0,\n currency: \"EUR\",\n action_type: \"withdrawal\",\n },\n subject: {\n entity_type: \"individual\",\n vendor_data: \"user-12345\",\n full_name: \"Maria Garcia\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Create(ctx, didit.TransactionsCreateParams{\n\tTransactionID: \"your-txn-2026-05-17-001\",\n\tTransactionCategory: \"finance\",\n\tTransactionDetails: didit.TransactionsCreateParamsTransactionDetails{\n\t\tDirection: \"outbound\",\n\t\tAmount: 1500.0,\n\t\tCurrency: \"EUR\",\n\t\tActionType: didit.String(\"withdrawal\"),\n\t},\n\tSubject: didit.TransactionsCreateParamsSubject{\n\t\tEntityType: didit.String(\"individual\"),\n\t\tVendorData: \"user-12345\",\n\t\tFullName: \"Maria Garcia\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().create(TransactionsCreateParams.builder()\n .transactionId(\"your-txn-2026-05-17-001\")\n .transactionCategory(TransactionsCreateParams.TransactionCategory.of(\"finance\"))\n .transactionDetails(TransactionsCreateParams.TransactionDetails.builder()\n .direction(TransactionsCreateParams.TransactionDetails.Direction.of(\"outbound\"))\n .amount(1500.0)\n .currency(\"EUR\")\n .actionType(\"withdrawal\")\n .build())\n .subject(TransactionsCreateParams.Subject.builder()\n .entityType(\"individual\")\n .vendorData(\"user-12345\")\n .fullName(\"Maria Garcia\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->create([\n 'transaction_id' => 'your-txn-2026-05-17-001',\n 'transaction_category' => 'finance',\n 'transaction_details' => [\n 'direction' => 'outbound',\n 'amount' => 1500.0,\n 'currency' => 'EUR',\n 'action_type' => 'withdrawal',\n ],\n 'subject' => [\n 'entity_type' => 'individual',\n 'vendor_data' => 'user-12345',\n 'full_name' => 'Maria Garcia',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.create(\n transaction_id: \"your-txn-2026-05-17-001\",\n transaction_category: \"finance\",\n transaction_details: {\n direction: \"outbound\",\n amount: 1500.0,\n currency: \"EUR\",\n action_type: \"withdrawal\",\n },\n subject: {\n entity_type: \"individual\",\n vendor_data: \"user-12345\",\n full_name: \"Maria Garcia\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.CreateAsync(new TransactionsCreateParams\n{\n TransactionId = \"your-txn-2026-05-17-001\",\n TransactionCategory = \"finance\",\n TransactionDetails = new()\n {\n Direction = \"outbound\",\n Amount = 1500.0,\n Currency = \"EUR\",\n ActionType = \"withdrawal\",\n },\n Subject = new()\n {\n EntityType = \"individual\",\n VendorData = \"user-12345\",\n FullName = \"Maria Garcia\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Il tuo identificatore univoco per questa transazione (massimo 128 caratteri).", "example": "your-txn-2026-05-17-001" }, "transaction_at": { "type": "string", "format": "date-time", "description": "Quando è avvenuta la transazione. Se omesso, il valore predefinito è adesso." }, "time_zone": { "type": "string", "description": "Identificatore di fuso orario IANA, ad es. `Europe/Madrid`." }, "transaction_category": { "type": "string", "description": "Categoria della transazione. Sono accettati anche alias CamelCase (`travelRule`, `userPlatformEvent`, `gamblingBet`, …); il valore memorizzato/restituito è in camelCase per le categorie composte da più parole.", "example": "finance", "enum": [ "finance", "kyc", "travel_rule", "user_event", "audit_trail_event", "gambling_bet", "gambling_limit_change", "gambling_bonus_change", "travelRule" ] }, "transaction_details": { "type": "object", "description": "Dettagli finanziari principali della transazione.", "required": [ "direction", "amount", "currency" ], "properties": { "direction": { "type": "string", "description": "Direzione della transazione rispetto al soggetto. Non fa distinzione tra maiuscole e minuscole; `in`/`out` sono accettati come alias. Restituito in maiuscolo (`INBOUND`/`OUTBOUND`).", "example": "outbound", "enum": [ "inbound", "outbound", "in", "out" ] }, "amount": { "type": "number", "description": "Importo della transazione (fino a 18 cifre decimali). Invialo come stringa decimale (es. `\"0.123456789012345678\"`) quando la precisione esatta è fondamentale: un numero JSON viene prima analizzato come float binario, quindi le cifre oltre circa 15 cifre significative vengono arrotondate prima che l'importo venga memorizzato. Deve essere pari o superiore a zero: la direzione determina il segno, e un importo negativo restituisce `400`.", "example": 1500 }, "currency": { "type": "string", "description": "Codice valuta. Viene accettato qualsiasi codice alfabetico ISO 4217 (ad es. `EUR`, `USD`, `NGN`), così come il simbolo di un asset crypto (ad es. `BTC`). È preferibile utilizzare un codice attualmente in circolazione. Non tutti i codici accettati hanno un tasso di cambio: quando non ne è disponibile alcuno per il codice (ad esempio l'unità di conto ISO `XSU` o un simbolo crypto di cui Didit non calcola il prezzo), la conversione automatica non riesce e `preferred_currency_amount` viene restituito null a meno che la richiesta non abbia fornito un `amount_in_default_currency` pre-convertito.", "example": "EUR" }, "currency_kind": { "type": "string", "description": "Indica se la valuta è `fiat` o `crypto`." }, "amount_in_default_currency": { "type": "number", "nullable": true, "description": "Importo pre-convertito nella valuta predefinita. Se omesso, viene tentata la conversione valutaria automatica. Deve essere maggiore o uguale a zero." }, "default_currency": { "type": "string", "description": "Il codice valuta predefinito per l'importo convertito. Qualsiasi codice ISO 4217 attualmente in circolazione." }, "payment_details": { "type": "string", "nullable": true, "description": "Riferimento di pagamento o promemoria in formato testo libero." }, "payment_reference_id": { "type": "string", "nullable": true, "description": "Riferimento del sistema di pagamento esterno. Per lo screening AML crypto basato su hash di transazione, invia l'hash della transazione blockchain e fornisci anche `subject.payment_method.account_id` con l'indirizzo correlato." }, "action_type": { "type": "string", "nullable": true, "description": "Sottotipo della transazione, ad es. `deposit`, `withdrawal`, `transfer`." }, "crypto_params": { "type": "object", "description": "Selezione della rete crypto, separata dalla valuta (il simbolo dell'asset). La registrazione di un simbolo di token personalizzato non garantisce la copertura dell'hash della transazione per il relativo smart contract.", "properties": { "crypto_chain": { "type": "string", "description": "Rete effettiva utilizzata per lo screening. Lo screening gestito supporta BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE (Base), OP (Optimism), ARB (Arbitrum One), AVAX (Avalanche C-Chain), ADA (Cardano), XLM (Stellar) e HBAR (Hedera). Sono accettati anche i nomi comuni delle reti, ad esempio POLYGON o POL per MATIC, BSC per BNB e TRON per TRX. Specificalo sempre per i token multi-rete. Quando non è presente per USDT, USDC o ETH inviati con un hash di transazione 0x, Didit cerca l'hash su Ethereum, BNB Chain, Polygon, Base, Arbitrum e Optimism ed esegue lo screening sulla rete in cui viene trovato; se nessuna rete lo contiene, la transazione non viene sottoposta a screening e custom_values.aml_screening_status è impostato su FAILED con il motivo in custom_values.aml_screening_error. Quando non è presente per USDT o USDC sottoposti a screening tramite wallet (senza hash di transazione), un indirizzo Tron viene esaminato su Tron, un indirizzo Solana su Solana e un indirizzo 0x sulla prima di queste sei reti in cui ha inviato una transazione o detiene il token, oppure su Ethereum se non è attivo su nessuna di esse. La copertura dei provider connessi varia; LIGHTNING richiede un provider connesso supportato.", "example": "BASE" } } } } }, "subject": { "type": "object", "description": "Il soggetto (richiedente) della transazione.", "required": [ "vendor_data", "full_name" ], "properties": { "entity_type": { "type": "string", "description": "Tipo di entità: `individual` o `company`." }, "vendor_data": { "type": "string", "description": "Il tuo identificatore interno utente/azienda.", "example": "user-12345" }, "full_name": { "type": "string", "description": "Nome completo del soggetto.", "example": "Maria Garcia" }, "first_name": { "type": "string", "description": "Nome del soggetto." }, "last_name": { "type": "string", "description": "Cognome del soggetto." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data di nascita (YYYY-MM-DD)." }, "address": { "type": "object", "description": "Oggetto indirizzo.", "properties": { "country": { "type": "string", "description": "Codice del paese (consigliato ISO 3166-1 alpha-3). Copiato nel `country_code` della parte." }, "town": { "type": "string" }, "state": { "type": "string" }, "street": { "type": "string" }, "post_code": { "type": "string" } } }, "institution_details": { "type": "object", "description": "Dati dell'istituto (per soggetti istituzionali).", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "address": { "type": "object" } } }, "device_context": { "type": "object", "description": "Contesto del dispositivo acquisito al momento della transazione. browser_family e platform devono essere inviati come chiavi esplicite di primo livello: non sono ricavati da user_agent. Nella richiesta è accettato anche l'alias in camelCase device.", "properties": { "fingerprint": { "type": "string", "description": "Impronta digitale univoca del dispositivo." }, "persistent_device_id": { "type": "string", "description": "Identificatore stabile del dispositivo tra sessioni diverse (schema di fingerprint v2)." }, "user_agent": { "type": "string", "description": "Stringa user agent del browser o dell'app. Alias in CamelCase: userAgent." }, "browser_family": { "type": "string", "description": "Famiglia del browser (es. Chrome, Firefox, Safari). Deve essere inviata esplicitamente — non è derivata da user_agent. Alias in CamelCase: browserFamily." }, "browser_version": { "type": "string", "description": "Stringa della versione del browser. Deve essere inviata esplicitamente. Alias in CamelCase: browserVersion." }, "platform": { "type": "string", "description": "Identificatore della piattaforma (web, ios, android, macos, windows, linux). Deve essere inviato esplicitamente — non viene derivato da user_agent." }, "os_family": { "type": "string", "description": "Famiglia del sistema operativo (ad es. iOS, Android, Windows). Alias CamelCase: osFamily." }, "os_version": { "type": "string", "description": "Stringa della versione del sistema operativo. Alias CamelCase: osVersion." }, "accept_language": { "type": "string", "description": "Valore dell'intestazione Accept-Language. Alias camelCase: acceptLang." }, "session_id": { "type": "string", "description": "Identificatore di sessione della sessione corrente dell'utente. Memorizzato nei metadati. Alias camelCase: sessionId." }, "session_age_ms": { "type": "number", "description": "Età della sessione utente in millisecondi al momento della transazione. Alias CamelCase: sessionAgeMs." }, "network_context": { "type": "object", "description": "Contesto di rete con indirizzo IP e geolocalizzazione. Anche un blocco ipInfo di livello principale è incluso in questo oggetto.", "properties": { "ip_address": { "type": "string", "description": "Indirizzo IP del client. Alias CamelCase: ip." }, "ip_country_code": { "type": "string", "description": "Paese geolocalizzato dell'IP (ISO 3166-1 alpha-3). Alias CamelCase: countryCode3." }, "latitude": { "type": "number", "description": "Latitudine geografica dell'IP. Alias CamelCase: lat." }, "longitude": { "type": "number", "description": "Longitudine geografica dell'IP. Alias CamelCase: lon." } } } } }, "payment_method": { "type": "object", "description": "Metodo di pagamento usato dal soggetto.", "properties": { "method_type": { "type": "string", "description": "Tipo di metodo di pagamento: `bank_card`, `bank_account`, `crypto_wallet`, `ewallet`, `unhosted_wallet`, `other`." }, "account_id": { "type": "string", "description": "Identificativo dell'account (ad es. IBAN, indirizzo). Per lo screening delle criptovalute, questo campo deve contenere l'indirizzo per questo partecipante. Lo screening dell'hash della transazione in entrata richiede l'indirizzo di deposito del servizio/cliente del soggetto. Lo screening in uscita utilizza il wallet di destinazione della controparte. Su un trasferimento crypto su bitcoin o Lightning può essere una richiesta di pagamento Lightning (fattura BOLT11, offerta BOLT12, LNURL) o un Lightning Address: Didit memorizza il beneficiario indicato come account (\"\" quando non ne indica alcuno) e il contenuto della richiesta in `chain_details.lightning` del trasferimento Travel Rule. Massimo 255 caratteri una volta memorizzato. Su un trasferimento crypto su bitcoin o Lightning può essere una richiesta di pagamento Lightning (fattura BOLT11, offerta BOLT12, LNURL) o un Lightning Address: Didit memorizza il beneficiario indicato come account (\"\" quando non ne indica alcuno) e il contenuto della richiesta in `chain_details.lightning` del trasferimento Travel Rule. Massimo 255 caratteri una volta memorizzato." }, "memo": { "type": "string", "maxLength": 256, "description": "Il destination tag o memo che fa parte del wallet su una rete con memo (XRP, XLM, EOS, ATOM, HBAR). Su un unico indirizzo di exchange condiviso, ciascun memo costituisce un metodo di pagamento a sé stante. XRP: un destination tag, un numero intero da 0 a 4294967295 (è accettato un numero JSON). XLM: un memo di testo fino a 28 byte, un ID a 64 bit o un hash a 32 byte in formato esadecimale. EOS: fino a 256 byte. ATOM: fino a 256 caratteri. HBAR: fino a 100 byte. I wallet Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning non accettano alcun memo: specificarne uno restituisce un errore `400`. Alias: `destinationTag` o `destination_tag`." }, "issuing_country": { "type": "string", "description": "Codice paese ISO 3166-1 alpha-3 dell'emittente." } } } } }, "counterparty": { "type": "object", "description": "La controparte della transazione (opzionale).", "properties": { "entity_type": { "type": "string", "description": "Tipo di entità: `individual` o `company`." }, "vendor_data": { "type": "string", "description": "Il tuo identificatore interno per la controparte." }, "full_name": { "type": "string", "description": "Nome completo della controparte." }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "address": { "type": "object", "description": "Oggetto indirizzo con `country` (ISO 3166-1 alpha-3)." }, "institution_details": { "type": "object" }, "device_context": { "type": "object", "description": "Contesto del dispositivo per la controparte. browser_family e platform devono essere inviati come chiavi esplicite di primo livello — non sono derivati da user_agent.", "properties": { "fingerprint": { "type": "string", "description": "Impronta digitale univoca del dispositivo." }, "persistent_device_id": { "type": "string", "description": "Identificatore stabile del dispositivo tra sessioni diverse (schema di fingerprint v2)." }, "user_agent": { "type": "string", "description": "Stringa user agent del browser o dell'app. Alias in CamelCase: userAgent." }, "browser_family": { "type": "string", "description": "Famiglia del browser (es. Chrome, Firefox, Safari). Deve essere inviata esplicitamente — non è derivata da user_agent. Alias in CamelCase: browserFamily." }, "browser_version": { "type": "string", "description": "Stringa della versione del browser. Deve essere inviata esplicitamente. Alias in CamelCase: browserVersion." }, "platform": { "type": "string", "description": "Identificatore della piattaforma (web, ios, android, macos, windows, linux). Deve essere inviato esplicitamente — non viene derivato da user_agent." }, "os_family": { "type": "string", "description": "Famiglia del sistema operativo (ad es. iOS, Android, Windows). Alias CamelCase: osFamily." }, "os_version": { "type": "string", "description": "Stringa della versione del sistema operativo. Alias CamelCase: osVersion." }, "accept_language": { "type": "string", "description": "Valore dell'intestazione Accept-Language. Alias camelCase: acceptLang." }, "session_id": { "type": "string", "description": "Identificatore di sessione per la sessione della controparte. Memorizzato nei metadati. Alias camelCase: sessionId." }, "session_age_ms": { "type": "number", "description": "Età della sessione utente in millisecondi al momento della transazione. Alias CamelCase: sessionAgeMs." }, "network_context": { "type": "object", "description": "Contesto di rete con indirizzo IP e geolocalizzazione. Anche un blocco ipInfo di livello principale è incluso in questo oggetto.", "properties": { "ip_address": { "type": "string", "description": "Indirizzo IP del client. Alias CamelCase: ip." }, "ip_country_code": { "type": "string", "description": "Paese geolocalizzato dell'IP (ISO 3166-1 alpha-3). Alias CamelCase: countryCode3." }, "latitude": { "type": "number", "description": "Latitudine geografica dell'IP. Alias CamelCase: lat." }, "longitude": { "type": "number", "description": "Longitudine geografica dell'IP. Alias CamelCase: lon." } } } } }, "payment_method": { "type": "object", "description": "Metodo di pagamento usato dalla controparte. Nelle transazioni travelRule, `method_type: \"unhosted_wallet\"` dichiara il wallet della controparte come in autocustodia: il trasferimento salta l'instradamento verso il VASP della controparte, viene creato direttamente in `UNCONFIRMED_OWNERSHIP` e (quando `auto_wallet_verification` è abilitato) viene generata automaticamente una sessione del widget di proprietà del wallet restituita nel blocco `action_required` della transazione.", "properties": { "method_type": { "type": "string", "description": "Tipo di metodo di pagamento: `bank_card`, `bank_account`, `crypto_wallet`, `ewallet`, `unhosted_wallet`, `other`. Usa `unhosted_wallet` per dichiarare un wallet in autocustodia per la Travel Rule." }, "account_id": { "type": "string", "description": "Identificativo dell'account (ad es. IBAN o indirizzo). In un trasferimento di criptovaluta su Bitcoin o Lightning può essere una richiesta di pagamento Lightning (fattura BOLT11, offerta BOLT12, LNURL) o un Lightning Address: Didit memorizza il beneficiario indicato come account (\"\" quando non ne indica alcuno) e il contenuto della richiesta in `chain_details.lightning` del trasferimento Travel Rule. Massimo 255 caratteri una volta memorizzato. In un trasferimento di criptovaluta su Bitcoin o Lightning può essere una richiesta di pagamento Lightning (fattura BOLT11, offerta BOLT12, LNURL) o un Lightning Address: Didit memorizza il beneficiario indicato come account (\"\" quando non ne indica alcuno) e il contenuto della richiesta in `chain_details.lightning` del trasferimento Travel Rule. Massimo 255 caratteri una volta memorizzato." }, "memo": { "type": "string", "maxLength": 256, "description": "Il destination tag o memo che fa parte del wallet su una rete con memo (XRP, XLM, EOS, ATOM, HBAR). Su un unico indirizzo di exchange condiviso, ciascun memo costituisce un metodo di pagamento a sé stante. XRP: un destination tag, un numero intero da 0 a 4294967295 (è accettato un numero JSON). XLM: un memo di testo fino a 28 byte, un ID a 64 bit o un hash a 32 byte in formato esadecimale. EOS: fino a 256 byte. ATOM: fino a 256 caratteri. HBAR: fino a 100 byte. I wallet Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning non accettano alcun memo: specificarne uno restituisce un errore `400`. Alias: `destinationTag` o `destination_tag`." }, "issuing_country": { "type": "string" } } } } }, "custom_properties": { "type": "object", "description": "Coppie chiave-valore arbitrarie allegate alla transazione. Ciascuna chiave può essere richiamata nelle condizioni delle regole con il percorso di campo `custom_values.`.", "additionalProperties": true, "example": { "merchant_id": "test", "bank_name": "test_2" } }, "travel_rule_details": { "type": "object", "description": "Dati Travel Rule. Quando Travel Rule è abilitata e transaction_category è travel_rule, Didit gestisce lo scambio direttamente: ignora status, protocol, required e obligations_count e utilizza originator_data, beneficiary_data e metadata. Altrimenti Didit memorizza questi valori come record Travel Rule passivo. Quando Travel Rule è attiva, un trasferimento in uscita pari o superiore alla soglia deve includere quanto richiesto dal relativo regime (TFR UE o Raccomandazione 16 del GAFI), verificato sulle parti inviate: un campo mancante restituisce 400 sotto `travel_rule_details.originator_data` o `travel_rule_details.beneficiary_data`, ad esempio \"Il TFR UE richiede il nome dell'ordinante.\"", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Obbligatorio ogni volta che si invia travel_rule_details. Uno degli stati del trasferimento Travel Rule (ad esempio AWAITING_COUNTERPARTY, COMPLETED, NOT_APPLICABLE); sono accettate e mappate anche le grafie minuscole e camelCase nonché i valori legacy UNKNOWN, COMPLIANT, PENDING_ACTION, PENDING_COUNTERPARTY, FAILED ed EXEMPT. Qualsiasi altro valore restituisce 400." }, "protocol": { "type": "string" }, "required": { "type": "boolean" }, "obligations_count": { "type": "integer" }, "originator_data": { "type": "object", "description": "Soggetto ordinante, come campi piatti o come una singola persona IVMS 101. Per il tuo utente con una verifica KYC approvata, Didit sostituisce i campi contenuti nella verifica con i valori verificati (vedi `metadata.originator_provenance`). Deve essere un oggetto: qualsiasi altro valore restituisce un `400`. Su una rete basata su memo, la chiave `memo` indica il memo o il tag del wallet dell'ordinante." }, "beneficiary_data": { "type": "object", "description": "Parte beneficiaria, come campi piatti o una singola persona IVMS 101. Deve essere un oggetto: qualsiasi altra cosa restituisce `400`. Per instradare il trasferimento, Didit legge `wallet_address` (se vuoto viene compilato da `counterparty.payment_method.account_id`), `chain` (compilato da `transaction_details.crypto_params.crypto_chain` o da `currency` quando quest'ultima indica una chain supportata), `name` (con fallback su `counterparty.full_name`), `travel_address`, `counterparty_vasp_name`, `counterparty_vasp_lei` e `counterparty_vasp_email`. Su una rete con memo, `memo` indica il memo o il tag del wallet del beneficiario; `wallet_address` e `memo` hanno la precedenza sul metodo di pagamento della controparte." }, "metadata": { "type": "object" }, "utxo": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleUtxo" } ], "description": "Opzionale, solo per blockchain UTXO (BTC, LTC, BCH, DOGE). Gli input e gli output della transazione, da cui Didit deduce il wallet dell'ordinante e l'output del beneficiario quando non li dichiari." }, "originator": { "type": "object", "description": "Un blocco dell'ordinante IVMS 101: `originatorPersons` (una `naturalPerson` o `legalPerson`; una persona giuridica rende la parte un'azienda) e `accountNumber` (indirizzi del wallet). Utilizzato per `originator_data` quando tale oggetto è vuoto. Un blocco non valido risponde con 400 indicizzato dal relativo percorso, ad esempio `originator.originatorPersons`." }, "beneficiary": { "type": "object", "description": "Un blocco del beneficiario IVMS 101: `beneficiaryPersons` (una `naturalPerson` o `legalPerson`; una persona giuridica rende la parte un'azienda) e `accountNumber` (indirizzi del wallet). Utilizzato per `beneficiary_data` quando tale oggetto è vuoto. Un blocco non valido risponde con 400 indicizzato dal relativo percorso, ad esempio `beneficiary.beneficiaryPersons`." }, "ivms101": { "type": "object", "description": "I blocchi `originator` e `beneficiary` racchiusi in un singolo oggetto IVMS 101 (è accettato anche `IVMS101`). I blocchi di primo livello hanno la precedenza su quelli dell'involucro." } } }, "network_snapshot": { "type": "object", "description": "Istantanea precalcolata del grafo di rete.", "properties": { "nodes": { "type": "array", "items": { "type": "object" } }, "edges": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "object" } } }, "include_crypto_screening": { "type": "boolean", "nullable": true, "description": "Sostituzione per singola transazione per lo screening di analisi della blockchain crypto. Quando è `true`, lo screening crypto viene eseguito indipendentemente dal valore predefinito dell'applicazione. Quando è `false`, lo screening crypto viene saltato anche se abilitato nelle impostazioni dell'applicazione. Se omesso o `null`, viene utilizzato il valore predefinito a livello di applicazione configurato nella Console. Lo screening crypto richiede `transaction_details.direction`, `currency_kind: \"crypto\"`, una blockchain/valuta e l'indirizzo del wallet selezionato in base alla direzione: lo screening in entrata pre-trasferimento utilizza `counterparty.payment_method.account_id`, lo screening in entrata con hash di transazione utilizza `subject.payment_method.account_id`, e lo screening in uscita utilizza `counterparty.payment_method.account_id`. Quando `transaction_details.payment_reference_id` contiene l'hash di una transazione blockchain, Didit esegue lo screening della transazione e restituisce l'arricchimento del riepilogo della transazione quando disponibile." } }, "required": [ "transaction_id", "transaction_category", "transaction_details", "subject" ] }, "examples": { "Minimal fiat withdrawal": { "summary": "Payload minimo accettabile per un trasferimento fiat in uscita", "value": { "transaction_id": "your-txn-2026-05-17-001", "transaction_category": "finance", "transaction_details": { "direction": "outbound", "amount": 1500, "currency": "EUR", "action_type": "withdrawal" }, "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia" } } }, "Crypto outbound with screening": { "summary": "Prelievo crypto in uscita verso un wallet in autocustodia, screening opzionale", "value": { "transaction_id": "your-txn-2026-05-17-002", "transaction_category": "finance", "include_crypto_screening": true, "transaction_details": { "direction": "outbound", "amount": 0.5, "currency": "BTC", "currency_kind": "crypto", "amount_in_default_currency": 32500, "default_currency": "USD", "action_type": "withdrawal" }, "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "payment_method": { "method_type": "crypto_wallet", "account_id": "bc1qexampleexchangewalletaddressxyz", "issuing_country": "ESP" } }, "counterparty": { "entity_type": "individual", "payment_method": { "method_type": "unhosted_wallet", "account_id": "bc1qexampleexternalwalletaddressabc" } } } }, "Travel Rule transfer": { "summary": "Trasferimento crypto in uscita con dati dell'ordinante/beneficiario per la Travel Rule", "value": { "transaction_id": "your-txn-2026-05-17-003", "transaction_category": "travel_rule", "transaction_details": { "direction": "outbound", "amount": 25000, "currency": "USDT", "currency_kind": "crypto", "action_type": "transfer" }, "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "date_of_birth": "1992-03-14", "address": { "country": "ESP", "town": "Madrid", "street": "Calle Mayor 1", "post_code": "28013" } }, "counterparty": { "entity_type": "individual", "full_name": "John Beneficiary", "institution_details": { "name": "Beneficiary VASP, Inc.", "code": "BVASP-US" } }, "travel_rule_details": { "status": "AWAITING_COUNTERPARTY", "protocol": "IVMS101", "required": true, "originator_data": { "name": "Maria Garcia" }, "beneficiary_data": { "name": "John Beneficiary" } } } } } } } }, "responses": { "201": { "description": "Transazione inviata e monitorata. Il corpo contiene il dettaglio completo della transazione (stessa struttura di `GET /v3/transactions/{transaction_id}/`), che riflette gli esiti delle regole già applicati.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "examples": { "Approved with no rule hits": { "value": { "uuid": "abcdef12-3456-4890-abcd-ef1234567890", "environment": "live", "transaction_number": 4123, "txn_id": "your-txn-2026-05-17-001", "txn_date": "2026-05-17T08:42:00Z", "zone_id": "Europe/Madrid", "transaction_type": "finance", "action_type": "withdrawal", "direction": "OUTBOUND", "status": "APPROVED", "source": "LIVE", "amount": "1500", "currency": "EUR", "currency_type": "fiat", "amount_in_default_currency": "1620.45", "default_currency_code": "USD", "preferred_currency_amount": "1620.45", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "payment_txn_id": null, "score": 0, "severity": null, "decision_reason_code": null, "decision_reason_label": null, "vendor_data": "user-12345", "metadata": { "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "address": {}, "institution_details": {}, "device_context": {} }, "counterparty": {} }, "props": {}, "tags": [], "parties": [ { "uuid": "b1111111-2222-4333-8444-555555555555", "role": "APPLICANT", "entity_type": "individual", "kind": "USER", "vendor_data": "user-12345", "full_name": "Maria Garcia", "first_name": null, "last_name": null, "country_code": null, "dob": null, "address": {}, "institution_info": {}, "device": {}, "external_party_snapshot": null } ], "payment_methods": [], "documents": [], "activities": [ { "uuid": "d4e5f6a7-8901-4bcd-9ef0-123456789abc", "activity_type": "TRANSACTION_CREATED", "source": "TRANSACTION", "status": "APPROVED", "title": "withdrawal", "description": "Transaction recorded.", "metadata": {}, "occurred_at": "2026-05-17T08:42:11Z" } ], "alerts": [], "rule_runs": [], "provider_results": [], "travel_rule": null, "network_snapshot": null, "remediation": null, "action_required": null, "cost_breakdown": null } }, "Flagged for review": { "value": { "uuid": "abcdef12-3456-4890-abcd-ef1234567891", "environment": "live", "transaction_number": 4124, "txn_id": "your-txn-2026-05-17-002", "txn_date": "2026-05-17T08:42:00Z", "zone_id": "Europe/Madrid", "transaction_type": "finance", "action_type": "withdrawal", "direction": "OUTBOUND", "status": "IN_REVIEW", "source": "LIVE", "amount": "0.5", "currency": "BTC", "currency_type": "crypto", "amount_in_default_currency": "32500", "default_currency_code": "USD", "preferred_currency_amount": "32500", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "payment_txn_id": null, "score": 78, "severity": "HIGH", "decision_reason_code": "WALLET_HIGH_RISK", "decision_reason_label": "Destination wallet flagged as high risk", "vendor_data": "user-12345", "metadata": { "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "address": {}, "institution_details": {}, "device_context": {} }, "counterparty": {} }, "props": { "order_id": "ord-9988" }, "tags": [], "parties": [ { "uuid": "b1111111-2222-4333-8444-555555555555", "role": "APPLICANT", "entity_type": "individual", "kind": "USER", "vendor_data": "user-12345", "full_name": "Maria Garcia", "first_name": null, "last_name": null, "country_code": null, "dob": null, "address": {}, "institution_info": {}, "device": {}, "external_party_snapshot": null } ], "payment_methods": [], "documents": [], "activities": [], "alerts": [ { "uuid": "a7b8c9d0-1234-4abc-9def-567890abcdef", "title": "Destination wallet flagged as high risk", "description": "Provider risk score exceeded the configured threshold.", "severity": "HIGH", "status": "OPEN", "source": "RULE", "metadata": {}, "created_at": "2026-05-17T08:42:12Z", "due_at": null } ], "rule_runs": [ { "uuid": "e5f6a7b8-9012-4cde-af01-23456789abcd", "rule": "f6a7b8c9-0123-4def-b012-3456789abcde", "rule_title": "High-risk wallet screening", "rule_description": null, "rule_category": "crypto", "matched": true, "is_test": false, "mode": "ACTIVE", "severity": "HIGH", "score_delta": 78, "status_target": "IN_REVIEW", "action_summary": "score +78; change_status:IN_REVIEW", "metadata": {}, "created_at": "2026-05-17T08:42:12Z" } ], "provider_results": [], "travel_rule": null, "network_snapshot": null, "remediation": null, "action_required": null, "cost_breakdown": null } } } } } }, "400": { "description": "Validazione non riuscita (campi obbligatori mancanti, `transaction_id` duplicato, valore enum sconosciuto, valuta non valida, ecc.).", "content": { "application/json": { "examples": { "Missing required field": { "value": { "transaction_details": { "amount": [ "This field is required." ] } } }, "Duplicate transaction_id": { "value": { "transaction_id": [ "A transaction with this transaction_id already exists." ] } }, "Invalid category": { "value": { "non_field_errors": [ "Unsupported transaction category." ] } }, "Missing subject identity": { "value": { "subject": [ "subject.vendor_data and subject.full_name are required." ] } }, "Blocklisted participant": { "value": { "vendor_data": [ "The individual 'user-12345' is in the blocklist and cannot participate in transactions." ] } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può inviare transazioni per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "409": { "description": "Un'altra richiesta con lo stesso `transaction_id` ha creato la transazione mentre questa era in fase di elaborazione, quindi solo uno dei due invii simultanei ha esito positivo. Leggi la transazione esistente invece di inviarla nuovamente.", "content": { "application/json": { "examples": { "Concurrent duplicate": { "value": { "detail": "A transaction with this transaction_id already exists." } } } } } }, "429": { "description": "Limite di frequenza superato: le creazioni di transazioni e l'ingestione di eventi (`POST /v3/transactions/`, `POST /v3/events/`, `POST /v3/events/batch/`) condividono un budget di 600 richieste al minuto per chiave API, separato dalle 300 condivise da tutte le altre richieste di scrittura. Attendi `Retry-After` secondi, quindi riprova.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di riprovare, arrotondati per eccesso in modo che il nuovo tentativo rientri nella finestra successiva.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Ingestion rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-didit-sdk": { "resource": "transactions", "method": "create", "auth": "api_key", "server": true } } }, "/v3/transactions/{transaction_id}/": { "get": { "summary": "Recupera transazione", "description": "Recupera il record di monitoraggio completo per una transazione: parti, punteggio/gravità, esecuzioni delle regole, alert, esito della Travel Rule, sessione di intervento correttivo.", "operationId": "getTransaction", "x-didit-sdk": { "resource": "transactions", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID della transazione stabile di Didit (lo `uuid` restituito da create / list, **non** il tuo `txn_id`).", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.retrieve(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.retrieve(\"abcdef12-3456-7890-abcd-ef1234567890\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Retrieve(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().retrieve(\"abcdef12-3456-7890-abcd-ef1234567890\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->retrieve('abcdef12-3456-7890-abcd-ef1234567890');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.retrieve(\"abcdef12-3456-7890-abcd-ef1234567890\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.RetrieveAsync(\"abcdef12-3456-7890-abcd-ef1234567890\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Dettaglio completo della transazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "examples": { "In review with an alert": { "value": { "uuid": "abcdef12-3456-4890-abcd-ef1234567890", "environment": "live", "transaction_number": 4123, "txn_id": "your-txn-2026-05-17-001", "txn_date": "2026-05-17T08:42:00Z", "zone_id": "Europe/Madrid", "transaction_type": "finance", "action_type": "withdrawal", "direction": "OUTBOUND", "status": "IN_REVIEW", "source": "LIVE", "amount": "1500", "currency": "EUR", "currency_type": "fiat", "amount_in_default_currency": "1620.45", "default_currency_code": "USD", "preferred_currency_amount": "1620.45", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "payment_txn_id": null, "score": 78, "severity": "HIGH", "decision_reason_code": "WALLET_HIGH_RISK", "decision_reason_label": "Destination wallet flagged as high risk", "vendor_data": "user-12345", "metadata": { "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "address": {}, "institution_details": {}, "device_context": {} }, "counterparty": {} }, "props": { "order_id": "ord-9988" }, "tags": [], "parties": [ { "uuid": "b1111111-2222-4333-8444-555555555555", "role": "APPLICANT", "entity_type": "individual", "kind": "USER", "vendor_data": "user-12345", "full_name": "Maria Garcia", "first_name": null, "last_name": null, "country_code": null, "dob": null, "address": {}, "institution_info": {}, "device": {}, "external_party_snapshot": null } ], "payment_methods": [], "documents": [], "activities": [], "alerts": [ { "uuid": "a7b8c9d0-1234-4abc-9def-567890abcdef", "title": "Destination wallet flagged as high risk", "description": "Provider risk score exceeded the configured threshold.", "severity": "HIGH", "status": "OPEN", "source": "RULE", "metadata": {}, "created_at": "2026-05-17T08:42:12Z", "due_at": null } ], "rule_runs": [], "provider_results": [], "travel_rule": null, "network_snapshot": null, "remediation": null, "action_required": null, "cost_breakdown": null } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può leggere le transazioni di questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessuna transazione con questo UUID esiste per l'applicazione (eliminata, mai creata, appartenente a un'altra applicazione, oppure il segmento di percorso non è un UUID valido).", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/sdk-token/": { "post": { "summary": "Genera un token di transazione per l'SDK", "description": "Genera un token con ambito limitato e di breve durata che la tua app trasmette agli SDK di Didit per consentire l'invio delle transazioni direttamente dal dispositivo dell'utente finale tramite `POST /v1/transactions/`. Il token è associato a un singolo `vendor_data` (l'ID del tuo utente): per ogni transazione inviata tramite esso, l'identità del soggetto viene applicata lato server a partire da tale associazione, impedendo a un client manomesso di inviare dati per conto di un altro utente. Genera i token dal tuo backend; non inserire mai la chiave API stessa all'interno di un'app. Sono accettati anche gli alias in camelCase (`vendorData`, `ttlSeconds`, `maxUses`).", "operationId": "createTransactionSdkToken", "x-didit-sdk": { "resource": "transactions", "method": "create_sdk_token", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendor_data": { "type": "string", "description": "Il tuo identificatore interno per l'utente finale a cui è limitato questo token. Imposto come identità del soggetto di ogni transazione inviata con il token.", "example": "user-042" }, "ttl_seconds": { "type": "integer", "default": 900, "maximum": 86400, "description": "Durata del token in secondi. Il valore predefinito è 900 (15 minuti); massimo 86400 (24 ore)." }, "max_uses": { "type": "integer", "nullable": true, "description": "Numero massimo di invii riusciti consentiti con questo token. Omettere o impostare su null per utilizzi illimitati entro il TTL." } }, "required": [ "vendor_data" ] }, "example": { "vendor_data": "user-042", "ttl_seconds": 900, "max_uses": 3 } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/transactions/sdk-token/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"vendor_data\": \"user-042\", \"ttl_seconds\": 900, \"max_uses\": 3}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.create_sdk_token(\n vendor_data=\"user-042\",\n ttl_seconds=900,\n max_uses=3,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.createSdkToken({\n vendor_data: \"user-042\",\n ttl_seconds: 900,\n max_uses: 3,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.CreateSDKToken(ctx, didit.TransactionsCreateSDKTokenParams{\n\tVendorData: \"user-042\",\n\tTTLSeconds: didit.Int(900),\n\tMaxUses: didit.Int(3),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionsCreateSdkTokenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().createSdkToken(TransactionsCreateSdkTokenParams.builder()\n .vendorData(\"user-042\")\n .ttlSeconds(900L)\n .maxUses(3L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->createSdkToken([\n 'vendor_data' => 'user-042',\n 'ttl_seconds' => 900,\n 'max_uses' => 3,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.create_sdk_token(\n vendor_data: \"user-042\",\n ttl_seconds: 900,\n max_uses: 3\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.CreateSdkTokenAsync(new TransactionsCreateSdkTokenParams\n{\n VendorData = \"user-042\",\n TtlSeconds = 900,\n MaxUses = 3,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Il token emesso. Passa `sdk_token` alla tua app; autentica gli endpoint `/v1/transactions/` rivolti al dispositivo tramite l'intestazione `X-Transaction-Token` fino a `expires_at`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sdk_token": { "type": "string", "description": "Il token di transazione con ambito da passare all'SDK." }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando il token smette di essere accettato." } } }, "example": { "sdk_token": "q7Zt...urlsafe", "expires_at": "2026-07-07T12:15:00Z" } } } }, "400": { "description": "Validazione non riuscita: `vendor_data` mancante o `ttl_seconds` al di fuori dell'intervallo consentito.", "content": { "application/json": { "examples": { "Missing vendor_data": { "value": { "vendor_data": [ "This field is required." ] } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata.", "content": { "application/json": { "examples": { "Invalid API Key": { "value": { "detail": "Invalid API Key." } } } } } } } } }, "/v1/transactions/": { "post": { "summary": "Invia una transazione da un SDK", "description": "Endpoint lato dispositivo chiamato dagli SDK di Didit per inviare una transazione direttamente dal dispositivo dell'utente finale. L'autenticazione avviene tramite un token con ambito generato da `POST /v3/transactions/sdk-token/` inviato nell'intestazione `X-Transaction-Token` al posto di una chiave API, e l'endpoint è abilitato a CORS in modo che i browser possano chiamarlo in modalità cross-origin. Il payload utilizza gli alias di trasmissione in camelCase mostrati di seguito (i metodi `submitTransaction` dell'SDK lo compongono automaticamente). Tre garanzie lato server: l'applicazione viene sempre ricavata dal token; l'identità del soggetto (`externalUserId`) è sempre imposta a partire dal `vendor_data` del token, ignorando quindi i valori spoofati nel payload; e la device intelligence (il fingerprint del dispositivo dell'SDK oltre a IP e user agent derivati dal server) viene allegata automaticamente al soggetto.", "operationId": "submitTransactionFromSdk", "x-didit-sdk": { "resource": "transactions", "method": "submit_from_device", "auth": "device_token", "server": false }, "tags": [ "Transactions" ], "security": [ { "TransactionTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "txnId": { "type": "string", "description": "Il tuo identificatore univoco per questa transazione (corrisponde a `transaction_id`, massimo 128 caratteri).", "example": "wd-2026-07-07-0042" }, "txnDate": { "type": "string", "format": "date-time", "description": "Quando è avvenuta la transazione (corrisponde a `transaction_at`). Se omesso, il valore predefinito è adesso." }, "zoneId": { "type": "string", "description": "Identificatore di fuso orario IANA (mappato a `time_zone`), ad es. `Europe/Madrid`." }, "type": { "type": "string", "description": "Categoria della transazione (corrisponde a `transaction_category`), es. `finance`, `kyc`, `travelRule`, `userPlatformEvent`, `gamblingBet`.", "example": "travelRule" }, "info": { "type": "object", "description": "Dettagli finanziari principali della transazione (mappati su `transaction_details`).", "required": [ "direction", "amount", "currency" ], "properties": { "direction": { "type": "string", "description": "Direzione rispetto al soggetto. Non fa distinzione tra maiuscole e minuscole; `in`/`out` sono accettati come alias. Restituito in maiuscolo (`INBOUND`/`OUTBOUND`).", "example": "out" }, "amount": { "type": "number", "description": "Importo della transazione (fino a 18 cifre decimali). Viene accettata anche una stringa decimale, ed è l'unico modo per preservare più di circa 15 cifre significative: un numero JSON viene prima analizzato come float binario, quindi `0.123456789012345678` viene memorizzato come `0.12345678901234568`.", "example": 0.25 }, "currency": { "type": "string", "description": "Codice valuta. Viene accettato qualsiasi codice alfabetico ISO 4217 (ad es. `EUR`, `USD`, `NGN`), così come il simbolo di un asset crypto (ad es. `BTC`). È preferibile utilizzare un codice attualmente in circolazione. Non tutti i codici accettati hanno un tasso di cambio: quando non ne è disponibile alcuno per il codice (ad esempio l'unità di conto ISO `XSU` o un simbolo crypto di cui Didit non calcola il prezzo), la conversione automatica non riesce e `preferred_currency_amount` viene restituito null a meno che la richiesta non abbia fornito un `amountInDefaultCurrency` pre-convertito.", "example": "ETH" }, "currencyType": { "type": "string", "description": "Indica se la valuta è `fiat` o `crypto` (corrisponde a `currency_kind`)." }, "amountInDefaultCurrency": { "type": "number", "nullable": true, "description": "Importo pre-convertito nella valuta predefinita (corrisponde a `amount_in_default_currency`). Se omesso, viene tentata la conversione valutaria automatica." }, "defaultCurrencyCode": { "type": "string", "description": "Il codice valuta predefinito per l'importo convertito (mappato su `default_currency`). Qualsiasi codice ISO 4217 attualmente in circolazione." }, "paymentDetails": { "type": "string", "nullable": true, "description": "Riferimento di pagamento o promemoria in formato testo libero (corrisponde a `payment_details`)." }, "paymentTxnId": { "type": "string", "nullable": true, "description": "Riferimento di pagamento esterno (mappato su `payment_reference_id`); l'hash della transazione on-chain per le transazioni crypto." }, "type": { "type": "string", "nullable": true, "description": "Sottotipo della transazione (mappato su `action_type`), ad es. `deposit`, `withdrawal`, `transfer`." }, "cryptoParams": { "type": "object", "description": "Parametri specifici per le crypto, ad es. `{\"crypto_chain\": \"ETH\"}`." } } }, "subject": { "type": "object", "description": "Il soggetto (richiedente) della transazione. `externalUserId` viene ignorato qui: l'identità del soggetto viene sempre vincolata in base a `vendor_data` del token.", "required": [ "fullName" ], "properties": { "type": { "type": "string", "description": "Tipo di entità (mappato su `entity_type`): `individual` (predefinito) o `company`." }, "externalUserId": { "type": "string", "description": "Ignorato sul soggetto: applicato lato server a partire dai `vendor_data` del token." }, "fullName": { "type": "string", "example": "Jane Doe" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dob": { "type": "string", "format": "date", "description": "Data di nascita (YYYY-MM-DD; corrisponde a `date_of_birth`)." }, "address": { "type": "object", "description": "Oggetto indirizzo con `country` (ISO 3166-1 alpha-3), `town`, `state`, `street`, `post_code`." }, "institutionInfo": { "type": "object", "description": "Dettagli dell'istituto per partecipanti istituzionali (corrisponde a `institution_details`)." }, "device": { "type": "object", "description": "Contesto esplicito del dispositivo opzionale. Viene unito alle informazioni sul dispositivo acquisite automaticamente; in caso di conflitto, prevalgono i campi ricavati dal server." }, "paymentMethod": { "type": "object", "description": "Metodo di pagamento usato dal soggetto (mappato su `payment_method`).", "properties": { "type": { "type": "string", "description": "Tipo di metodo di pagamento (mappato su `method_type`), ad es. `bank_card`, `bank_account`, `crypto_wallet`, `ewallet`, `unhosted_wallet`, `other`." }, "accountId": { "type": "string", "description": "Identificativo dell'account (mappato su `account_id`): IBAN, impronta digitale della carta o indirizzo." }, "issuingCountry": { "type": "string", "description": "Codice paese ISO 3166-1 alpha-3 dell'emittente (corrisponde a `issuing_country`)." } } } } }, "counterparty": { "type": "object", "description": "La controparte della transazione (opzionale). Stessa struttura di `subject`; in questo contesto `externalUserId` è rilevante.", "properties": { "type": { "type": "string", "description": "Tipo di entità (mappato su `entity_type`): `individual` o `company`." }, "externalUserId": { "type": "string", "description": "Il tuo identificatore interno per la controparte (corrisponde a `vendor_data`)." }, "fullName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dob": { "type": "string", "format": "date" }, "address": { "type": "object" }, "institutionInfo": { "type": "object" }, "device": { "type": "object" }, "paymentMethod": { "type": "object", "description": "Metodo di pagamento usato dalla controparte (mappato su `payment_method`). Nelle transazioni travelRule, `type: \"unhosted_wallet\"` dichiara il wallet della controparte come in autocustodia: il trasferimento salta l'instradamento verso il VASP della controparte, viene creato direttamente in `UNCONFIRMED_OWNERSHIP` e (quando `auto_wallet_verification` è abilitato) viene generata automaticamente una sessione del widget di proprietà del wallet restituita in `action_required` in modo che l'SDK possa avviarla.", "properties": { "type": { "type": "string", "description": "Tipologia di metodo di pagamento (mappata su `method_type`), ad es. `bank_card`, `bank_account`, `crypto_wallet`, `ewallet`, `unhosted_wallet`, `other`. Usa `unhosted_wallet` per dichiarare un wallet in autocustodia per la Travel Rule." }, "accountId": { "type": "string", "description": "Identificativo dell'account (mappato su `account_id`): IBAN, impronta digitale della carta o indirizzo." }, "issuingCountry": { "type": "string" } } } } }, "props": { "type": "object", "additionalProperties": true, "description": "Coppie chiave-valore personalizzate (mappate su `custom_properties`). Ciascuna chiave può essere referenziata nelle condizioni delle regole come `custom_values.`." }, "travelRule": { "type": "object", "description": "Dettagli Travel Rule (corrisponde a `travel_rule_details`). Quando Travel Rule è abilitata per l'applicazione, Didit ignora qualsiasi `status` inviato e gestisce direttamente lo scambio.", "required": [ "status" ], "properties": { "status": { "type": "string" }, "protocol": { "type": "string" }, "required": { "type": "boolean" }, "obligationsCount": { "type": "integer" }, "originatorData": { "type": "object" }, "beneficiaryData": { "type": "object" }, "metadata": { "type": "object" } } }, "includeCryptoScreening": { "type": "boolean", "nullable": true, "description": "Sostituzione per transazione per lo screening di analisi della blockchain crypto (corrisponde a `include_crypto_screening`)." }, "fingerprint_v2": { "type": "object", "description": "Il payload del fingerprint del dispositivo `didit-fp-v2`. Iniettato automaticamente dagli SDK; rilevante solo quando si chiama direttamente l'API wire." } }, "required": [ "txnId", "type", "info", "subject" ] }, "example": { "txnId": "wd-2026-07-07-0042", "type": "travelRule", "info": { "direction": "out", "amount": "0.25", "currency": "ETH", "currencyType": "crypto", "cryptoParams": { "crypto_chain": "ETH" } }, "subject": { "fullName": "Jane Doe" }, "counterparty": { "fullName": "Ana Diaz", "paymentMethod": { "type": "unhosted_wallet", "accountId": "0xBeneficiaryWallet01" } }, "travelRule": { "status": "AWAITING_COUNTERPARTY", "beneficiaryData": { "wallet_address": "0xBeneficiaryWallet01", "name": "Ana Diaz" } }, "includeCryptoScreening": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v1/transactions/ \\\n -H 'X-Transaction-Token: SDK_TOKEN' -H 'Content-Type: application/json' \\\n -d '{\"txnId\": \"wd-2026-07-07-0042\", \"type\": \"travelRule\", \"info\": {\"direction\": \"out\", \"amount\": \"0.25\", \"currency\": \"ETH\", \"currencyType\": \"crypto\"}, \"subject\": {\"fullName\": \"Jane Doe\"}, \"counterparty\": {\"fullName\": \"Ana Diaz\", \"paymentMethod\": {\"type\": \"unhosted_wallet\", \"accountId\": \"0xBeneficiaryWallet01\"}}, \"travelRule\": {\"status\": \"AWAITING_COUNTERPARTY\", \"beneficiaryData\": {\"wallet_address\": \"0xBeneficiaryWallet01\", \"name\": \"Ana Diaz\"}}, \"includeCryptoScreening\": true}'" }, { "lang": "javascript", "label": "Web SDK", "source": "import { DiditSdk } from '@didit-protocol/sdk-web';\n\nconst result = await DiditSdk.shared.submitTransaction({\n transactionToken: sdkToken,\n transaction: {\n txnId: 'wd-2026-07-07-0042',\n category: 'travelRule',\n details: { direction: 'out', amount: '0.25', currency: 'ETH', currencyType: 'crypto' },\n subject: { fullName: 'Jane Doe' },\n counterparty: { fullName: 'Ana Diaz', paymentMethod: { type: 'unhosted_wallet', accountId: '0xBeneficiaryWallet01' } },\n travelRule: { status: 'AWAITING_COUNTERPARTY', beneficiaryData: { wallet_address: '0xBeneficiaryWallet01', name: 'Ana Diaz' } },\n includeCryptoScreening: true\n },\n onActionCompleted: (refreshed) => console.log(refreshed.status)\n});" } ], "responses": { "201": { "description": "Transazione inviata e monitorata. Stessa struttura di dettaglio di `GET /v3/transactions/{transaction_id}/`, incluso il blocco `action_required` quando l'utente finale deve completare un'azione successiva (gli SDK la avviano automaticamente per impostazione predefinita).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "examples": { "Wallet ownership required": { "value": { "uuid": "22222222-3333-4444-5555-666666666666", "txn_id": "wd-2026-07-07-0042", "transaction_type": "travelRule", "direction": "OUTBOUND", "status": "APPROVED", "amount": "0.25", "currency": "ETH", "travel_rule": { "uuid": "33333333-4444-5555-6666-777777777777", "status": "UNCONFIRMED_OWNERSHIP", "required": true }, "action_required": { "type": "wallet_ownership", "url": "https://verify.didit.me/wallet-ownership/3s9x...urlsafe", "widget_session_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb", "expires_at": "2026-07-07T13:00:00Z" } } } } } } }, "400": { "description": "Validazione non riuscita (campi obbligatori mancanti, `txnId` duplicato, categoria sconosciuta).", "content": { "application/json": { "examples": { "Missing fields": { "value": { "transaction_details": { "currency": [ "This field is required." ] } } }, "Duplicate txnId": { "value": { "transaction_id": [ "A transaction with this transaction_id already exists." ] } } } } } }, "401": { "description": "Il token di transazione è stato rifiutato: mancante, sconosciuto, revocato, superiore al relativo `max_uses` o scaduto. Le risposte per token scaduto contengono sempre la parola `expired` nei dettagli, consentendo agli SDK di distinguere gli errori `expired_token` da `invalid_token`.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "Invalid transaction token." } }, "Expired token": { "value": { "detail": "Transaction token expired." } } } } } }, "409": { "description": "Un'altra richiesta con lo stesso `txnId` ha creato la transazione mentre questa era in fase di elaborazione, quindi solo uno dei due invii simultanei ha esito positivo. Leggi la transazione esistente invece di inviarla nuovamente.", "content": { "application/json": { "examples": { "Concurrent duplicate": { "value": { "detail": "A transaction with this transaction_id already exists." } } } } } } } } }, "/v1/transactions/{transaction_id}/": { "get": { "summary": "Recupera una transazione da un SDK", "description": "Endpoint di lettura lato dispositivo, autenticato con lo stesso `X-Transaction-Token` utilizzato per l'invio. Gli SDK ne eseguono il polling dopo il completamento di un flusso di azioni avviato automaticamente o alla chiusura della relativa finestra, assicurando che lo stato finale non dipenda mai da una singola notifica. Restituisce gli stessi dettagli della transazione della risposta di invio, compreso il blocco `action_required` corrente (`null` una volta risolta l'azione).", "operationId": "getTransactionFromSdk", "x-didit-sdk": { "resource": "transactions", "method": "retrieve_from_device", "auth": "device_token", "server": false }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID della transazione stabile di Didit (lo `uuid` dalla risposta di invio, **non** il tuo `txnId`).", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" } ], "security": [ { "TransactionTokenAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v1/transactions/22222222-3333-4444-5555-666666666666/' \\\n -H 'X-Transaction-Token: SDK_TOKEN'" } ], "responses": { "200": { "description": "Il dettaglio completo della transazione, compreso `action_required` (`null` una volta risolta l'azione in sospeso).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" } } } }, "401": { "description": "Il token di transazione è stato rifiutato: mancante, sconosciuto, revocato, superiore al relativo `max_uses` o scaduto.", "content": { "application/json": { "examples": { "Expired token": { "value": { "detail": "Transaction token expired." } } } } } }, "404": { "description": "Nessuna transazione con questo UUID esiste per l'applicazione del token, oppure il segmento di percorso non è un UUID valido.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } } } } }, "/v3/businesses/": { "get": { "summary": "Elenca le aziende", "description": "Elenca le [aziende](/entities/businesses) aggregate da Didit a partire dalle sessioni KYB che condividono lo stesso `vendor_data` (stringa a formato libero, NON un UUID), oltre alle aziende create tramite API. Paginato, ordinato per `last_session_at` decrescente. Questo endpoint non supporta parametri di filtro o ricerca: recupera le pagine e applica i filtri sul client.", "operationId": "list_businesses", "x-didit-sdk": { "resource": "businesses", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Dimensione della pagina. Se omessa, il valore predefinito è 50. Non esiste un massimo imposto, ma mantieni le pagine piccole per ridurre la latenza." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Offset in base zero del primo record da restituire. È preferibile seguire l'URL `next` della pagina precedente invece di calcolarlo manualmente." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/businesses/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.businesses.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.businesses.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Businesses.ListAutoPaging(ctx, didit.BusinessesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.businesses().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "businesses->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.businesses.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Businesses.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Elenco impaginato delle aziende con stato, conteggio delle sessioni e riepilogo delle funzionalità.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero di righe corrispondenti: esatto fino a 100, con limite massimo di 100 oltre tale soglia per motivi di prestazioni. Non utilizzarlo per rilevare l'ultima pagina; fai invece affidamento sul fatto che `next` sia `null`." }, "next": { "type": "string", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessListItem" } } } }, "examples": { "Example": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": null, "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Trading Ltd", "status": "ACTIVE", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z" } ] } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può elencare le aziende per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/customization/": { "get": { "summary": "Recupera la personalizzazione del branding", "description": "Restituisce il branding White label per l'applicazione determinato dalla chiave API: colori, font, raggi del bordo, URL del logo e opzioni UI/UX. Le impostazioni del dominio personalizzato e delle email White label sono gestite esclusivamente nella Business Console e non fanno parte di questa risposta.", "operationId": "get_customization", "x-didit-sdk": { "resource": "customization", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Customization" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/customization/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.customization.retrieve()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.customization.retrieve();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Customization.Retrieve(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.customization().retrieve();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "customization->retrieve();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.customization.retrieve\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Customization.RetrieveAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Personalizzazione attuale del marchio per l'applicazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingCustomization" }, "examples": { "Default branding": { "value": { "color_primary": "#000000", "color_secondary": "#9DA1A1", "color_background": "#FFFFFF", "color_panel": "#2567FF", "color_panel_10": "#1A1A1A", "color_on_panel_1": "#9DA1A1", "color_on_panel_2": "#F4F4F6", "color_on_background": "#000000", "color_button_1": "#2567FF", "color_button_2": "#F8F8F8", "color_button_text_1": "#FFFFFF", "color_button_text_2": "#000000", "color_pill_text": "#111827", "border_radius_panel": 10, "border_radius_buttons": 12, "font_family": "Inter", "font_weight": "regular", "font_url": "https://fonts.googleapis.com/css2?family=Inter", "logo_square": null, "logo_rectangular": null, "logo_rectangular_dark": null, "favicon": null, "app_public_name": "Acme Verify", "privacy_policy_url": "https://acme.com/privacy", "skip_welcome_screen": false, "disable_login_with_didit": false, "hide_progress_bar": false, "callback_seconds": 3 } } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna la personalizzazione del branding", "description": "Aggiornamento parziale del branding White label dell'applicazione. Invia `application/json` per modificare colori, font, raggi e opzioni dell'interfaccia utente, oppure `multipart/form-data` per caricare le immagini del logo. Vengono modificati solo i campi inclusi. Il dominio personalizzato e l'email White label non possono essere impostati tramite questo endpoint — usa la Business Console per queste opzioni.", "operationId": "update_customization", "x-didit-sdk": { "resource": "customization", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Customization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingCustomizationUpdate" }, "examples": { "Update colors and font": { "summary": "Modifica i colori e il font del branding", "value": { "color_primary": "#123456", "color_button_1": "#2567FF", "font_family": "AR One Sans", "border_radius_buttons": 16 } }, "Update UI options": { "summary": "Modifica il nome pubblico e le opzioni del flusso", "value": { "app_public_name": "Acme Verify", "privacy_policy_url": "https://acme.com/privacy", "skip_welcome_screen": true, "hide_progress_bar": true, "callback_seconds": 5 } }, "Remove a logo": { "summary": "Elimina il logo rettangolare attuale", "value": { "delete_logo_rectangular": true } }, "Remove the dark-mode logo": { "summary": "Elimina il logo attuale per la modalità scura", "value": { "delete_logo_rectangular_dark": true } } } }, "multipart/form-data": { "schema": { "type": "object", "description": "Usa multipart/form-data solo per caricare immagini del logo. I campi di branding indicati sopra possono essere inviati anche come campi del modulo nella stessa richiesta.", "properties": { "image_square": { "type": "string", "format": "binary", "description": "Logo quadrato (proporzioni 1:1). PNG, JPG o WebP, almeno 512 px sul lato lungo, massimo **1 MB**." }, "image_rectangular": { "type": "string", "format": "binary", "description": "Logo rettangolare (proporzioni 2:1). PNG, JPG o WebP, di almeno 512 px sul lato lungo, massimo **1 MB**." }, "image_rectangular_dark": { "type": "string", "format": "binary", "description": "Logo rettangolare per la modalità scura (proporzioni 2:1), mostrato su sfondo scuro. PNG, JPG o WebP, di almeno 512 px sul lato lungo, massimo **1 MB**. Restituito come `logo_rectangular_dark`." }, "image_favicon": { "type": "string", "format": "binary", "description": "Immagine della favicon. Massimo **500 KB**." } } }, "example": { "image_rectangular": "(binary PNG logo, 2:1)", "image_rectangular_dark": "(binary PNG logo for dark mode, 2:1)", "image_favicon": "(binary favicon)" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/customization/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"color_primary\": \"#123456\", \"font_family\": \"AR One Sans\"}'" }, { "lang": "curl", "label": "curl (logo upload)", "source": "curl -X PATCH 'https://verification.didit.me/v3/customization/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'image_rectangular=@logo.png' \\\n -F 'image_rectangular_dark=@logo-dark.png' \\\n -F 'image_favicon=@favicon.ico'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.customization.update(\n image_rectangular=open(\"image_rectangular.jpg\", \"rb\"),\n image_rectangular_dark=open(\"image_rectangular_dark.jpg\", \"rb\"),\n image_favicon=open(\"image_favicon.jpg\", \"rb\"),\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.customization.update({\n image_rectangular: await fileFromPath(\"image_rectangular.jpg\"),\n image_rectangular_dark: await fileFromPath(\"image_rectangular_dark.jpg\"),\n image_favicon: await fileFromPath(\"image_favicon.jpg\"),\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Customization.Update(ctx, didit.CustomizationUpdateParams{\n\tImageRectangular: didit.Some(didit.FileFromPath(\"image_rectangular.jpg\")),\n\tImageRectangularDark: didit.Some(didit.FileFromPath(\"image_rectangular_dark.jpg\")),\n\tImageFavicon: didit.Some(didit.FileFromPath(\"image_favicon.jpg\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.CustomizationUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.customization().update(CustomizationUpdateParams.builder()\n .imageRectangular(Path.of(\"image_rectangular.jpg\"))\n .imageRectangularDark(Path.of(\"image_rectangular_dark.jpg\"))\n .imageFavicon(Path.of(\"image_favicon.jpg\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "customization->update([\n 'image_rectangular' => File::fromPath('image_rectangular.jpg'),\n 'image_rectangular_dark' => File::fromPath('image_rectangular_dark.jpg'),\n 'image_favicon' => File::fromPath('image_favicon.jpg'),\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.customization.update(\n image_rectangular: Pathname(\"image_rectangular.jpg\"),\n image_rectangular_dark: Pathname(\"image_rectangular_dark.jpg\"),\n image_favicon: Pathname(\"image_favicon.jpg\")\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Customization.UpdateAsync(new CustomizationUpdateParams\n{\n ImageRectangular = FileUpload.FromPath(\"image_rectangular.jpg\"),\n ImageRectangularDark = FileUpload.FromPath(\"image_rectangular_dark.jpg\"),\n ImageFavicon = FileUpload.FromPath(\"image_favicon.jpg\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Branding aggiornato. Viene restituito l'oggetto branding COMPLETO (tutti i campi, non solo quelli modificati).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingCustomization" }, "examples": { "Updated": { "value": { "color_primary": "#123456", "color_secondary": "#9DA1A1", "color_background": "#FFFFFF", "color_panel": "#2567FF", "color_panel_10": "#1A1A1A", "color_on_panel_1": "#9DA1A1", "color_on_panel_2": "#F4F4F6", "color_on_background": "#000000", "color_button_1": "#2567FF", "color_button_2": "#F8F8F8", "color_button_text_1": "#FFFFFF", "color_button_text_2": "#000000", "color_pill_text": "#111827", "border_radius_panel": 10, "border_radius_buttons": 16, "font_family": "AR One Sans", "font_weight": "400", "font_url": "https://fonts.googleapis.com/css2?family=AR+One+Sans", "logo_square": null, "logo_rectangular": "https://cdn.didit.me/white_label/logo_rectangular/...", "logo_rectangular_dark": null, "favicon": null, "app_public_name": "Acme Verify", "privacy_policy_url": "https://acme.com/privacy", "skip_welcome_screen": true, "disable_login_with_didit": false, "hide_progress_bar": false, "callback_seconds": 3 } } } } } }, "400": { "description": "Corpo non valido. Ad esempio: un colore esadecimale non valido, una famiglia di caratteri o un peso del carattere sconosciuti, un campo riservato alla Business Console (`domain`, `from_email`, `verify_domain`, `force_remove_domain`, `verify_email_domain`, `force_remove_email_domain` e i relativi corrispondenti in sola lettura), o il caricamento di un logo che non è un'immagine PNG, JPG o WebP, ha il lato lungo inferiore a 512 px, supera 1 MB o presenta proporzioni errate. Viene restituito anche quando si imposta `disable_login_with_didit` su `false` mentre è configurato un dominio personalizzato.", "content": { "application/json": { "examples": { "Bad color": { "value": { "color_primary": [ "Invalid color format. Use '#RRGGBB' or '#RRGGBBAA' format." ] } }, "Bad logo": { "value": { "image_rectangular": [ "Image aspect ratio must be 2:1. Got 1024x1024 image dimensions" ] } }, "Unsupported logo format": { "summary": "Non è un'immagine PNG, JPG o WebP (ad esempio un SVG)", "value": { "image_rectangular_dark": [ "Upload a PNG, JPG or WebP image." ] } }, "Logo too small": { "summary": "Inferiore a 512 px sul lato lungo", "value": { "image_rectangular": [ "Image must be at least 512 px on its long side. Got 400x200 image dimensions" ] } }, "Logo too large": { "summary": "Superiore a 1 MB", "value": { "image_square": [ "File size should not exceed 1 MB" ] } }, "Console-only field": { "value": { "domain": [ "Manage this field in the Business Console." ] } }, "Bad font weight": { "value": { "font_weight": [ "Font weight 950 is not available for Inter. Available weights are: 100, 200, 300, 400, 500, 600, 700, 800, 900" ] } } } } } }, "403": { "description": "Chiave API mancante, malformata, scaduta o associata a un'applicazione diversa. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato. Riprova con backoff esponenziale." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/{vendor_data}/": { "get": { "summary": "Recupera azienda", "description": "Recupera un'[azienda](/entities/businesses) tramite `vendor_data` (corrispondenza esatta). Aggiunge `metadata` e `updated_at` alla visualizzazione elenco. Le aziende eliminate restituiscono 404.", "operationId": "get_business", "x-didit-sdk": { "resource": "businesses", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il tuo identificatore univoco per l'azienda: una stringa a formato libero (NON un UUID), confrontata esattamente come inviata.", "example": "company-123" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/businesses/company-123/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.retrieve(\n \"company-123\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.retrieve(\"company-123\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Retrieve(ctx, \"company-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().retrieve(\"company-123\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->retrieve('company-123');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.retrieve(\"company-123\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.RetrieveAsync(\"company-123\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Dettagli completi dell'azienda compresi metadati e dati aggregati della sessione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Active business": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": null, "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Trading Ltd", "status": "ACTIVE", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z", "metadata": { "industry": "fintech" }, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può leggere le aziende di questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessuna azienda (non eliminata) con il `vendor_data` fornito esiste per questa applicazione.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna l'azienda", "description": "Aggiornamento parziale di un'azienda: `display_name`, `legal_name`, `registration_number`, `country_code`, `status`, `metadata`. `metadata` sostituisce completamente. L'impostazione di `status` su `BLOCKED` aggiunge il `vendor_data` alla blocklist di sistema; allontanarsi da `BLOCKED` rimuove tale voce. Ogni modifica viene registrata nell'attività dell'azienda: una modifica di stato con il `reason` facoltativo, e una modifica a `display_name`, `legal_name`, `registration_number`, `country_code` o `metadata` come aggiornamento del profilo.", "operationId": "update_business", "x-didit-sdk": { "resource": "businesses", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il tuo identificatore univoco per l'azienda (stringa a formato libero, NON un UUID).", "example": "company-123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Corpo dell'aggiornamento parziale. Fornisci solo i campi che desideri modificare.", "properties": { "display_name": { "type": "string", "nullable": true, "description": "Nome descrittivo mostrato nella console (ha la precedenza su `legal_name` per la visualizzazione dell'interfaccia utente)." }, "legal_name": { "type": "string", "nullable": true, "description": "Denominazione legale ufficiale dal registro o inserimento manuale." }, "registration_number": { "type": "string", "nullable": true, "description": "Numero di registrazione o costituzione dell'azienda." }, "country_code": { "type": "string", "nullable": true, "description": "Paese di costituzione (ISO 3166-1 alpha-2, ad es. `GB`, `US`)." }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Stato del ciclo di vita dell'azienda. L'impostazione di `BLOCKED` aggiunge automaticamente il `vendor_data` alla blocklist di sistema; la rimozione di `BLOCKED` elimina tale voce dalla blocklist." }, "metadata": { "type": "object", "nullable": true, "description": "Oggetto JSON arbitrario da allegare all'azienda. **Sostituisce completamente** i metadati esistenti in caso di aggiornamento: esegui l'unione lato client se desideri solo aggiungere chiavi." }, "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Il motivo per cui lo stato è cambiato. Registrato nella voce di cambio di stato in **Activity** dell'azienda nella Business Console, solo quando lo stato cambia effettivamente. I webhook non lo includono." } } }, "examples": { "Update name": { "summary": "Aggiorna il nome visualizzato", "value": { "display_name": "Acme Corp" } }, "Flag for review": { "summary": "Modifica stato", "value": { "status": "FLAGGED" } }, "Add metadata": { "summary": "Sostituisci il JSON dei metadati", "value": { "metadata": { "industry": "fintech", "risk_level": "low" } } }, "Fix registry data": { "summary": "Campi estratti corretti", "value": { "legal_name": "Acme Trading International Ltd", "registration_number": "12345678", "country_code": "GB" } }, "Flag with reason": { "summary": "Segnala l'azienda e registra il motivo", "value": { "status": "FLAGGED", "reason": "Ownership structure under review" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/businesses/company-123/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"display_name\": \"Acme Corp\", \"status\": \"FLAGGED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.update(\n \"company-123\",\n display_name=\"Acme Corp\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.update(\"company-123\", {\n display_name: \"Acme Corp\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Update(ctx, \"company-123\", didit.BusinessesUpdateParams{\n\tDisplayName: didit.String(\"Acme Corp\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BusinessesUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().update(\"company-123\", BusinessesUpdateParams.builder()\n .displayName(\"Acme Corp\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->update('company-123', [\n 'display_name' => 'Acme Corp',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.update(\n \"company-123\",\n display_name: \"Acme Corp\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.UpdateAsync(\"company-123\", new BusinessesUpdateParams\n{\n DisplayName = \"Acme Corp\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Azienda aggiornata. Viene restituito il record aziendale completo aggiornato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Updated": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": "Acme Corp", "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Corp", "status": "FLAGGED", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z", "metadata": { "industry": "fintech", "risk_level": "low" }, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "400": { "description": "Corpo non valido: in genere uno `status` sconosciuto, `metadata` non corretti o un `reason` superiore a 1000 caratteri.", "content": { "application/json": { "examples": { "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Bad metadata": { "value": { "metadata": [ "Metadata must be a JSON object." ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può aggiornare aziende per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessuna azienda (non eliminata) con il `vendor_data` fornito esiste per questa applicazione.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/{vendor_data}/update-status/": { "patch": { "summary": "Aggiorna lo stato dell'azienda", "description": "Modifica solo lo `status` del ciclo di vita di un'azienda: `ACTIVE`, `FLAGGED` o `BLOCKED` (non gli stati della sessione). `BLOCKED` aggiunge il `vendor_data` alla blocklist di sistema; passare a uno stato diverso da `BLOCKED` rimuove tale voce. Ogni modifica viene registrata nell'attività dell'azienda, con il `reason` facoltativo. L'invio dello stato attuale non modifica nulla e non registra alcun `reason`. Il webhook `business.status.updated` non include `reason`.", "operationId": "update_business_status", "x-didit-sdk": { "resource": "businesses", "method": "update_status", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il tuo identificatore univoco per l'azienda (stringa a formato libero, NON un UUID).", "example": "company-123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityStatusUpdateRequest" }, { "type": "object", "properties": { "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Il motivo per cui lo stato è cambiato. Registrato nella voce di cambio di stato in **Activity** dell'azienda nella Business Console, solo quando lo stato cambia effettivamente. I webhook non lo includono." } } } ] }, "examples": { "Flag": { "summary": "Segnala l'azienda per la revisione", "value": { "status": "FLAGGED" } }, "Block": { "summary": "Blocca l'azienda (aggiunge alla blocklist di sistema)", "value": { "status": "BLOCKED" } }, "Reactivate": { "summary": "Riattiva l'azienda", "value": { "status": "ACTIVE" } }, "Block with reason": { "summary": "Blocca l'azienda e registra il motivo", "value": { "status": "BLOCKED", "reason": "Registry shows the company dissolved" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/businesses/company-123/update-status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"status\": \"BLOCKED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.update_status(\n \"company-123\",\n status=\"FLAGGED\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.updateStatus(\"company-123\", {\n status: \"FLAGGED\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.UpdateStatus(ctx, \"company-123\", didit.BusinessesUpdateStatusParams{\n\tStatus: \"FLAGGED\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BusinessesUpdateStatusParams;\nimport me.didit.types.EntityStatusUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().updateStatus(\"company-123\", BusinessesUpdateStatusParams.builder()\n .status(EntityStatusUpdateRequest.Status.of(\"FLAGGED\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->updateStatus('company-123', [\n 'status' => 'FLAGGED',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.update_status(\n \"company-123\",\n status: \"FLAGGED\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.UpdateStatusAsync(\"company-123\", new BusinessesUpdateStatusParams\n{\n Status = \"FLAGGED\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Stato dell'azienda aggiornato. Restituisce il record aziendale completo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Blocked": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": null, "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Trading Ltd", "status": "BLOCKED", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z", "metadata": { "industry": "fintech" }, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "400": { "description": "`status` mancante o non valido, oppure un `reason` superiore a 1000 caratteri.", "content": { "application/json": { "examples": { "Missing status": { "value": { "status": [ "This field is required." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può aggiornare aziende per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessuna azienda (non eliminata) con il `vendor_data` fornito esiste per questa applicazione.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/delete/": { "post": { "summary": "Elimina aziende in blocco", "description": "**Elimina definitivamente** le aziende: questa operazione non può essere annullata. Per il blocco preferisci [Aggiorna stato azienda](#patch-/v3/businesses/-vendor_data-/update-status/) con `BLOCKED`.\n\n**Report normativi presentati:** se i dati selezionati sono presenti in un report normativo finalizzato, l'intera richiesta viene rifiutata con `409` e non viene eliminato nulla. Il corpo usa `code: in_filed_report` e indica ciascun report con `uuid`, `report_number`, `report_type` e `case_uuid`. Elimina i report, quindi ripeti la richiesta.", "operationId": "batch_delete_businesses", "x-didit-sdk": { "resource": "businesses", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Fornisci `vendor_data_list`, `didit_internal_id_list` o `delete_all: true`. Ordine di precedenza quando ne vengono inviati diversi: `delete_all` > `vendor_data_list` > `didit_internal_id_list` (viene utilizzato solo il selettore con precedenza più alta).", "properties": { "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "I tuoi identificatori da eliminare, confrontati esattamente come inviati." }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "UUID interni Didit (`didit_internal_id`) da eliminare." }, "delete_all": { "type": "boolean", "default": false, "description": "Se `true`, elimina ogni azienda nell'applicazione. Non può essere combinato con i selettori di elenco." } } }, "examples": { "Specific businesses": { "summary": "Elimina tramite vendor_data", "value": { "vendor_data_list": [ "company-123", "company-456" ] } }, "Specific internal IDs": { "summary": "Elimina tramite didit_internal_id", "value": { "didit_internal_id_list": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] } }, "All businesses": { "summary": "Elimina tutte le aziende in questa applicazione", "value": { "delete_all": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/businesses/delete/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data_list\": [\"company-123\", \"company-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.batch_delete(\n vendor_data_list=[\"company-123\", \"company-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.batchDelete({\n vendor_data_list: [\"company-123\", \"company-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.BatchDelete(ctx, didit.BusinessesBatchDeleteParams{\n\tVendorDataList: didit.Some([]string{\"company-123\", \"company-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BusinessesBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().batchDelete(BusinessesBatchDeleteParams.builder()\n .vendorDataList(List.of(\"company-123\", \"company-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->batchDelete([\n 'vendor_data_list' => ['company-123', 'company-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.batch_delete(vendor_data_list: [\"company-123\", \"company-456\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.BatchDeleteAsync(new BusinessesBatchDeleteParams\n{\n VendorDataList = new string[] { \"company-123\", \"company-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Aziende eliminate. Restituisce il numero di righe effettivamente rimosse.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer", "description": "Numero di aziende eliminate (esclude i valori di vendor_data che non corrispondevano a nulla)." } } }, "examples": { "Deleted some": { "value": { "deleted": 2 } }, "Nothing matched": { "value": { "deleted": 0 } } } } } }, "400": { "description": "Nessun selettore fornito (tutti i parametri `vendor_data_list`, `didit_internal_id_list` e `delete_all` risultano mancanti o vuoti). Il corpo dell'errore è un array JSON.", "content": { "application/json": { "examples": { "Missing selector": { "value": [ "Provide vendor_data_list, didit_internal_id_list, or set delete_all=true." ] } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può eliminare aziende per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } }, "409": { "description": "Non viene eliminato nulla. `code` ne indica il motivo: `in_filed_report` quando la selezione include un'azienda presente in un report normativo finalizzato, `subject_deletion_in_progress` quando un'altra richiesta sta ancora eliminando una delle aziende selezionate. Ripeti la richiesta una volta completata tale eliminazione.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InFiledReportError" }, { "$ref": "#/components/schemas/SubjectDeletionInProgressError" } ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/users/aml-monitoring/": { "post": { "summary": "Abilita o disabilita il monitoraggio AML continuo per gli utenti", "description": "Attiva o disattiva il monitoraggio AML continuo per gli utenti selezionati, con la stessa semantica della Business Console. Viene mantenuto esattamente uno Screening AML monitorato per utente, quindi un profilo che ha completato la verifica più volte viene monitorato e fatturato una sola volta; la disattivazione disabilita il monitoraggio in tutti gli screening del profilo. Gli utenti senza alcuno Screening AML vengono prima sottoposti a screening (fatturato come normale Screening AML) se dispongono di nome completo, data di nascita e paese necessari; altrimenti vengono riportati come `skipped_no_identity_data`.\n\nImposta `estimate_only: true` per visualizzare in anteprima conteggi e costi senza scrivere nulla. Le selezioni di 20 profili o meno vengono elaborate inline e restituiscono `200` con il job completato; le selezioni più ampie restituiscono `202` e vengono eseguite in background: esegui il polling di [Get AML monitoring job](#get-/v3/aml-monitoring/jobs/-job_id-/) con il `job_id` restituito. L'attivazione viene rifiutata con `403` quando il saldo dell'organizzazione non copre la stima. Gli identificatori che non corrispondono a nessun elemento vengono elencati in `unmatched` e non fanno mai fallire la richiesta: una selezione che non corrisponde a nulla si completa come un job vuoto (`total` 0), la stessa convenzione degli endpoint di eliminazione in batch.", "operationId": "toggle_users_aml_monitoring", "x-didit-sdk": { "resource": "users", "method": "set_aml_monitoring", "auth": "api_key", "server": true }, "tags": [ "AML Ongoing Monitoring" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_enabled" ], "description": "Seleziona gli utenti con `vendor_data_list`, `didit_internal_id_list` o entrambi (i due elenchi vengono combinati con OR). Al massimo 1000 identificatori per richiesta considerando entrambi gli elenchi.", "properties": { "is_enabled": { "type": "boolean", "description": "true per abilitare il monitoraggio, false per disabilitarlo." }, "estimate_only": { "type": "boolean", "default": false, "description": "Se true, restituisce la stima dei costi e non esegue scritture: nessuno screening, nessuna fatturazione, nessun job." }, "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "I tuoi identificatori degli utenti da attivare/disattivare, confrontati esattamente come inviati." }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "ID interni Didit degli utenti da attivare o disattivare: il `didit_internal_id` restituito dagli endpoint di creazione, recupero ed elenco." } } }, "examples": { "Estimate first": { "summary": "Visualizza l'anteprima del costo senza scrivere", "value": { "is_enabled": true, "estimate_only": true, "vendor_data_list": [ "user-123", "user-456" ] } }, "Enable": { "summary": "Abilita il monitoraggio per due utenti", "value": { "is_enabled": true, "vendor_data_list": [ "user-123", "user-456" ] } }, "Disable": { "summary": "Disabilita il monitoraggio tramite ID interno di Didit", "value": { "is_enabled": false, "didit_internal_id_list": [ "3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11" ] } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/users/aml-monitoring/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"is_enabled\": true, \"vendor_data_list\": [\"user-123\", \"user-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.set_aml_monitoring(\n is_enabled=True,\n estimate_only=True,\n vendor_data_list=[\"user-123\", \"user-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.setAmlMonitoring({\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"user-123\", \"user-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.SetAMLMonitoring(ctx, didit.UsersSetAMLMonitoringParams{\n\tIsEnabled: true,\n\tEstimateOnly: didit.Bool(true),\n\tVendorDataList: didit.Some([]string{\"user-123\", \"user-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.UsersSetAmlMonitoringParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().setAmlMonitoring(UsersSetAmlMonitoringParams.builder()\n .isEnabled(true)\n .estimateOnly(true)\n .vendorDataList(List.of(\"user-123\", \"user-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->setAmlMonitoring([\n 'is_enabled' => true,\n 'estimate_only' => true,\n 'vendor_data_list' => ['user-123', 'user-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.set_aml_monitoring(\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"user-123\", \"user-456\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.SetAmlMonitoringAsync(new UsersSetAmlMonitoringParams\n{\n IsEnabled = true,\n EstimateOnly = true,\n VendorDataList = new string[] { \"user-123\", \"user-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La stima (quando `estimate_only` è true) o il processo completato per una selezione elaborata in linea.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringToggleResult" } } } }, "202": { "description": "Le selezioni più ampie vengono eseguite in background. Esegui il polling dell'endpoint del job con `job_id`; `results` si popola man mano che i profili vengono elaborati.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringJob" } } } }, "400": { "description": "Errore di validazione: `is_enabled` mancante, nessun selettore o più di 1000 identificatori complessivamente nelle due liste." }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "Saldo insufficiente per abilitare il monitoraggio per questa selezione. La risposta include il campo `estimate` per consentirti di ricaricare l'importo corretto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "estimate": { "type": "object", "description": "Anteprima dei costi. Restituita direttamente quando estimate_only è true (non viene scritto nulla).", "properties": { "users_total": { "type": "integer", "description": "Profili corrispondenti alla selezione." }, "already_enabled": { "type": "integer", "description": "Profili già monitorati (nessuna operazione da eseguire durante l'abilitazione; sono quelli che vengono disattivati quando si disabilita il monitoraggio)." }, "with_existing_aml": { "type": "integer", "description": "Profili il cui Screening AML esistente verrà impostato come monitorato (nessun nuovo screening)." }, "needing_screening": { "type": "integer", "description": "Profili senza alcuno Screening AML che verranno prima sottoposti a screening (fatturati come normale Screening AML)." }, "skipped_no_identity_data": { "type": "integer", "description": "Profili di cui non è possibile effettuare lo screening a causa della mancanza dei dati di identità." }, "skipped_blocked": { "type": "integer", "description": "Utenti bloccati che verranno saltati (sempre 0 per le aziende)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Costo una tantum dei nuovi screening." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Costo annuale di monitoraggio dei profili che passeranno a essere monitorati." }, "balance_sufficient": { "type": "boolean", "description": "Indica se il saldo dell'organizzazione copre lo screening e il primo anno di monitoraggio." } } } } } } } } } } }, "/v3/businesses/aml-monitoring/": { "post": { "summary": "Abilita o disabilita il monitoraggio AML continuo per le aziende", "description": "Attiva o disattiva il monitoraggio AML continuo per le aziende selezionate, con la stessa semantica della Business Console. Viene mantenuto esattamente uno Screening AML monitorato per azienda, quindi un profilo che ha completato la verifica più volte viene monitorato e fatturato una sola volta; la disattivazione disabilita il monitoraggio in tutti gli screening del profilo. Le aziende senza alcuno Screening AML vengono prima sottoposte a screening (fatturato come normale Screening AML) se dispongono della ragione sociale o del nome visualizzato necessario; altrimenti vengono riportate come `skipped_no_identity_data`.\n\nImposta `estimate_only: true` per visualizzare in anteprima conteggi e costi senza scrivere nulla. Le selezioni di 20 profili o meno vengono elaborate inline e restituiscono `200` con il job completato; le selezioni più ampie restituiscono `202` e vengono eseguite in background: esegui il polling di [Get AML monitoring job](#get-/v3/aml-monitoring/jobs/-job_id-/) con il `job_id` restituito. L'attivazione viene rifiutata con `403` quando il saldo dell'organizzazione non copre la stima. Gli identificatori che non corrispondono a nessun elemento vengono elencati in `unmatched` e non fanno mai fallire la richiesta: una selezione che non corrisponde a nulla si completa come un job vuoto (`total` 0), la stessa convenzione degli endpoint di eliminazione in batch.", "operationId": "toggle_businesses_aml_monitoring", "x-didit-sdk": { "resource": "businesses", "method": "set_aml_monitoring", "auth": "api_key", "server": true }, "tags": [ "AML Ongoing Monitoring" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_enabled" ], "description": "Seleziona le aziende con `vendor_data_list`, `didit_internal_id_list` o entrambi (i due elenchi vengono combinati con OR). Al massimo 1000 identificatori per richiesta considerando entrambi gli elenchi.", "properties": { "is_enabled": { "type": "boolean", "description": "true per abilitare il monitoraggio, false per disabilitarlo." }, "estimate_only": { "type": "boolean", "default": false, "description": "Se true, restituisce la stima dei costi e non esegue scritture: nessuno screening, nessuna fatturazione, nessun job." }, "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "I tuoi identificatori delle aziende da attivare/disattivare, confrontati esattamente come inviati." }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "ID interni Didit delle aziende da attivare o disattivare: il `didit_internal_id` restituito dagli endpoint di creazione, recupero ed elenco." } } }, "examples": { "Estimate first": { "summary": "Visualizza l'anteprima del costo senza scrivere", "value": { "is_enabled": true, "estimate_only": true, "vendor_data_list": [ "company-123", "company-456" ] } }, "Enable": { "summary": "Abilita il monitoraggio per due aziende", "value": { "is_enabled": true, "vendor_data_list": [ "company-123", "company-456" ] } }, "Disable": { "summary": "Disabilita il monitoraggio tramite ID interno di Didit", "value": { "is_enabled": false, "didit_internal_id_list": [ "3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11" ] } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/businesses/aml-monitoring/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"is_enabled\": true, \"vendor_data_list\": [\"company-123\", \"company-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.set_aml_monitoring(\n is_enabled=True,\n estimate_only=True,\n vendor_data_list=[\"company-123\", \"company-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.setAmlMonitoring({\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"company-123\", \"company-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.SetAMLMonitoring(ctx, didit.BusinessesSetAMLMonitoringParams{\n\tIsEnabled: true,\n\tEstimateOnly: didit.Bool(true),\n\tVendorDataList: didit.Some([]string{\"company-123\", \"company-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BusinessesSetAmlMonitoringParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().setAmlMonitoring(BusinessesSetAmlMonitoringParams.builder()\n .isEnabled(true)\n .estimateOnly(true)\n .vendorDataList(List.of(\"company-123\", \"company-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->setAmlMonitoring([\n 'is_enabled' => true,\n 'estimate_only' => true,\n 'vendor_data_list' => ['company-123', 'company-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.set_aml_monitoring(\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"company-123\", \"company-456\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.SetAmlMonitoringAsync(new BusinessesSetAmlMonitoringParams\n{\n IsEnabled = true,\n EstimateOnly = true,\n VendorDataList = new string[] { \"company-123\", \"company-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La stima (quando `estimate_only` è true) o il processo completato per una selezione elaborata in linea.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringToggleResult" } } } }, "202": { "description": "Le selezioni più ampie vengono eseguite in background. Esegui il polling dell'endpoint del job con `job_id`; `results` si popola man mano che i profili vengono elaborati.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringJob" } } } }, "400": { "description": "Errore di validazione: `is_enabled` mancante, nessun selettore o più di 1000 identificatori complessivamente nelle due liste." }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "Saldo insufficiente per abilitare il monitoraggio per questa selezione. La risposta include il campo `estimate` per consentirti di ricaricare l'importo corretto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "estimate": { "type": "object", "description": "Anteprima dei costi. Restituita direttamente quando estimate_only è true (non viene scritto nulla).", "properties": { "users_total": { "type": "integer", "description": "Profili corrispondenti alla selezione." }, "already_enabled": { "type": "integer", "description": "Profili già monitorati (nessuna operazione da eseguire durante l'abilitazione; sono quelli che vengono disattivati quando si disabilita il monitoraggio)." }, "with_existing_aml": { "type": "integer", "description": "Profili il cui Screening AML esistente verrà impostato come monitorato (nessun nuovo screening)." }, "needing_screening": { "type": "integer", "description": "Profili senza alcuno Screening AML che verranno prima sottoposti a screening (fatturati come normale Screening AML)." }, "skipped_no_identity_data": { "type": "integer", "description": "Profili di cui non è possibile effettuare lo screening a causa della mancanza dei dati di identità." }, "skipped_blocked": { "type": "integer", "description": "Utenti bloccati che verranno saltati (sempre 0 per le aziende)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Costo una tantum dei nuovi screening." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Costo annuale di monitoraggio dei profili che passeranno a essere monitorati." }, "balance_sufficient": { "type": "boolean", "description": "Indica se il saldo dell'organizzazione copre lo screening e il primo anno di monitoraggio." } } } } } } } } } } }, "/v3/aml-monitoring/jobs/{job_id}/": { "get": { "summary": "Recupera un job di monitoraggio AML continuo", "description": "Stato, contatori dei risultati ed esiti per record di un job di attivazione/disattivazione del monitoraggio avviato da `POST /v3/users/aml-monitoring/` o `POST /v3/businesses/aml-monitoring/`. Esegui il polling ogni paio di secondi mentre `status` è `PENDING` o `PROCESSING`; `results` è completo quando diventa `COMPLETED`.", "operationId": "get_aml_monitoring_job", "x-didit-sdk": { "resource": "aml_monitoring", "method": "retrieve_job", "auth": "api_key", "server": true }, "tags": [ "AML Ongoing Monitoring" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Il `job_id` restituito dall'endpoint di attivazione/disattivazione." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl 'https://verification.didit.me/v3/aml-monitoring/jobs/JOB_ID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.aml_monitoring.retrieve_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.amlMonitoring.retrieveJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AMLMonitoring.RetrieveJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.amlMonitoring().retrieveJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "amlMonitoring->retrieveJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.aml_monitoring.retrieve_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.AmlMonitoring.RetrieveJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean", "description": "true quando il job abilita il monitoraggio, false quando lo disabilita." }, "target_type": { "type": "string", "enum": [ "user", "business" ], "description": "Quale famiglia di profili viene attivata o disattivata dal job." }, "total": { "type": "integer", "description": "Profili elaborati dal job." }, "processed": { "type": "integer", "description": "Profili elaborati finora." }, "outcomes": { "type": "object", "description": "Contatori di esito per singolo record. Ogni profilo selezionato corrisponde esattamente a un contatore; nulla viene ignorato silenziosamente.", "properties": { "enabled": { "type": "integer", "description": "Monitoraggio abilitato su uno screening AML esistente." }, "screened_and_enabled": { "type": "integer", "description": "È stato creato un nuovo screening AML (fatturato) e il relativo monitoraggio è stato abilitato." }, "already_enabled": { "type": "integer", "description": "Il monitoraggio era già attivo; non è cambiato nulla e non è stato fatturato nulla." }, "disabled": { "type": "integer", "description": "Monitoraggio disattivato su tutti gli screening AML del profilo." }, "skipped_no_identity_data": { "type": "integer", "description": "Saltato: il profilo è privo di nome completo, data di nascita e paese (utenti) o di un nome (aziende) necessari per lo screening." }, "skipped_blocked": { "type": "integer", "description": "Saltato: l'utente è bloccato." }, "skipped_sandbox": { "type": "integer", "description": "Saltato: applicazione sandbox, non viene creato alcuno screening." }, "failed_provider": { "type": "integer", "description": "Impossibile completare lo screening; riprova più tardi." }, "failed_insufficient_balance": { "type": "integer", "description": "Il saldo si è esaurito mentre il processo era in esecuzione." } } }, "results": { "type": "array", "description": "Una voce per ogni profilo elaborato, nell'ordine di elaborazione. Aumenta durante l'esecuzione del job; completa una volta che lo stato è COMPLETED. Registrata per i job avviati tramite API; un job avviato dalla Business Console riporta solo i conteggi.", "items": { "type": "object", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "ID interno Didit del profilo." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore per il profilo." }, "outcome": { "type": "string", "enum": [ "enabled", "screened_and_enabled", "already_enabled", "disabled", "skipped_no_identity_data", "skipped_blocked", "skipped_sandbox", "failed_provider", "failed_insufficient_balance" ] } } } }, "error": { "type": "string", "nullable": true, "description": "Messaggio di errore generico quando lo stato è FAILED; la causa dettagliata viene conservata lato piattaforma." }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "description": "Chiave API mancante o non valida." }, "404": { "description": "Nessun job del genere per questa applicazione." } } } }, "/v3/users/{vendor_data}/update-status/": { "patch": { "summary": "Aggiorna lo stato dell'utente", "description": "Modifica solo lo `status` del ciclo di vita di un utente: `ACTIVE`, `FLAGGED` o `BLOCKED` (non gli stati della sessione). `BLOCKED` aggiunge il `vendor_data` alla blocklist di sistema; passare a uno stato diverso da `BLOCKED` rimuove tale voce. Ogni modifica viene registrata come attività `STATUS_CHANGED` sull'utente, con il `reason` facoltativo come relativo `comment`. L'invio dello stato attuale non modifica nulla e non registra alcun `reason`. Il webhook `user.status.updated` non include `reason`.", "operationId": "update_user_status", "x-didit-sdk": { "resource": "users", "method": "update_status", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il tuo identificatore univoco per l'utente." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityStatusUpdateRequest" }, { "type": "object", "properties": { "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "Il motivo per cui lo stato è cambiato. Registrato nella voce di cambio di stato dell'attività dell'utente (`comments[].comment` e **Activity** nella Business Console), solo quando lo stato cambia effettivamente. I webhook non lo includono." } } } ] }, "examples": { "Activate": { "summary": "Riattiva l'utente", "value": { "status": "ACTIVE" } }, "Flag": { "summary": "Segnala l'utente per la revisione", "value": { "status": "FLAGGED" } }, "Block": { "summary": "Blocca l'utente (aggiunge alla blocklist di sistema)", "value": { "status": "BLOCKED" } }, "Block with reason": { "summary": "Blocca l'utente e registra il motivo", "value": { "status": "BLOCKED", "reason": "Chargeback fraud pattern confirmed" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/update-status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"status\": \"BLOCKED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.update_status(\n \"user-123\",\n status=\"ACTIVE\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.updateStatus(\"user-123\", {\n status: \"ACTIVE\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.UpdateStatus(ctx, \"user-123\", didit.UsersUpdateStatusParams{\n\tStatus: \"ACTIVE\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EntityStatusUpdateRequest;\nimport me.didit.types.UsersUpdateStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().updateStatus(\"user-123\", UsersUpdateStatusParams.builder()\n .status(EntityStatusUpdateRequest.Status.of(\"ACTIVE\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->updateStatus('user-123', [\n 'status' => 'ACTIVE',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.update_status(\n \"user-123\",\n status: \"ACTIVE\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.UpdateStatusAsync(\"user-123\", new UsersUpdateStatusParams\n{\n Status = \"ACTIVE\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Stato dell'utente aggiornato. Restituisce il record utente completo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetailItem" }, "examples": { "Blocked": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Michael Doe", "date_of_birth": "1990-05-15", "effective_name": "John Michael Doe", "status": "BLOCKED", "metadata": { "tier": "premium", "source": "website" }, "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "tag": { "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "VIP", "color": "#2567FF", "description": null, "source": "custom", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-05-01T09:00:00Z" }, "added_by_email": "analyst@acme.com", "added_by_name": "Jane Analyst", "created_at": "2025-06-02T11:00:00Z" } ], "comments": [ { "uuid": "c1111111-2222-4333-8444-555555555555", "comment_type": "STATUS_CHANGED", "comment": "Chargeback fraud pattern confirmed", "actor_email": null, "actor_name": null, "previous_status": "ACTIVE", "new_status": "BLOCKED", "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "mentioned_emails": [], "created_at": "2025-06-15T10:30:00Z" } ], "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-15T10:30:00Z" } } } } } }, "400": { "description": "`status` mancante o non valido, oppure un `reason` superiore a 1000 caratteri.", "content": { "application/json": { "examples": { "Missing status": { "value": { "status": [ "This field is required." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "401": { "description": "Nessuna credenziale fornita. Le richieste ai percorsi `/v3/users/*` senza un'intestazione `x-api-key` (o token `Authorization: Bearer`) vengono rifiutate dal middleware di autenticazione prima di raggiungere l'API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "La chiave non può aggiornare gli utenti per questa applicazione. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun utente (non eliminato) con il `vendor_data` fornito esiste per questa applicazione.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/create/": { "post": { "summary": "Crea azienda", "description": "Crea preventivamente un'[azienda](/entities/businesses) *senza* una sessione KYB. Tutti i campi sono opzionali, ma dovresti sempre inviare `vendor_data` — senza di esso il record non può essere collegato a sessioni o transazioni. Se fornito, `vendor_data` deve essere univoco tra le aziende non cancellate (corrispondenza esatta; i conflitti restituiscono 400). Non idempotente.", "operationId": "create_business", "x-didit-sdk": { "resource": "businesses", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore univoco per questa azienda (stringa a formato libero, NON un UUID). Facoltativo ma fortemente consigliato. Quando fornito, deve essere univoco tra le aziende non eliminate per l'applicazione; confrontato esattamente come inviato." }, "display_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Nome descrittivo mostrato nella console (ha la precedenza su `legal_name` per la visualizzazione dell'interfaccia utente)." }, "legal_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Denominazione legale ufficiale dell'azienda." }, "registration_number": { "type": "string", "nullable": true, "maxLength": 100, "description": "Numero di registrazione o costituzione dell'azienda." }, "country_code": { "type": "string", "nullable": true, "maxLength": 10, "description": "Paese di costituzione (ISO 3166-1 alpha-2, ad es. `GB`, `US`)." }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "default": "ACTIVE", "description": "Stato iniziale del ciclo di vita. Il valore predefinito è `ACTIVE`." }, "metadata": { "type": "object", "nullable": true, "description": "Oggetto JSON arbitrario da allegare all'azienda. Il valore predefinito è `{}`." } } }, "examples": { "Basic": { "summary": "Minimo raccomandato", "value": { "vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US" } }, "Full": { "summary": "Tutti i campi", "value": { "vendor_data": "company-789", "display_name": "New Corp", "legal_name": "New Corp International Ltd", "registration_number": "98765432", "country_code": "DE", "status": "ACTIVE", "metadata": { "industry": "fintech", "tier": "enterprise" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/businesses/create/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data\": \"company-456\", \"legal_name\": \"New Corp Ltd\", \"country_code\": \"US\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.create(\n vendor_data=\"company-456\",\n legal_name=\"New Corp Ltd\",\n country_code=\"US\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.create({\n vendor_data: \"company-456\",\n legal_name: \"New Corp Ltd\",\n country_code: \"US\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Create(ctx, didit.BusinessesCreateParams{\n\tVendorData: didit.String(\"company-456\"),\n\tLegalName: didit.String(\"New Corp Ltd\"),\n\tCountryCode: didit.String(\"US\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BusinessesCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().create(BusinessesCreateParams.builder()\n .vendorData(\"company-456\")\n .legalName(\"New Corp Ltd\")\n .countryCode(\"US\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->create([\n 'vendor_data' => 'company-456',\n 'legal_name' => 'New Corp Ltd',\n 'country_code' => 'US',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.create(\n vendor_data: \"company-456\",\n legal_name: \"New Corp Ltd\",\n country_code: \"US\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.CreateAsync(new BusinessesCreateParams\n{\n VendorData = \"company-456\",\n LegalName = \"New Corp Ltd\",\n CountryCode = \"US\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Azienda creata. Restituisce il record aziendale completo (stessa struttura di Get Business).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Created": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-456", "display_name": null, "legal_name": "New Corp Ltd", "registration_number": null, "country_code": "US", "effective_name": "New Corp Ltd", "status": "ACTIVE", "session_count": 0, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "features": {}, "features_list": [], "last_session_at": null, "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": null, "tags": [], "created_at": "2026-03-15T10:30:00Z", "metadata": {}, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "400": { "description": "Corpo non valido — in genere un `vendor_data` duplicato, uno `status` sconosciuto o `metadata` non corretti.", "content": { "application/json": { "examples": { "Duplicate": { "value": { "vendor_data": [ "A business with this vendor_data already exists." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Bad metadata": { "value": { "metadata": [ "Metadata must be a JSON object." ] } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure la chiave non può creare aziende per questa applicazione. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/users/create/": { "post": { "summary": "Crea utente", "description": "Crea un [utente](/entities/users) tramite `vendor_data`, prima o senza una sessione di verifica. `vendor_data` deve essere univoco tra gli utenti dell'applicazione (un duplicato restituisce `400`). Non idempotente.\n\n**Dati di contatto:** `email` e `phone_number` vengono memorizzati in `metadata.contact`, e `country` in `metadata.address`. Quando invii `first_name` o `last_name` senza `full_name`, Didit li unisce in `full_name`.\n\n**Link di verifica:** con `send_verification_link: true`, Didit crea anche una sessione di verifica per la persona nel workflow identificato da `workflow_id` e le invia il link via email all'indirizzo `email`. La sessione esegue gli stessi controlli di [Crea sessione](/it/sessions-api/create-session), come la blocklist e il tuo saldo crediti. La persona e la sessione vengono create insieme oppure non vengono create affatto: se un qualsiasi controllo fallisce, non viene scritto nulla e non viene inviata alcuna email. Il campo `verification_link` della risposta descrive la sessione, ed è `null` quando non richiedi un link.\n\n**Accesso con chiave API:** una chiave API con ambito limitato necessita dell'autorizzazione in scrittura su `users`. Con `send_verification_link: true` richiede anche l'autorizzazione in scrittura su `sessions`, altrimenti la chiamata risponde con `403` prima che venga scritto alcunché. Le chiavi con accesso completo non sono interessate. Consulta [Chiavi API](/it/console/api-keys).", "operationId": "create_user", "x-didit-sdk": { "resource": "users", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vendor_data" ], "properties": { "vendor_data": { "type": "string", "description": "Il tuo identificatore univoco per questo utente (stringa a formato libero, NON un UUID). Deve essere univoco tra gli utenti dell'applicazione; confrontato esattamente come inviato." }, "full_name": { "type": "string", "nullable": true, "maxLength": 512, "description": "Nome legale completo dell'utente." }, "display_name": { "type": "string", "nullable": true, "description": "Nome descrittivo mostrato nella console (ha la precedenza su `full_name` per la visualizzazione dell'interfaccia utente).", "maxLength": 255 }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data di nascita nel formato `YYYY-MM-DD`." }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "default": "ACTIVE", "description": "Stato iniziale del ciclo di vita. Il valore predefinito è `ACTIVE`." }, "metadata": { "type": "object", "nullable": true, "description": "Oggetto JSON arbitrario da allegare all'utente. Il valore predefinito è `{}`." }, "approved_emails": { "type": "array", "items": { "type": "string" }, "description": "Indirizzi email già considerati attendibili per questo utente, ad es. `[\"john@example.com\"]`." }, "approved_phones": { "type": "array", "items": { "type": "string" }, "description": "Numeri di telefono già considerati attendibili per questo utente, ad es. `[\"+14155551234\"]`." }, "issuing_states": { "type": "array", "items": { "type": "string" }, "description": "Paesi di emissione preregistrati (ISO 3166-1 alpha-3), ad es. `[\"USA\"]`." }, "first_name": { "type": "string", "maxLength": 255, "description": "Nome. Quando `full_name` non viene inviato, Didit unisce `first_name` e `last_name` con uno spazio in `full_name`. Non restituito come campo separato." }, "last_name": { "type": "string", "maxLength": 255, "description": "Cognome. Unito a `first_name` in `full_name` quando `full_name` non viene inviato. Non restituito come campo separato." }, "email": { "type": "string", "format": "email", "description": "Email di contatto, memorizzata in `metadata.contact.email` (sostituisce l'`email` inviata all'interno di `metadata.contact`). Obbligatoria quando `send_verification_link` è `true`: il link viene inviato a questo indirizzo. Se `metadata.contact` non è un oggetto JSON, la chiamata risponde `400` su questo campo." }, "phone_number": { "type": "string", "maxLength": 32, "description": "Numero di telefono di contatto, memorizzato in `metadata.contact.phone_number`. Se `metadata.contact` non è un oggetto JSON, la chiamata risponde `400` su questo campo." }, "country": { "type": "string", "maxLength": 3, "description": "Paese come codice ISO 3166, alpha-2 o alpha-3 (`ES` o `ESP`). Memorizzato in lettere maiuscole in `metadata.address.country`. Se `metadata.address` non è un oggetto JSON, la chiamata risponde `400` su questo campo." }, "send_verification_link": { "type": "boolean", "default": false, "description": "Quando è `true`, Didit crea una sessione di verifica per la persona su `workflow_id` e le invia via email il link all'indirizzo `email`. Richiede `email` e `workflow_id`. Una chiave API con ambito limitato richiede anche l'autorizzazione di scrittura per `sessions`." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Il workflow della sessione di verifica. Obbligatorio quando `send_verification_link` è `true`. Deve verificare una persona fisica: un workflow di Verifica aziendale (KYB) viene rifiutato. Ignorato altrimenti." }, "language": { "type": "string", "maxLength": 10, "description": "Lingua dell'email di verifica, come codice di una [lingua supportata](/it/integration/supported-languages). Inglese se omessa. Ignorata quando `send_verification_link` non è `true`." } } }, "examples": { "Basic": { "summary": "Crea con informazioni di base", "value": { "vendor_data": "user-abc-123", "full_name": "John Doe" } }, "Full": { "summary": "Tutti i campi", "value": { "vendor_data": "user-abc-456", "full_name": "Jane Smith", "display_name": "Jane S.", "date_of_birth": "1990-05-15", "status": "ACTIVE", "metadata": { "tier": "premium", "source": "api" }, "approved_emails": [ "jane@example.com" ] } }, "Contact details": { "summary": "Nome, email, telefono e paese", "value": { "vendor_data": "user-abc-789", "first_name": "Julia", "last_name": "Martin", "email": "julia.martin@example.com", "phone_number": "+34600000000", "country": "ES" } }, "With verification link": { "summary": "Crea la persona e invia alla persona un link di verifica via email", "value": { "vendor_data": "user-abc-789", "first_name": "Julia", "last_name": "Martin", "email": "julia.martin@example.com", "send_verification_link": true, "workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "language": "es" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/users/create/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data\": \"user-abc-123\", \"full_name\": \"John Doe\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.create(\n vendor_data=\"user-abc-123\",\n full_name=\"John Doe\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.create({\n vendor_data: \"user-abc-123\",\n full_name: \"John Doe\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Create(ctx, didit.UsersCreateParams{\n\tVendorData: \"user-abc-123\",\n\tFullName: didit.String(\"John Doe\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.UsersCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().create(UsersCreateParams.builder()\n .vendorData(\"user-abc-123\")\n .fullName(\"John Doe\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->create([\n 'vendor_data' => 'user-abc-123',\n 'full_name' => 'John Doe',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.create(\n vendor_data: \"user-abc-123\",\n full_name: \"John Doe\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.CreateAsync(new UsersCreateParams\n{\n VendorData = \"user-abc-123\",\n FullName = \"John Doe\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Utente creato. Il record utente completo (stessa struttura di Get User), più `verification_link`: la sessione di verifica inviata via email da Didit quando `send_verification_link` era `true`, altrimenti `null`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserDetailItem" }, { "type": "object", "required": [ "verification_link" ], "properties": { "verification_link": { "type": "object", "nullable": true, "description": "La sessione di verifica creata e inviata via email da Didit alla persona. Sempre presente: `null` quando `send_verification_link` non era `true`.", "required": [ "session_id", "session_number", "status", "url", "workflow_id", "email" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID della sessione di verifica." }, "session_number": { "type": "integer", "description": "Numero sequenziale della sessione all'interno della tua applicazione." }, "status": { "type": "string", "description": "Stato della sessione, `Not Started` per una sessione appena creata." }, "url": { "type": "string", "format": "uri", "description": "Il link di verifica inviato via email da Didit alla persona." }, "workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Il workflow eseguito dalla sessione." }, "email": { "type": "string", "format": "email", "description": "L'indirizzo a cui è stato inviato il link." } } } } } ] }, "examples": { "Created": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Doe", "date_of_birth": null, "effective_name": "John Doe", "status": "ACTIVE", "metadata": {}, "portrait_image_url": null, "session_count": 0, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "issuing_states": [], "approved_emails": [], "approved_phones": [], "features": {}, "features_list": [], "last_session_at": null, "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": null, "tags": [], "comments": [], "created_at": "2025-06-15T10:30:00Z", "updated_at": "2025-06-15T10:30:00Z", "verification_link": null } }, "Created with verification link": { "value": { "didit_internal_id": "9b2f6c1e-3d4a-4e5f-8a7b-1c2d3e4f5a6b", "vendor_data": "user-abc-789", "display_name": null, "full_name": "Julia Martin", "date_of_birth": null, "effective_name": "Julia Martin", "status": "ACTIVE", "metadata": { "contact": { "email": "julia.martin@example.com" } }, "portrait_image_url": null, "session_count": 1, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "issuing_states": [], "approved_emails": [], "approved_phones": [], "features": {}, "features_list": [], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-15T10:30:00Z", "tags": [], "comments": [], "created_at": "2025-06-15T10:30:00Z", "updated_at": "2025-06-15T10:30:00Z", "verification_link": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa7", "session_number": 43762, "status": "Not Started", "url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz", "workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "email": "julia.martin@example.com" } } } } } } }, "400": { "description": "Corpo non valido, indicizzato per campo: in genere un `vendor_data` duplicato, un campo obbligatorio mancante o un valore non valido. Con `send_verification_link: true`, anche un `email` o un `workflow_id` mancante, un workflow sconosciuto o di Verifica aziendale (KYB), una `language` non supportata (indicizzata come `contact_details.email_lang`), un `vendor_data` presente in blocklist o crediti insufficienti per avviare la sessione. Non viene scritto nulla.", "content": { "application/json": { "examples": { "Duplicate": { "value": { "vendor_data": [ "A user with this vendor_data already exists." ] } }, "Missing vendor_data": { "value": { "vendor_data": [ "This field is required." ] } }, "Bad metadata": { "value": { "metadata": [ "Metadata must be a JSON object." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Bad country": { "value": { "country": [ "Use an ISO 3166 country code, like ES or ESP." ] } }, "Contact not an object": { "value": { "email": [ "metadata.contact must be a JSON object to store this value." ] } }, "Address not an object": { "value": { "country": [ "metadata.address must be a JSON object to store this value." ] } }, "Link without email or workflow": { "value": { "email": [ "An email address is required to send a verification link." ], "workflow_id": [ "Pick the workflow to send a verification link for." ] } }, "Unknown workflow": { "value": { "workflow_id": [ "Invalid workflow_id." ] } }, "Business workflow": { "value": { "workflow_id": [ "This workflow verifies a business. Pick a workflow that verifies a person to send them a verification link." ] } }, "Blocklisted vendor_data": { "value": { "vendor_data": "This user or business has been blocked and cannot create new verification sessions." } }, "Insufficient credits": { "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "401": { "description": "Nessuna credenziale fornita. Le richieste ai percorsi `/v3/users/*` senza un'intestazione `x-api-key` (o token `Authorization: Bearer`) vengono rifiutate dal middleware di autenticazione prima di raggiungere l'API.", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "Chiave API non valida o revocata, oppure la chiave non può creare utenti per questa applicazione. Una chiave API con restrizioni d'ambito necessita dei permessi di scrittura su `users` e anche di scrittura su `sessions` quando `send_verification_link` è `true`; non viene scritto nulla. Una chiave mancante restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } }, "No sessions write": { "summary": "La chiave con ambito richiede un link di verifica senza autorizzazione di scrittura su sessions", "value": { "detail": "This API key has no write access to sessions." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/": { "post": { "summary": "Carica il volto dell'utente", "description": "Collega un'immagine del volto importata e affidabile a un profilo Utente esistente. Usa questo endpoint dopo aver creato o recuperato un Utente tramite `vendor_data` e aver letto il suo `didit_internal_id`. Il volto caricato viene memorizzato nel profilo Utente e indicizzato per il rilevamento dei duplicati e la ricerca facciale. Non viene aggiunto a una blocklist facciale.", "operationId": "upload_user_face", "x-didit-sdk": { "resource": "users", "method": "upload_face", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Users" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione proprietaria dell'applicazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione a cui appartiene il profilo utente." }, { "name": "didit_internal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID utente interno di Didit, restituito come `didit_internal_id` da `GET /v3/users/{vendor_data}/` e `POST /v3/users/create/`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "format": "byte", "description": "Immagine del volto in formato JPG o PNG non elaborata con codifica base64. Non includere il prefisso `data:image/...;base64,`. Dimensione massima decodificata: 2 MB." }, "comment": { "type": "string", "description": "Nota opzionale visibile all'operatore per il volto caricato.", "default": "" } } }, "examples": { "Imported face": { "summary": "Collega un volto importato da un provider precedente", "value": { "image": "/9j/4AAQSkZJRgABAQEA...", "comment": "Imported from previous KYC provider" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/vendor-users/by-id/f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418/faces/upload/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"image\": \"/9j/4AAQSkZJRgABAQEA...\", \"comment\": \"Imported from previous KYC provider\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image=\"/9j/4AAQSkZJRgABAQEA...\",\n comment=\"Imported from previous KYC provider\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.uploadFace(\"11111111-2222-3333-4444-555555555555\", {\n image: \"/9j/4AAQSkZJRgABAQEA...\",\n comment: \"Imported from previous KYC provider\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.UsersUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQEA...\",\n\tComment: didit.String(\"Imported from previous KYC provider\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.UsersUploadFaceParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().uploadFace(\"11111111-2222-3333-4444-555555555555\", UsersUploadFaceParams.builder()\n .image(\"/9j/4AAQSkZJRgABAQEA...\")\n .comment(\"Imported from previous KYC provider\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->uploadFace('11111111-2222-3333-4444-555555555555', [\n 'image' => '/9j/4AAQSkZJRgABAQEA...',\n 'comment' => 'Imported from previous KYC provider',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image: \"/9j/4AAQSkZJRgABAQEA...\",\n comment: \"Imported from previous KYC provider\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.UploadFaceAsync(\"11111111-2222-3333-4444-555555555555\", new UsersUploadFaceParams\n{\n Image = \"/9j/4AAQSkZJRgABAQEA...\",\n Comment = \"Imported from previous KYC provider\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Volto caricato e collegato al profilo utente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "uuid", "image_url", "comment", "uploaded_by", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID del record del volto dell'utente caricato." }, "image_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL firmato per l'immagine del volto caricata." }, "comment": { "type": "string", "nullable": true, "description": "Commento fornito al momento del caricamento del volto." }, "uploaded_by": { "type": "string", "nullable": true, "description": "Email o identificatore del soggetto che ha effettuato il caricamento, se disponibile." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp del caricamento." } } }, "examples": { "Uploaded": { "value": { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "image_url": "https://signed-url.example/face.jpg", "comment": "Imported from previous KYC provider", "uploaded_by": "api", "created_at": "2026-05-18T12:00:00Z" } } } } } }, "400": { "description": "Corpo della richiesta o immagine non validi. Cause frequenti: base64 non valido, immagine non valida, nessun volto rilevabile, immagine superiore a 2 MB, embedding mancante o l'utente ha già caricato 5 volti.", "content": { "application/json": { "examples": { "No face": { "value": { "image": "No face detected in the image. Please upload a clear photo with a visible face." } }, "Too many faces": { "value": { "detail": "Maximum of 5 faces per user reached." } }, "Too large": { "value": { "image": "Image exceeds maximum size of 2 MB." } } } } } }, "401": { "description": "Chiave API mancante o non valida.", "content": { "application/json": { "examples": { "Missing key": { "value": { "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "La credenziale è valida ma non dispone dei permessi di scrittura dei profili User per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Nessun utente esiste per tale `didit_internal_id` nell'applicazione.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "Limite di frequenza superato; rallenta e riprova.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/update-data/": { "patch": { "summary": "Aggiorna i dati KYC estratti dal documento di identità in una sessione di verifica", "description": "Correggi i campi di identità estratti (OCR / NFC) dal documento d'identità dell'utente — nomi letti erroneamente, date, numeri di documento e così via — dopo il completamento della verifica. I chiamanti tipici sono un analista della compliance che opera dal tuo back office o un processo di riconciliazione automatizzato. Ogni campo nel corpo della richiesta è facoltativo: vengono scritte solo le chiavi inviate, mentre tutto il resto rimane invariato (semantica `PATCH`).\n\nLa sessione deve appartenere alla tua applicazione e trovarsi nello stato `Approved`, `Declined`, `In Review` o `Kyc Expired`. Le sessioni in qualsiasi altro stato (ad es. ancora `In Progress`) restituiscono `404` con `\"No Session matches the given query.\"` — differente da `\"Not found.\"` restituito per un `sessionId` sconosciuto o eliminato. La sessione deve inoltre contenere un record di verifica dell'identità (KYC): le sessioni il cui workflow non ha mai eseguito un passaggio di verifica dell'identità restituiscono `404` (`\"The session does not have a KYC.\"`). Per i workflow a grafo con più passaggi di verifica dell'identità, seleziona un passaggio specifico con `node_id` (parametro di query o campo del corpo); se omesso, viene applicata la patch al record KYC più recente.\n\nDue campi derivati vengono ricalcolati a ogni chiamata: `full_name` (da `first_name` + `last_name`) e `issuing_state_name` (da `issuing_state`). Se il campo di testo libero `address` cambia, il server potrebbe anche ripetere la geocodifica e aggiornare `parsed_address` (operazione ignorata per le sessioni sandbox). `extra_fields` e `parsed_address` vengono uniti chiave per chiave anziché sostituiti — consulta le descrizioni dei singoli campi per la semantica di eliminazione tramite `null`.\n\nL'invio di almeno un campo valido attiva il [webhook](/it/integration/webhooks) `data.updated` (trigger `manual_review`) — anche quando i valori inviati sono identici a quelli memorizzati. Quando i valori cambiano effettivamente, una voce di attività `KYC_DATA_UPDATED` che registra i campi modificati con i valori precedenti e nuovi viene aggiunta a `reviews` della sessione, visibile in [Get Decision](#get-/v3/session/-sessionId-/decision/) e nella cronologia delle attività della console. Lo stato e la decisione della sessione **non** vengono rivalutati — usa [Update Status](#patch-/v3/session/-sessionId-/update-status/) per modificare l'esito. È accettato un corpo JSON vuoto (`{}`) che si limita a restituire i dati KYC correnti senza attivare il webhook.\n\nAccetta una chiave API o un token utente della console; in entrambi i casi la credenziale richiede l'autorizzazione `write:sessions`. Sia gli errori di autenticazione sia quelli di autorizzazione restituiscono `403` — questa API non risponde mai con `401`. Tieni presente che la ricerca della sessione viene eseguita prima dei controlli delle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche in assenza di credenziali. Questo endpoint ha un limite di frequenza dedicato di 10 richieste al minuto per chiave API (vengono conteggiate anche le richieste non valide); si applica inoltre il budget di scrittura condiviso di 300 richieste al minuto.", "operationId": "patch_v3_session_update_data", "x-didit-sdk": { "resource": "sessions", "method": "update_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica degli utenti (KYC) di cui stai correggendo i dati estratti dal documento. Gli ID di sessione aziendale (KYB) non sono validi qui — per i dati aziendali usa [Update KYB Company Data](#patch-/v3/session/-sessionId-/kyb/-companyUuid-/update-data/).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nodo del grafo del workflow di cui aggiornare parzialmente il record KYC, per workflow a grafo con più passaggi di verifica dell'identità (accettato anche come campo `node_id` nel corpo). Se omesso, viene aggiornato il record KYC più recente della sessione. Se non esiste alcun KYC per il nodo specificato, la chiamata restituisce `404` (`\"The session does not have a KYC for node ''.\"`).", "schema": { "type": "string", "example": "feature_ocr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Tutti i campi sono facoltativi — invia solo ciò che desideri modificare.", "properties": { "document_type": { "type": "string", "description": "Codice del tipo di documento. Accetta i codici brevi elencati nell'enum, più sei alias in formato esteso normalizzati lato server prima della validazione: `Passport` → `P`, `Identity Card` → `ID`, `Driver's License` → `DL`, `Residence Permit` → `RP`, `Health Insurance Card` → `HIC`, `Tax Card` → `TC`. Qualsiasi altro valore (incluso `PASSPORT` in maiuscolo) restituisce `400`.", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "nullable": true, "example": "P" }, "document_subtype": { "type": "string", "maxLength": 128, "nullable": true, "description": "Sottotipo di documento dal registro dei documenti, incluso il prefisso regionale quando il registro distingue le varianti regionali." }, "document_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Numero del documento come stampato sul documento d'identità.", "example": "PAB123456" }, "personal_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Numero di identificazione personale/nazionale se presente sul documento (ad es. DNI spagnolo su un passaporto).", "example": "99999999R" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data di nascita in `YYYY-MM-DD`. Qualsiasi altro formato restituisce `400`.", "example": "1980-01-01" }, "date_of_issue": { "type": "string", "format": "date", "nullable": true, "description": "Data di emissione del documento nel formato `YYYY-MM-DD`." }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "Data di scadenza del documento in `YYYY-MM-DD`." }, "issuing_state": { "type": "string", "nullable": true, "description": "Paese di emissione come codice ISO 3166-1 alpha-3. Senza distinzione tra maiuscole e minuscole (`esp` viene memorizzato come `ESP`); il valore leggibile `issuing_state_name` mostrato in [Get Decision](#get-/v3/session/-sessionId-/decision/) viene ricalcolato a partire da questo valore. I codici non validi restituiscono `400`.", "example": "ESP" }, "first_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Nome/i. Il valore memorizzato di `full_name` viene ricalcolato come `first_name + ' ' + last_name` a ogni chiamata a questo endpoint.", "example": "Carmen" }, "last_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Cognome/i. Alimenta anche il `full_name` ricalcolato.", "example": "Espanola Espanola" }, "gender": { "type": "string", "enum": [ "M", "F", "U" ], "nullable": true, "description": "Sesso riportato sul documento: `M` (maschio), `F` (femmina) o `U` (sconosciuto). Qualsiasi altro valore — incluso `X` — restituisce `400`." }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "Indirizzo a testo libero così come stampato sul documento. Quando questo valore cambia (solo per le sessioni non sandbox) e l'indirizzo strutturato è ancora mancante o incompleto, il server esegue nuovamente la geocodifica in modo sincrono prima di rispondere: il corpo della risposta con stato 200 riflette già il valore aggiornato di `parsed_address`. La nuova geocodifica richiede inoltre la presenza di `issuing_state` nel record KYC." }, "place_of_birth": { "type": "string", "maxLength": 255, "nullable": true, "description": "Luogo di nascita come stampato sul documento." }, "nationality": { "type": "string", "maxLength": 32, "nullable": true, "description": "Nazionalità come stampata sul documento. Testo libero fino a 32 caratteri — tipicamente un codice ISO 3166-1 alpha-3 (ad es. `ESP`), ma non convalidato come tale." }, "marital_status": { "type": "string", "enum": [ "SINGLE", "MARRIED", "DIVORCED", "WIDOWED", "UNKNOWN" ], "description": "Stato civile se presente sul documento. Qualsiasi altro valore restituisce `400`." }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Sostituzioni per chiave per campi aggiuntivi specifici del documento (ad es. `blood_group`, `dl_categories`, `mrz_string`). Le chiavi vengono unite nella mappa di sostituzione esistente: invia una chiave con un valore per impostarla, oppure con `null` / `\"\"` per rimuovere tale chiave dalla vista unita. Invia l'intero campo come `null` per cancellare tutte le sostituzioni applicate in precedenza. Deve essere un oggetto JSON, altrimenti `400`. La risposta restituisce sempre la vista unita (valori estratti da OCR con le tue sostituzioni applicate)." }, "parsed_address": { "type": "object", "nullable": true, "description": "Indirizzo strutturato. Vengono accettate solo queste chiavi nidificate: `address_type`, `city`, `region`, `street_1`, `street_2`, `postal_code`, `country` — qualsiasi altra chiave restituisce `400`. Semantica per chiave: un valore imposta la chiave, `null` la rimuove. `formatted_address` viene ricalcolato lato server unendo `street_1`, `street_2`, `city`, `region`, `postal_code` e `country` e viene restituito nella risposta — non puoi impostarlo direttamente.", "properties": { "address_type": { "type": "string", "nullable": true, "description": "Classificazione dell'indirizzo a testo libero (es. `home`)." }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "Stato / provincia / comunità autonoma." }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "Codice paese ISO 3166-1 alpha-2. L'input in lettere minuscole viene normalizzato in maiuscolo; i codici alpha-3 vengono rifiutati con `400`.", "example": "ES" } } } } }, "examples": { "Correct name and DOB": { "summary": "Correggi il nome letto erroneamente dall'OCR, la data di nascita e l'indirizzo strutturato", "value": { "first_name": "Carmen", "last_name": "Espanola Espanola", "date_of_birth": "1980-01-01", "issuing_state": "ESP", "marital_status": "MARRIED", "extra_fields": { "blood_group": "O+" }, "parsed_address": { "street_1": "Avda de Madrid 34", "city": "Madrid", "postal_code": "28013", "country": "ES" } } }, "Remove an extra field": { "summary": "Elimina una chiave di un campo extra, mantieni il resto", "value": { "extra_fields": { "blood_group": null } } }, "Long-form document type": { "summary": "L'alias in formato esteso viene normalizzato nel codice breve (qui P)", "value": { "document_type": "Passport" } } } } } }, "responses": { "200": { "description": "Dati KYC aggiornati. Restituisce il **record KYC attuale completo** (ogni campo aggiornabile con il relativo valore memorizzato, oltre ai campi `extra_fields` uniti e al valore `parsed_address` corrente) — non solo i campi inviati. Il webhook `data.updated` viene attivato quando nel payload è presente almeno un campo valido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "document_type": { "type": "string", "description": "Codice del tipo di documento. Accetta i codici brevi elencati nell'enum, più sei alias in formato esteso normalizzati lato server prima della validazione: `Passport` → `P`, `Identity Card` → `ID`, `Driver's License` → `DL`, `Residence Permit` → `RP`, `Health Insurance Card` → `HIC`, `Tax Card` → `TC`. Qualsiasi altro valore (incluso `PASSPORT` in maiuscolo) restituisce `400`.", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "nullable": true, "example": "P" }, "document_subtype": { "type": "string", "maxLength": 128, "nullable": true, "description": "Sottotipo di documento dal registro dei documenti, incluso il prefisso regionale quando il registro distingue le varianti regionali." }, "document_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Numero del documento come stampato sul documento d'identità.", "example": "PAB123456" }, "personal_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "Numero di identificazione personale/nazionale se presente sul documento (ad es. DNI spagnolo su un passaporto).", "example": "99999999R" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data di nascita in `YYYY-MM-DD`. Qualsiasi altro formato restituisce `400`.", "example": "1980-01-01" }, "date_of_issue": { "type": "string", "format": "date", "nullable": true, "description": "Data di emissione del documento nel formato `YYYY-MM-DD`." }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "Data di scadenza del documento in `YYYY-MM-DD`." }, "issuing_state": { "type": "string", "nullable": true, "description": "Paese di emissione come codice ISO 3166-1 alpha-3. Senza distinzione tra maiuscole e minuscole (`esp` viene memorizzato come `ESP`); il valore leggibile `issuing_state_name` mostrato in [Get Decision](#get-/v3/session/-sessionId-/decision/) viene ricalcolato a partire da questo valore. I codici non validi restituiscono `400`.", "example": "ESP" }, "first_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Nome/i. Il valore memorizzato di `full_name` viene ricalcolato come `first_name + ' ' + last_name` a ogni chiamata a questo endpoint.", "example": "Carmen" }, "last_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "Cognome/i. Alimenta anche il `full_name` ricalcolato.", "example": "Espanola Espanola" }, "gender": { "type": "string", "enum": [ "M", "F", "U" ], "nullable": true, "description": "Sesso riportato sul documento: `M` (maschio), `F` (femmina) o `U` (sconosciuto). Qualsiasi altro valore — incluso `X` — restituisce `400`." }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "Indirizzo a testo libero così come stampato sul documento. Quando questo valore cambia (solo per sessioni non sandbox) e l'indirizzo strutturato è ancora mancante o incompleto, il server esegue nuovamente la geocodifica in background della stessa richiesta e potrebbe sovrascrivere `parsed_address` con il risultato del geocodificatore." }, "place_of_birth": { "type": "string", "maxLength": 255, "nullable": true, "description": "Luogo di nascita come stampato sul documento." }, "nationality": { "type": "string", "maxLength": 32, "nullable": true, "description": "Nazionalità come stampata sul documento. Testo libero fino a 32 caratteri — tipicamente un codice ISO 3166-1 alpha-3 (ad es. `ESP`), ma non convalidato come tale." }, "marital_status": { "type": "string", "enum": [ "SINGLE", "MARRIED", "DIVORCED", "WIDOWED", "UNKNOWN" ], "description": "Stato civile se presente sul documento. Qualsiasi altro valore restituisce `400`." }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Vista combinata dei campi extra del documento: i valori estratti tramite OCR con tutte le sovrascritture dell'operatore applicate. Le chiavi rimosse tramite una sovrascrittura con `null` sono assenti da questa mappa." }, "parsed_address": { "type": "object", "nullable": true, "description": "Indirizzo strutturato attuale (senza le chiavi di gestione interna), oppure `null` quando non ne esiste alcuno. Include il `formatted_address` ricalcolato insieme alle sette chiavi modificabili.", "properties": { "address_type": { "type": "string", "nullable": true, "description": "Classificazione dell'indirizzo a testo libero (es. `home`)." }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "Stato / provincia / comunità autonoma." }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "Codice paese ISO 3166-1 alpha-2. L'input in lettere minuscole viene normalizzato in maiuscolo; i codici alpha-3 vengono rifiutati con `400`.", "example": "ES" }, "formatted_address": { "type": "string", "nullable": true, "description": "Forma unificata e leggibile dell'indirizzo strutturato. Ricalcolata lato server dopo ogni modifica a `parsed_address`.", "example": "Avda de Madrid 34, Madrid, 28013, ES" } } } } }, "examples": { "Updated KYC": { "summary": "Record KYC completo dopo la correzione", "value": { "document_type": "P", "document_subtype": null, "document_number": "PAB123456", "personal_number": "99999999R", "date_of_birth": "1980-01-01", "date_of_issue": "2021-02-09", "expiration_date": "2031-02-08", "issuing_state": "ESP", "first_name": "Carmen", "last_name": "Espanola Espanola", "gender": "F", "address": "AVDA DE MADRID 34, MADRID, MADRID 28013", "place_of_birth": "MADRID", "nationality": "ESP", "marital_status": "MARRIED", "extra_fields": { "mrz_string": "P\": [\"\"]}`; gli errori sulle chiavi nidificate di `parsed_address` / `extra_fields` utilizzano un valore oggetto: `{\"parsed_address\": {\"\": \"\"}}`.", "content": { "application/json": { "examples": { "Invalid gender": { "summary": "gender deve essere M, F o U", "value": { "gender": [ "\"X\" is not a valid choice." ] } }, "Invalid document type": { "summary": "Non è un codice breve o un alias esteso", "value": { "document_type": [ "\"PASSPORT\" is not a valid choice." ] } }, "Invalid issuing state": { "summary": "issuing_state non è in formato ISO 3166-1 alpha-3", "value": { "issuing_state": [ "Invalid ISO 3166-1 alpha-3 country code for issuing_state." ] } }, "Invalid marital status": { "summary": "marital_status non presente nell'enum", "value": { "marital_status": [ "\"ENGAGED\" is not a valid choice." ] } }, "Bad date format": { "summary": "Le date devono essere YYYY-MM-DD", "value": { "date_of_birth": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Unsupported parsed_address key": { "summary": "Sono consentite solo le sette chiavi documentate", "value": { "parsed_address": { "zipcode": "Unsupported key. Allowed keys: address_type, city, region, street_1, street_2, postal_code, country" } } }, "Invalid parsed_address country": { "summary": "Il paese nidificato deve essere in formato alpha-2, non alpha-3", "value": { "parsed_address": { "country": "Invalid ISO 3166-1 alpha-2 country code." } } }, "extra_fields not an object": { "summary": "extra_fields deve essere un oggetto JSON", "value": { "extra_fields": [ "This field must be a JSON object." ] } } } } } }, "403": { "description": "Credenziali mancanti o autorizzazioni insufficienti. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "La credenziale non dispone di write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Sessione sconosciuta, sessione in uno stato non modificabile o nessun record KYC da aggiornare. Ciascun caso ha un messaggio `detail` distinto (vedi esempi). La ricerca della sessione sconosciuta viene eseguita prima dei controlli delle credenziali.", "content": { "application/json": { "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID nella tua applicazione (oppure è stata eliminata)", "value": { "detail": "Not found." } }, "Wrong session state": { "summary": "La sessione esiste ma non è Approved / Declined / In Review / Kyc Expired", "value": { "detail": "No Session matches the given query." } }, "No KYC record": { "summary": "Il workflow non ha mai eseguito un passaggio di Verifica dell'identità", "value": { "detail": "The session does not have a KYC." } }, "No KYC for node": { "summary": "node_id specificato ma non esiste alcun KYC associato", "value": { "detail": "The session does not have a KYC for node 'feature_missing'." } } } } } }, "429": { "description": "Limite di frequenza dedicato superato — 10 aggiornamenti dei dati KYC al minuto per chiave API (le richieste rifiutate vengono conteggiate nel budget). Anche il budget di scrittura condiviso di 300/min può attivarsi con il proprio messaggio. Controlla `Retry-After` e le intestazioni di risposta `X-RateLimit-*` prima di effettuare un nuovo tentativo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Budget di aggiornamento KYC esaurito", "value": { "detail": "Session KYC data update rate limit exceeded. You can make up to 10 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-data/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"first_name\": \"Carmen\",\n \"last_name\": \"Espanola Espanola\",\n \"date_of_birth\": \"1980-01-01\",\n \"issuing_state\": \"ESP\",\n \"parsed_address\": {\n \"street_1\": \"Avda de Madrid 34\",\n \"city\": \"Madrid\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\"\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_data(\n \"11111111-2222-3333-4444-555555555555\",\n date_of_birth=\"1980-01-01\",\n issuing_state=\"ESP\",\n first_name=\"Carmen\",\n last_name=\"Espanola Espanola\",\n marital_status=\"MARRIED\",\n extra_fields={\"blood_group\": \"O+\"},\n parsed_address={\n \"city\": \"Madrid\",\n \"street_1\": \"Avda de Madrid 34\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateData(\"11111111-2222-3333-4444-555555555555\", {\n date_of_birth: \"1980-01-01\",\n issuing_state: \"ESP\",\n first_name: \"Carmen\",\n last_name: \"Espanola Espanola\",\n marital_status: \"MARRIED\",\n extra_fields: { blood_group: \"O+\" },\n parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateData(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateDataParams{\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tIssuingState: didit.String(\"ESP\"),\n\tFirstName: didit.String(\"Carmen\"),\n\tLastName: didit.String(\"Espanola Espanola\"),\n\tMaritalStatus: didit.Some(didit.SessionsUpdateDataParamsMaritalStatus(\"MARRIED\")),\n\tExtraFields: didit.Some(map[string]any{\"blood_group\": \"O+\"}),\n\tParsedAddress: didit.Some(didit.SessionsUpdateDataParamsParsedAddress{\n\t\tCity: didit.String(\"Madrid\"),\n\t\tStreet1: didit.String(\"Avda de Madrid 34\"),\n\t\tPostalCode: didit.String(\"28013\"),\n\t\tCountry: didit.String(\"ES\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdateDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateData(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateDataParams.builder()\n .dateOfBirth(LocalDate.parse(\"1980-01-01\"))\n .issuingState(\"ESP\")\n .firstName(\"Carmen\")\n .lastName(\"Espanola Espanola\")\n .maritalStatus(SessionsUpdateDataParams.MaritalStatus.of(\"MARRIED\"))\n .extraFields(Map.of(\"blood_group\", \"O+\"))\n .parsedAddress(SessionsUpdateDataParams.ParsedAddress.builder()\n .city(\"Madrid\")\n .street1(\"Avda de Madrid 34\")\n .postalCode(\"28013\")\n .country(\"ES\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateData('11111111-2222-3333-4444-555555555555', [\n 'date_of_birth' => '1980-01-01',\n 'issuing_state' => 'ESP',\n 'first_name' => 'Carmen',\n 'last_name' => 'Espanola Espanola',\n 'marital_status' => 'MARRIED',\n 'extra_fields' => ['blood_group' => 'O+'],\n 'parsed_address' => [\n 'city' => 'Madrid',\n 'street_1' => 'Avda de Madrid 34',\n 'postal_code' => '28013',\n 'country' => 'ES',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_data(\n \"11111111-2222-3333-4444-555555555555\",\n date_of_birth: \"1980-01-01\",\n issuing_state: \"ESP\",\n first_name: \"Carmen\",\n last_name: \"Espanola Espanola\",\n marital_status: \"MARRIED\",\n extra_fields: { blood_group: \"O+\" },\n parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateDataAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateDataParams\n{\n DateOfBirth = \"1980-01-01\",\n IssuingState = \"ESP\",\n FirstName = \"Carmen\",\n LastName = \"Espanola Espanola\",\n MaritalStatus = new SessionsUpdateDataParamsMaritalStatus(\"MARRIED\"),\n ExtraFields = new Dictionary { [\"blood_group\"] = \"O+\" },\n ParsedAddress = new SessionsUpdateDataParamsParsedAddress\n {\n City = \"Madrid\",\n Street1 = \"Avda de Madrid 34\",\n PostalCode = \"28013\",\n Country = \"ES\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/features/{nodeId}/update-status/": { "patch": { "summary": "Aggiorna lo stato di una singola funzionalità (passaggio)", "description": "Imposta lo stato di una singola funzionalità di verifica (passaggio) all'interno di una sessione. Seleziona la funzionalità tramite il suo `nodeId` nel grafo del workflow. Nei workflow senza grafo, i cui passaggi non hanno nodi, usa `default` e passa anche `feature_type` per indicare a quale passaggio ti riferisci.\n\nFunziona sia per le sessioni di Verifica degli utenti (KYC) sia per quelle di Verifica aziendale (KYB) e per ogni tipo di passaggio: ID/OCR, Rilevamento della vitalità, Confronto facciale, NFC, AML, Prova di residenza, Verifica telefonica, Verifica email, Validazione su database, Questionari e i controlli KYB su registro / documenti / persone chiave. Questo endpoint **non** è disponibile per le sessioni API standalone (`session_type = API`).\n\n`new_status` deve essere `Approved`, `Declined` o `In Review` e deve differire dallo stato attuale della funzionalità.\n\n**Quando viene applicato l'override.** Senza `defer_until_flow_finishes` (o con `false`), l'override viene applicato immediatamente, come sempre; quando la persona è ancora nel flusso, viene registrato come `forced`. Con `defer_until_flow_finishes: true` mentre la persona è ancora nel flusso (la sessione è `Not Started`, `In Progress` o `Resubmitted` e non è terminata), l'override viene memorizzato come `pending_until_flow_finishes` e applicato al termine del flusso, dopo che quest'ultimo ha raggiunto la propria decisione. Su una sessione il cui flusso è già terminato, viene applicato immediatamente in entrambi i casi. Un override in attesa viene invece annullato se la persona ripete il passaggio prima di terminare, se un override più recente sullo stesso controllo lo sostituisce, se la sessione abbandona il flusso prima del termine (abbandonata, scaduta o decisa a metà flusso), oppure se lo annulli con `POST /v3/session/{sessionId}/features/overrides/{overrideId}/cancel/`. Visualizza gli override di una sessione con `GET /v3/session/{sessionId}/features/overrides/`.\n\n**Effetto sulla sessione.** Una sessione che ha già una decisione la mantiene: cambia solo il controllo. Quando la sessione non ha ancora una decisione e il suo workflow è in attesa proprio di questo passaggio, l'applicazione dell'override completa il passaggio: il workflow prosegue, i passaggi successivi vengono eseguiti e un nodo di stato può impostare la decisione della sessione e attivare `status.updated`.\n\n**Webhook e attività.** Un webhook `data.updated` viene inviato quando l'override viene applicato (immediatamente o al termine del flusso), mai mentre è in attesa o quando viene annullato. Ogni override viene registrato nell'attività della sessione come `FEATURE_OVERRIDE_PENDING`, `FEATURE_OVERRIDE_APPLIED` o `FEATURE_OVERRIDE_CANCELLED`, insieme a chi lo ha effettuato; la voce della richiesta include il tuo `comment`.\n\nAutenticati con la tua chiave API (`x-api-key`) o con un'intestazione di autorizzazione utente che include il privilegio `write:sessions`; una chiave API con ambito limitato necessita dell'accesso in scrittura alle decisioni.", "operationId": "patch_v3_session_update_feature_status", "x-didit-sdk": { "resource": "sessions", "method": "update_feature_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB): il servizio risolve l'ID per entrambi i tipi di sessione.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "in": "path", "name": "nodeId", "required": true, "description": "ID del nodo del grafo del workflow della funzionalità da aggiornare (ad esempio `feature_ocr_1`). Usa il valore letterale `default` per i workflow non basati su grafo (a singolo passaggio) in cui la funzionalità non ha un ID nodo.", "schema": { "type": "string", "example": "feature_ocr_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string", "description": "Stato di destinazione per questa funzionalità. Deve differire dal valore attuale.", "enum": [ "Approved", "Declined", "In Review" ], "example": "Approved" }, "comment": { "type": "string", "description": "Nota opzionale a testo libero registrata nella traccia di revisione della sessione per questa modifica della funzionalità.", "example": "Document manually verified by compliance." }, "feature_type": { "type": "string", "enum": [ "ID_VERIFICATION", "OCR", "OCR_BACK", "NFC", "LIVENESS", "FACE", "AGE_ESTIMATION", "AGE_VERIFICATION", "FACE_SEARCH", "FACE_MATCH", "IP_ANALYSIS", "AML", "PHONE", "PHONE_VERIFICATION", "EMAIL", "EMAIL_VERIFICATION", "POA", "PROOF_OF_ADDRESS", "DATABASE_VALIDATION", "DATA_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "BANK_VERIFICATION", "GEOLOCATION" ], "description": "A quale tipo di passaggio puntare. Necessario sui workflow non a grafo (`nodeId` = `default`), dove i passaggi non condividono alcun nodo; facoltativo negli altri casi. Un valore sconosciuto restituisce `400`.", "example": "LIVENESS" }, "defer_until_flow_finishes": { "type": "boolean", "default": false, "description": "Mentre la persona è ancora nel flusso, memorizza l'override come `pending_until_flow_finishes` e applicalo al termine del flusso, anziché immediatamente. Se omesso o impostato su `false`, l'override viene applicato immediatamente. Su una sessione il cui flusso è già terminato, viene comunque applicato immediatamente.", "example": false } } }, "examples": { "Apply Now": { "summary": "Approva subito il passaggio ID", "value": { "new_status": "Approved", "comment": "Document manually verified by compliance." } }, "Wait For The Flow": { "summary": "Approva il passaggio di rilevamento della vitalità non appena la persona completa il flusso", "value": { "new_status": "Approved", "comment": "Liveness retried with a reviewer present.", "defer_until_flow_finishes": true } }, "Non-graph Workflow": { "summary": "Indirizza il passaggio di rilevamento della vitalità di un workflow senza nodi (nodeId = default)", "value": { "new_status": "In Review", "feature_type": "LIVENESS" } } } } } }, "responses": { "200": { "description": "L'override è stato registrato. `new_status` è lo stato del controllo così come memorizzato: quello richiesto una volta applicato l'override, quello invariato mentre attende il completamento del flusso. `override` indica quale delle due situazioni si è verificata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "nullable": true, "description": "Il nodo del workflow del passaggio aggiornato, oppure `null` per un passaggio senza nodo (il percorso `default` in un workflow non a grafo).", "example": "feature_ocr_1" }, "feature_type": { "type": "string", "description": "Nome del modello della funzionalità aggiornata (ad es. `KYC`, `Face`, `FaceMatch`, `AML`, `POA`).", "example": "KYC" }, "new_status": { "type": "string", "description": "Lo stato memorizzato del controllo: quello richiesto una volta applicato l'override, quello invariato mentre l'override è in attesa che il flusso termini.", "example": "Approved" }, "override": { "$ref": "#/components/schemas/FeatureStatusOverride" } }, "required": [ "session_id", "node_id", "feature_type", "new_status", "override" ] }, "examples": { "Applied": { "summary": "L'override applicato immediatamente", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "node_id": "feature_ocr_1", "feature_type": "KYC", "new_status": "Approved", "override": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "node_id": "feature_ocr_1", "feature_type": "", "feature_model": "KYC", "previous_status": "In Review", "new_status": "Approved", "state": "applied", "forced": false, "reason": "Document manually verified by compliance.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": "2026-10-13T09:15:00Z", "cancelled_at": null, "cancel_reason": null } } }, "Waiting For The Flow": { "summary": "defer_until_flow_finishes mentre la persona è ancora nel flusso", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "node_id": "feature_liveness_1", "feature_type": "Face", "new_status": "Declined", "override": { "id": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3", "node_id": "feature_liveness_1", "feature_type": "", "feature_model": "Face", "previous_status": "Declined", "new_status": "Approved", "state": "pending_until_flow_finishes", "forced": false, "reason": "Liveness retried with a reviewer present.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": null, "cancelled_at": null, "cancel_reason": null } } } } } } }, "400": { "description": "Errore di validazione. Restituito quando `new_status` non è valido o non è cambiato, quando `feature_type` è sconosciuto, oppure quando la sessione è una sessione API autonoma.", "content": { "application/json": { "examples": { "Same Status": { "summary": "new_status corrisponde allo stato attuale", "value": { "new_status": [ "The new status is the same as the current status." ] } }, "API Session": { "summary": "Lo stato della funzionalità non può essere modificato nelle sessioni API autonome", "value": [ "Cannot change feature status for API sessions." ] }, "Unknown feature_type": { "summary": "feature_type non è un tipo di passaggio noto", "value": { "feature_type": [ "Unknown feature_type 'SELFIE'." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chiave API con ambito oltre la sua data di scadenza", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenziali mancanti o autorizzazioni insufficienti.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "La chiave API non dispone dell'autorizzazione write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chiave API con ambito priva di accesso in scrittura alle decisioni", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "La sessione non è stata trovata o non include alcuna funzionalità con il `nodeId` specificato.", "content": { "application/json": { "examples": { "Session Not Found": { "summary": "session_id sconosciuto", "value": { "detail": "Session not found." } }, "Feature Not Found": { "summary": "Nessuna funzionalità per questo node_id", "value": { "detail": "No feature found with node_id 'feature_ocr_1' in this session." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/features/feature_ocr_1/update-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"new_status\": \"Approved\",\n \"comment\": \"Document manually verified by compliance.\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_feature_status(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_ocr_1\",\n new_status=\"Approved\",\n comment=\"Document manually verified by compliance.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateFeatureStatus(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_ocr_1\",\n {\n new_status: \"Approved\",\n comment: \"Document manually verified by compliance.\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateFeatureStatus(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_ocr_1\", didit.SessionsUpdateFeatureStatusParams{\n\tNewStatus: \"Approved\",\n\tComment: didit.String(\"Document manually verified by compliance.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateFeatureStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateFeatureStatus(\"11111111-2222-3333-4444-555555555555\", \"feature_ocr_1\", SessionsUpdateFeatureStatusParams.builder()\n .newStatus(SessionsUpdateFeatureStatusParams.NewStatus.of(\"Approved\"))\n .comment(\"Document manually verified by compliance.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateFeatureStatus('11111111-2222-3333-4444-555555555555', 'feature_ocr_1', [\n 'new_status' => 'Approved',\n 'comment' => 'Document manually verified by compliance.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_feature_status(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_ocr_1\",\n new_status: \"Approved\",\n comment: \"Document manually verified by compliance.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateFeatureStatusAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_ocr_1\", new SessionsUpdateFeatureStatusParams\n{\n NewStatus = \"Approved\",\n Comment = \"Document manually verified by compliance.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/update-aml-hit-status/": { "patch": { "summary": "Aggiorna lo stato di revisione di un riscontro AML", "description": "Imposta lo stato di revisione di un **singolo hit AML** (una potenziale corrispondenza con sanzioni / PEP / watchlist / notizie negative) restituito dallo Screening AML, senza modificare la decisione complessiva della sessione. Identifica l'hit tramite il relativo `hit_id` (l'`id` di una voce nell'array `hits` del controllo AML — vedi la decisione della sessione). Un ID hit restituito nel formato precedente viene comunque accettato; la risposta identifica sempre l'hit tramite il suo `id` attuale.\n\n`review_status` è uno tra `Unreviewed`, `Confirmed Match`, `False Positive` o `Inconclusive`. Le decisioni del revisore vengono mantenute durante gli aggiornamenti del monitoraggio continuo, quindi un hit contrassegnato come `False Positive` rimane tale quando il provider esegue un nuovo screening.\n\nUna chiamata riuscita attiva un webhook `data.updated` e aggiunge una voce di attività (con attribuzione dell'autore) al registro di revisione della sessione. Per i workflow a grafo con controlli AML multipli, passa `node_id` per indirizzare un controllo specifico.\n\nAutenticati con la tua chiave API (`x-api-key`) o con un'intestazione di autorizzazione utente — entrambi devono disporre del privilegio `write:sessions`.", "operationId": "patch_v3_session_update_aml_hit_status", "x-didit-sdk": { "resource": "sessions", "method": "update_aml_hit_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB): il servizio risolve l'ID per entrambi i tipi di sessione.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "in": "query", "name": "node_id", "required": false, "description": "ID del nodo del grafo del workflow. Richiesto solo quando la sessione contiene più controlli AML (uno per nodo); omettere per le sessioni con un singolo controllo AML.", "schema": { "type": "string", "example": "feature_aml_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hit_id", "review_status" ], "properties": { "hit_id": { "type": "string", "description": "L'`id` dell'hit nell'array `hits` del controllo AML (`hit_...`). Un id hit restituito nel formato precedente viene ancora accettato.", "example": "hit_7c1e9a40b2d35f86e0a4c912" }, "review_status": { "type": "string", "description": "Il nuovo stato di revisione per il match.", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ], "example": "False Positive" }, "node_id": { "type": "string", "description": "ID opzionale del nodo del grafo. Usalo (qui o come parametro di query) quando la sessione include più controlli AML.", "example": "feature_aml_1" } } }, "example": { "hit_id": "hit_7c1e9a40b2d35f86e0a4c912", "review_status": "False Positive" } } } }, "responses": { "200": { "description": "Stato di revisione del riscontro aggiornato.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "hit_id", "review_status" ], "properties": { "message": { "type": "string", "description": "Sempre `Hit status updated successfully`." }, "hit_id": { "type": "string", "description": "L'`id` dell'hit aggiornato, così come restituito dalla decisione della sessione, anche se la richiesta ha indicato l'hit tramite un id nel formato precedente." }, "review_status": { "type": "string", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ], "description": "Lo stato di revisione ora memorizzato per la corrispondenza (hit)." } } }, "example": { "message": "Hit status updated successfully", "hit_id": "hit_7c1e9a40b2d35f86e0a4c912", "review_status": "False Positive" } } } }, "400": { "description": "Errore di validazione — `hit_id` vuoto o `review_status` non compreso tra i valori consentiti.", "content": { "application/json": { "example": { "review_status": [ "\"Maybe\" is not a valid choice." ] } } } }, "403": { "description": "Credenziali mancanti o autorizzazioni insufficienti. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "La chiave API non dispone dell'autorizzazione write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "La sessione non è stata trovata, la sessione non include alcun controllo AML (opzionalmente per il `node_id` specificato) oppure nessun riscontro corrisponde a `hit_id`.", "content": { "application/json": { "examples": { "No AML Check": { "summary": "La sessione non ha alcun controllo AML", "value": { "detail": "The session does not have an AML check." } }, "Hit Not Found": { "summary": "hit_id sconosciuto", "value": { "detail": "Hit with ID 'hit_9d2e7f41c0a8b3e65d1f0c47' not found in the AML check." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-aml-hit-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"hit_id\": \"abc123\",\n \"review_status\": \"False Positive\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_id=\"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status=\"False Positive\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", {\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"False Positive\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateAMLHitStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateAMLHitStatusParams{\n\tHitID: \"hit_7c1e9a40b2d35f86e0a4c912\",\n\tReviewStatus: \"False Positive\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateAmlHitStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateAmlHitStatusParams.builder()\n .hitId(\"hit_7c1e9a40b2d35f86e0a4c912\")\n .reviewStatus(SessionsUpdateAmlHitStatusParams.ReviewStatus.of(\"False Positive\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateAmlHitStatus('11111111-2222-3333-4444-555555555555', [\n 'hit_id' => 'hit_7c1e9a40b2d35f86e0a4c912',\n 'review_status' => 'False Positive',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"False Positive\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateAmlHitStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateAmlHitStatusParams\n{\n HitId = \"hit_7c1e9a40b2d35f86e0a4c912\",\n ReviewStatus = \"False Positive\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/bulk-update-aml-hit-status/": { "patch": { "summary": "Aggiornamento massivo degli stati di revisione dei riscontri AML", "description": "Aggiorna lo stato di revisione di **più hit AML** in un'unica chiamata. Fornisci `hit_updates`, un elenco di coppie `{ hit_id, review_status }`. `review_status` è uno tra `Unreviewed`, `Confirmed Match`, `False Positive` o `Inconclusive`.\n\nL'aggiornamento è del tipo tutto o niente: se un qualsiasi `hit_id` non viene trovato nel controllo AML, la richiesta restituisce `404` e nessun hit viene modificato. Una chiamata riuscita attiva un singolo webhook `data.updated` e registra una voce di attività che copre tutte le modifiche. Per i workflow a grafo con controlli AML multipli, passa `node_id` per selezionare un controllo specifico.\n\nAutenticati con la tua chiave API (`x-api-key`) o con un'intestazione di autorizzazione utente: entrambi devono disporre del privilegio `write:sessions`.", "operationId": "patch_v3_session_bulk_update_aml_hit_status", "x-didit-sdk": { "resource": "sessions", "method": "bulk_update_aml_hit_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB): il servizio risolve l'ID per entrambi i tipi di sessione.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "in": "query", "name": "node_id", "required": false, "description": "ID del nodo del grafo del workflow. Richiesto solo quando la sessione contiene più controlli AML (uno per nodo); omettere per le sessioni con un singolo controllo AML.", "schema": { "type": "string", "example": "feature_aml_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hit_updates" ], "properties": { "hit_updates": { "type": "array", "description": "Elenco non vuoto di aggiornamenti dei riscontri.", "items": { "type": "object", "required": [ "hit_id", "review_status" ], "properties": { "hit_id": { "type": "string", "example": "hit_7c1e9a40b2d35f86e0a4c912", "description": "L'`id` dell'hit nell'array `hits` del controllo AML (`hit_...`). Un id hit restituito nel formato precedente viene ancora accettato." }, "review_status": { "type": "string", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ], "example": "Confirmed Match" } } } }, "node_id": { "type": "string", "description": "ID opzionale del nodo del grafo. Usalo (qui o come parametro di query) quando la sessione include più controlli AML.", "example": "feature_aml_1" } } }, "example": { "hit_updates": [ { "hit_id": "hit_7c1e9a40b2d35f86e0a4c912", "review_status": "Confirmed Match" }, { "hit_id": "hit_3b8f20d6a91c4e75f0b2d6a8", "review_status": "False Positive" } ] } } } }, "responses": { "200": { "description": "Tutti gli hit sono stati aggiornati.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "updated_hits" ], "properties": { "message": { "type": "string", "description": "`Updated {n} hit(s) successfully`, dove `n` è il numero di voci in `hit_updates`." }, "updated_hits": { "type": "array", "items": { "type": "string" }, "description": "L'`id` dell'hit indicato da ciascuna voce in `hit_updates`, così come restituito dalla decisione della sessione, nell'ordine della richiesta, compresi gli hit il cui stato non è cambiato." } } }, "example": { "message": "Updated 2 hit(s) successfully", "updated_hits": [ "hit_7c1e9a40b2d35f86e0a4c912", "hit_3b8f20d6a91c4e75f0b2d6a8" ] } } } }, "400": { "description": "Errore di validazione — `hit_updates` vuoto, oppure una voce è priva di `hit_id` / `review_status` o contiene un valore non valido.", "content": { "application/json": { "example": { "hit_updates": [ "hit_updates cannot be empty" ] } } } }, "403": { "description": "Credenziali mancanti o autorizzazioni insufficienti. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "La chiave API non dispone dell'autorizzazione write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "La sessione non è stata trovata, la sessione non presenta controlli AML oppure uno o più `hit_id` non esistono (in tal caso nessun riscontro viene modificato).", "content": { "application/json": { "example": { "detail": "Hits not found: hit_9d2e7f41c0a8b3e65d1f0c47" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/bulk-update-aml-hit-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"hit_updates\": [\n { \"hit_id\": \"abc123\", \"review_status\": \"Confirmed Match\" },\n { \"hit_id\": \"def456\", \"review_status\": \"False Positive\" }\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.bulk_update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_updates=[{\n \"hit_id\": \"hit_7c1e9a40b2d35f86e0a4c912\",\n \"review_status\": \"Confirmed Match\",\n }, {\n \"hit_id\": \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n \"review_status\": \"False Positive\",\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.bulkUpdateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", {\n hit_updates: [{\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"Confirmed Match\",\n }, {\n hit_id: \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n review_status: \"False Positive\",\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.BulkUpdateAMLHitStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsBulkUpdateAMLHitStatusParams{\n\tHitUpdates: []didit.SessionsBulkUpdateAMLHitStatusParamsHitUpdates{{\n\t\tHitID: \"hit_7c1e9a40b2d35f86e0a4c912\",\n\t\tReviewStatus: \"Confirmed Match\",\n\t}, {\n\t\tHitID: \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n\t\tReviewStatus: \"False Positive\",\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsBulkUpdateAmlHitStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().bulkUpdateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", SessionsBulkUpdateAmlHitStatusParams.builder()\n .hitUpdates(List.of(\n SessionsBulkUpdateAmlHitStatusParams.HitUpdates.builder()\n .hitId(\"hit_7c1e9a40b2d35f86e0a4c912\")\n .reviewStatus(SessionsBulkUpdateAmlHitStatusParams.HitUpdates.ReviewStatus.of(\"Confirmed Match\"))\n .build(),\n SessionsBulkUpdateAmlHitStatusParams.HitUpdates.builder()\n .hitId(\"hit_3b8f20d6a91c4e75f0b2d6a8\")\n .reviewStatus(SessionsBulkUpdateAmlHitStatusParams.HitUpdates.ReviewStatus.of(\"False Positive\"))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->bulkUpdateAmlHitStatus('11111111-2222-3333-4444-555555555555', [\n 'hit_updates' => [[\n 'hit_id' => 'hit_7c1e9a40b2d35f86e0a4c912',\n 'review_status' => 'Confirmed Match',\n ], [\n 'hit_id' => 'hit_3b8f20d6a91c4e75f0b2d6a8',\n 'review_status' => 'False Positive',\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.bulk_update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_updates: [{\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"Confirmed Match\",\n }, {\n hit_id: \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n review_status: \"False Positive\",\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.BulkUpdateAmlHitStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsBulkUpdateAmlHitStatusParams\n{\n HitUpdates = new SessionsBulkUpdateAmlHitStatusParamsHitUpdates[]\n {\n new()\n {\n HitId = \"hit_7c1e9a40b2d35f86e0a4c912\",\n ReviewStatus = \"Confirmed Match\",\n },\n new()\n {\n HitId = \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n ReviewStatus = \"False Positive\",\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/update-poa-data/": { "patch": { "summary": "Aggiorna i dati della Prova di residenza estratti dal documento POA in una sessione di verifica", "description": "Correggi i campi estratti dal documento di Prova di residenza dell'utente (bolletta delle utenze, estratto conto bancario o altra prova dell'indirizzo) al termine della verifica: emittente, date, nome stampato, l'indirizzo stesso e dati bancari. Ogni campo nel corpo è facoltativo: vengono scritte solo le chiavi inviate, tutto il resto rimane invariato (semantica `PATCH`).\n\nLa sessione deve appartenere alla tua applicazione ed essere nello stato `Approved`, `Declined`, `In Review` o `Kyc Expired`. Le sessioni in qualsiasi altro stato (ad esempio ancora `In Progress`) restituiscono `404` con `\"No Session matches the given query.\"` (diverso da `\"Not found.\"` restituito per un `sessionId` sconosciuto o eliminato). La sessione deve inoltre contenere un record POA: le sessioni il cui workflow non ha mai eseguito un passaggio di Prova di residenza restituiscono `404` (`\"The session does not have a POA.\"`). Per i workflow a grafo con più passaggi POA, indica un passaggio specifico con `node_id` (parametro query o campo del body); se omesso, viene aggiornato il record POA più recente.\n\n`extra_fields` viene unito chiave per chiave: nove chiavi note (`bank_iban`, `additional_names`, …) scrivono direttamente nelle colonne POA dedicate, qualsiasi altra chiave viene conservata come elemento personalizzato aggiuntivo e `null` / `\"\"` elimina una chiave. `poa_parsed_address` accetta solo le sette chiavi documentate e ricalcola `formatted_address` / `poa_formatted_address` dopo ogni modifica. Se l'indirizzo in testo libero `poa_address` cambia, il server potrebbe anche ripetere la geocodifica e aggiornare l'indirizzo strutturato (operazione saltata per le sessioni sandbox).\n\nA differenza della variante KYC di questo endpoint, il [webhook](/it/integration/webhooks) `data.updated` (trigger `manual_review`) si attiva solo quando almeno un valore memorizzato **è effettivamente cambiato**: il reinvio di valori identici non produce alcun effetto. Quando i valori cambiano, una voce di attività `POA_DATA_UPDATED` che registra i campi modificati con i valori precedenti e nuovi viene aggiunta a `reviews` della sessione, visibile in [Get Decision](#get-/v3/session/-sessionId-/decision/) e nella cronologia delle attività della console. Lo stato e la decisione della sessione **non** vengono rivalutati: utilizza [Update Status](#patch-/v3/session/-sessionId-/update-status/) per modificare l'esito.\n\nAccetta una chiave API o un token utente della console; in entrambi i casi la credenziale necessita dell'autorizzazione `write:sessions`. Gli errori di autenticazione e di autorizzazione restituiscono entrambi `403`: questa API non risponde mai `401`. Tieni presente che la ricerca della sessione viene eseguita prima dei controlli delle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche in assenza di credenziali. Questo endpoint ha un limite di frequenza dedicato di 10 richieste al minuto per chiave API (vengono conteggiate anche le richieste non valide); si applica inoltre il budget di scrittura condiviso di 300 richieste al minuto.\n\nUn corpo JSON vuoto `{}` non produce alcun effetto: restituisce `200` riportando il record POA corrente senza attivare il webhook (`has_changes` rimane false).", "operationId": "patch_v3_session_update_poa_data", "x-didit-sdk": { "resource": "sessions", "method": "update_poa_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica degli utenti (KYC) di cui stai correggendo il record POA allegato.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nodo del grafo del workflow di cui aggiornare parzialmente il record POA, per workflow a grafo con più passaggi di Prova di residenza (accettato anche come campo `node_id` nel corpo). Se omesso, viene aggiornato il record POA più recente della sessione. Se non esiste alcuna POA per il nodo specificato, la chiamata restituisce `404` (`\"The session does not have a POA for node ''.\"`).", "schema": { "type": "string", "example": "feature_poa" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Tutti i campi sono facoltativi — invia solo ciò che desideri modificare.", "properties": { "issuing_state": { "type": "string", "nullable": true, "description": "Paese che ha rilasciato il documento di prova di residenza, ISO 3166-1 alpha-3. Non fa distinzione tra maiuscole e minuscole (normalizzato in maiuscolo); i codici non validi restituiscono `400`.", "example": "ESP" }, "document_type": { "type": "string", "enum": [ "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" ], "description": "Categoria del documento POA. I valori sono in maiuscolo; le varianti in minuscolo come `utility_bill` restituiscono `400`.", "example": "UTILITY_BILL" }, "document_language": { "type": "string", "maxLength": 50, "nullable": true, "description": "Lingua del documento, in genere un codice ISO 639-1 (es. `es`). Testo libero — non validato come codice lingua.", "example": "es" }, "issuer": { "type": "string", "maxLength": 255, "nullable": true, "description": "Organizzazione che ha emesso il documento (fornitore di utenze, banca, agenzia governativa).", "example": "Energy Provider S.A." }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "Data di emissione del documento POA in formato `YYYY-MM-DD`. Qualsiasi altro formato restituisce `400`.", "example": "2026-04-12" }, "poa_address": { "type": "string", "nullable": true, "description": "Indirizzo a testo libero così come stampato sul documento. Quando questo valore cambia (solo per sessioni non sandbox) e l'indirizzo strutturato è ancora mancante o incompleto, il server esegue nuovamente la geocodifica in background della stessa richiesta e potrebbe sovrascrivere `poa_parsed_address` / `poa_formatted_address` con il risultato del geocodificatore. La nuova geocodifica richiede inoltre la presenza di `issuing_state` nel record POA.", "example": "Avda de Madrid 34, 28013 Madrid" }, "name_on_document": { "type": "string", "maxLength": 255, "nullable": true, "description": "Nome del destinatario esattamente come stampato sul documento.", "example": "Carmen Espanola" }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Dati aggiuntivi specifici del documento, uniti chiave per chiave. Nove chiavi corrispondono a colonne dedicate della prova di residenza: `bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`, `document_phone_number` e `additional_names` (deve essere un elenco di stringhe o `null`, altrimenti `400`). Qualsiasi altra chiave viene memorizzata come campo aggiuntivo personalizzato. Semantica per chiave: un valore imposta la chiave; `null` o `\"\"` la elimina. Deve essere un oggetto JSON, altrimenti `400`." }, "poa_parsed_address": { "type": "object", "nullable": true, "description": "Indirizzo strutturato. Vengono accettate solo queste chiavi nidificate: `address_type`, `city`, `region`, `street_1`, `street_2`, `postal_code`, `country` — qualsiasi altra chiave restituisce `400`. Semantica per chiave: un valore imposta la chiave, `null` la rimuove. `formatted_address` (e il campo di primo livello `poa_formatted_address`) viene ricalcolato lato server unendo `street_1`, `street_2`, `city`, `region`, `postal_code` e `country` — non puoi impostarlo direttamente.", "properties": { "address_type": { "type": "string", "nullable": true, "description": "Classificazione dell'indirizzo a testo libero (es. `home`)." }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "Stato / provincia / comunità autonoma." }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "Codice paese ISO 3166-1 alpha-2. L'input in lettere minuscole viene normalizzato in maiuscolo; i codici alpha-3 vengono rifiutati con `400`.", "example": "ES" } } } } }, "examples": { "Correct issuer and address": { "summary": "Correggi la classificazione del documento, l'emittente e l'indirizzo strutturato", "value": { "issuing_state": "ESP", "document_type": "BANK_STATEMENT", "issuer": "Banco Example S.A.", "issue_date": "2026-05-02", "name_on_document": "Carmen Espanola", "poa_address": "Avda de Madrid 34, 28013 Madrid", "extra_fields": { "bank_iban": "ES9121000418450200051332", "additional_names": [ "Carmen E. Espanola" ] }, "poa_parsed_address": { "street_1": "Avda de Madrid 34", "city": "Madrid", "postal_code": "28013", "country": "ES" } } }, "Remove a banking detail": { "summary": "Elimina una chiave di un campo extra, mantieni il resto", "value": { "extra_fields": { "bank_iban": null } } } } } } }, "responses": { "200": { "description": "Dati POA aggiornati. Restituisce il **record POA attuale completo** (ogni campo aggiornabile con il relativo valore memorizzato, oltre alla mappa `extra_fields` completa, `poa_parsed_address` e `poa_formatted_address`) — non solo i campi inviati. Il webhook `data.updated` viene attivato solo quando almeno un valore è effettivamente cambiato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuing_state": { "type": "string", "nullable": true, "description": "Paese che ha rilasciato il documento di prova di residenza, ISO 3166-1 alpha-3. Non fa distinzione tra maiuscole e minuscole (normalizzato in maiuscolo); i codici non validi restituiscono `400`.", "example": "ESP" }, "document_type": { "type": "string", "enum": [ "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" ], "description": "Categoria del documento POA. I valori sono in maiuscolo; le varianti in minuscolo come `utility_bill` restituiscono `400`.", "example": "UTILITY_BILL" }, "document_language": { "type": "string", "maxLength": 50, "nullable": true, "description": "Lingua del documento, in genere un codice ISO 639-1 (es. `es`). Testo libero — non validato come codice lingua.", "example": "es" }, "issuer": { "type": "string", "maxLength": 255, "nullable": true, "description": "Organizzazione che ha emesso il documento (fornitore di utenze, banca, agenzia governativa).", "example": "Energy Provider S.A." }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "Data di emissione del documento POA in formato `YYYY-MM-DD`. Qualsiasi altro formato restituisce `400`.", "example": "2026-04-12" }, "poa_address": { "type": "string", "nullable": true, "description": "Indirizzo a testo libero così come stampato sul documento. Quando questo valore cambia (solo per sessioni non sandbox) e l'indirizzo strutturato è ancora mancante o incompleto, il server esegue nuovamente la geocodifica in background della stessa richiesta e potrebbe sovrascrivere `poa_parsed_address` / `poa_formatted_address` con il risultato del geocodificatore.", "example": "Avda de Madrid 34, 28013 Madrid" }, "name_on_document": { "type": "string", "maxLength": 255, "nullable": true, "description": "Nome del destinatario esattamente come stampato sul documento.", "example": "Carmen Espanola" }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Sempre presenti nella risposta: le nove chiavi note (con `null` per quelle non impostate, `additional_names` con valore predefinito `[]`) più eventuali chiavi personalizzate precedentemente memorizzate." }, "poa_parsed_address": { "type": "object", "nullable": true, "description": "Indirizzo strutturato attuale, oppure `null` quando non ne esiste alcuno. Include il `formatted_address` ricalcolato insieme alle sette chiavi modificabili. Restituito così come archiviato: dopo una geocodifica lato server può contenere chiavi di gestione interna (ad es. `raw_results`) insieme alle chiavi modificabili.", "properties": { "address_type": { "type": "string", "nullable": true, "description": "Classificazione dell'indirizzo a testo libero (es. `home`)." }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "Stato / provincia / comunità autonoma." }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "Codice paese ISO 3166-1 alpha-2. L'input in lettere minuscole viene normalizzato in maiuscolo; i codici alpha-3 vengono rifiutati con `400`.", "example": "ES" }, "formatted_address": { "type": "string", "nullable": true, "description": "Forma unificata e leggibile dell'indirizzo strutturato. Ricalcolata lato server dopo ogni modifica a `poa_parsed_address`.", "example": "Avda de Madrid 34, Madrid, 28013, ES" } } }, "poa_formatted_address": { "type": "string", "nullable": true, "description": "Copia di primo livello del campo `formatted_address` ricalcolato, mantenuta sincronizzata quando l'indirizzo strutturato cambia.", "example": "Avda de Madrid 34, Madrid, 28013, ES" } } }, "examples": { "Updated POA": { "summary": "Record POA completo dopo la correzione", "value": { "issuing_state": "ESP", "document_type": "BANK_STATEMENT", "document_language": "es", "issuer": "Banco Example S.A.", "issue_date": "2026-05-02", "poa_address": "Avda de Madrid 34, 28013 Madrid", "name_on_document": "Carmen Espanola", "extra_fields": { "bank_account_number": null, "bank_iban": "ES9121000418450200051332", "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "Carmen E. Espanola" ] }, "poa_parsed_address": { "city": "Madrid", "street_1": "Avda de Madrid 34", "postal_code": "28013", "country": "ES", "formatted_address": "Avda de Madrid 34, Madrid, 28013, ES" }, "poa_formatted_address": "Avda de Madrid 34, Madrid, 28013, ES" } } } } } }, "400": { "description": "Errore di validazione. Gli errori di campo arrivano come `{\"\": [\"\"]}`; gli errori sulle chiavi nidificate di `poa_parsed_address` / `extra_fields` utilizzano un valore oggetto: `{\"extra_fields\": {\"\": \"\"}}`.", "content": { "application/json": { "examples": { "Invalid document type": { "summary": "L'enum è in maiuscolo: le varianti in minuscolo vengono rifiutate", "value": { "document_type": [ "\"utility_bill\" is not a valid choice." ] } }, "Invalid issuing state": { "summary": "issuing_state non è in formato ISO 3166-1 alpha-3", "value": { "issuing_state": [ "Invalid ISO 3166-1 alpha-3 country code for issuing_state." ] } }, "additional_names not a list": { "summary": "additional_names accetta una lista di stringhe o null", "value": { "extra_fields": { "additional_names": "Must be a list or null." } } }, "Unsupported poa_parsed_address key": { "summary": "Sono consentite solo le sette chiavi documentate", "value": { "poa_parsed_address": { "zipcode": "Unsupported key. Allowed keys: address_type, city, region, street_1, street_2, postal_code, country" } } }, "Bad date format": { "summary": "Le date devono essere YYYY-MM-DD", "value": { "issue_date": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } } } } } }, "403": { "description": "Credenziali mancanti o autorizzazioni insufficienti. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "La credenziale non dispone di write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Sessione sconosciuta, sessione in uno stato non modificabile o nessun record POA da aggiornare. Ciascun caso ha un messaggio `detail` distinto (vedi esempi). La ricerca della sessione sconosciuta viene eseguita prima dei controlli delle credenziali.", "content": { "application/json": { "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID nella tua applicazione (oppure è stata eliminata)", "value": { "detail": "Not found." } }, "Wrong session state": { "summary": "La sessione esiste ma non è Approved / Declined / In Review / Kyc Expired", "value": { "detail": "No Session matches the given query." } }, "No POA record": { "summary": "Il workflow non ha mai eseguito un passaggio di Prova di residenza", "value": { "detail": "The session does not have a POA." } }, "No POA for node": { "summary": "node_id specificato ma non esiste alcuna POA associata", "value": { "detail": "The session does not have a POA for node 'feature_missing'." } } } } } }, "429": { "description": "Limite di frequenza dedicato superato — 10 aggiornamenti dei dati POA al minuto per chiave API (le richieste rifiutate vengono conteggiate nel budget). Anche il budget di scrittura condiviso di 300/min può attivarsi con il proprio messaggio. Controlla `Retry-After` e le intestazioni di risposta `X-RateLimit-*` prima di effettuare un nuovo tentativo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Budget di aggiornamento POA esaurito", "value": { "detail": "Session POA data update rate limit exceeded. You can make up to 10 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-poa-data/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"issuing_state\": \"ESP\",\n \"document_type\": \"BANK_STATEMENT\",\n \"issuer\": \"Banco Example S.A.\",\n \"issue_date\": \"2026-05-02\",\n \"name_on_document\": \"Carmen Espanola\",\n \"poa_address\": \"Avda de Madrid 34, 28013 Madrid\",\n \"extra_fields\": {\n \"bank_iban\": \"ES9121000418450200051332\"\n },\n \"poa_parsed_address\": {\n \"city\": \"Madrid\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\"\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_poa_data(\n \"11111111-2222-3333-4444-555555555555\",\n issuing_state=\"ESP\",\n document_type=\"BANK_STATEMENT\",\n issuer=\"Banco Example S.A.\",\n issue_date=\"2026-05-02\",\n poa_address=\"Avda de Madrid 34, 28013 Madrid\",\n name_on_document=\"Carmen Espanola\",\n extra_fields={\"bank_iban\": \"ES9121000418450200051332\", \"additional_names\": [\"Carmen E. Espanola\"]},\n poa_parsed_address={\n \"city\": \"Madrid\",\n \"street_1\": \"Avda de Madrid 34\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updatePoaData(\"11111111-2222-3333-4444-555555555555\", {\n issuing_state: \"ESP\",\n document_type: \"BANK_STATEMENT\",\n issuer: \"Banco Example S.A.\",\n issue_date: \"2026-05-02\",\n poa_address: \"Avda de Madrid 34, 28013 Madrid\",\n name_on_document: \"Carmen Espanola\",\n extra_fields: { bank_iban: \"ES9121000418450200051332\", additional_names: [\"Carmen E. Espanola\"] },\n poa_parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdatePOAData(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdatePOADataParams{\n\tIssuingState: didit.String(\"ESP\"),\n\tDocumentType: didit.Some(didit.SessionsUpdatePOADataParamsDocumentType(\"BANK_STATEMENT\")),\n\tIssuer: didit.String(\"Banco Example S.A.\"),\n\tIssueDate: didit.String(\"2026-05-02\"),\n\tPOAAddress: didit.String(\"Avda de Madrid 34, 28013 Madrid\"),\n\tNameOnDocument: didit.String(\"Carmen Espanola\"),\n\tExtraFields: didit.Some(map[string]any{\"bank_iban\": \"ES9121000418450200051332\", \"additional_names\": []any{\"Carmen E. Espanola\"}}),\n\tPOAParsedAddress: didit.Some(didit.SessionsUpdatePOADataParamsPOAParsedAddress{\n\t\tCity: didit.String(\"Madrid\"),\n\t\tStreet1: didit.String(\"Avda de Madrid 34\"),\n\t\tPostalCode: didit.String(\"28013\"),\n\t\tCountry: didit.String(\"ES\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdatePoaDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updatePoaData(\"11111111-2222-3333-4444-555555555555\", SessionsUpdatePoaDataParams.builder()\n .issuingState(\"ESP\")\n .documentType(SessionsUpdatePoaDataParams.DocumentType.of(\"BANK_STATEMENT\"))\n .issuer(\"Banco Example S.A.\")\n .issueDate(LocalDate.parse(\"2026-05-02\"))\n .poaAddress(\"Avda de Madrid 34, 28013 Madrid\")\n .nameOnDocument(\"Carmen Espanola\")\n .extraFields(Map.of(\"bank_iban\", \"ES9121000418450200051332\", \"additional_names\", List.of(\"Carmen E. Espanola\")))\n .poaParsedAddress(SessionsUpdatePoaDataParams.PoaParsedAddress.builder()\n .city(\"Madrid\")\n .street1(\"Avda de Madrid 34\")\n .postalCode(\"28013\")\n .country(\"ES\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updatePoaData('11111111-2222-3333-4444-555555555555', [\n 'issuing_state' => 'ESP',\n 'document_type' => 'BANK_STATEMENT',\n 'issuer' => 'Banco Example S.A.',\n 'issue_date' => '2026-05-02',\n 'poa_address' => 'Avda de Madrid 34, 28013 Madrid',\n 'name_on_document' => 'Carmen Espanola',\n 'extra_fields' => ['bank_iban' => 'ES9121000418450200051332', 'additional_names' => ['Carmen E. Espanola']],\n 'poa_parsed_address' => [\n 'city' => 'Madrid',\n 'street_1' => 'Avda de Madrid 34',\n 'postal_code' => '28013',\n 'country' => 'ES',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_poa_data(\n \"11111111-2222-3333-4444-555555555555\",\n issuing_state: \"ESP\",\n document_type: \"BANK_STATEMENT\",\n issuer: \"Banco Example S.A.\",\n issue_date: \"2026-05-02\",\n poa_address: \"Avda de Madrid 34, 28013 Madrid\",\n name_on_document: \"Carmen Espanola\",\n extra_fields: { bank_iban: \"ES9121000418450200051332\", additional_names: [\"Carmen E. Espanola\"] },\n poa_parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdatePoaDataAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdatePoaDataParams\n{\n IssuingState = \"ESP\",\n DocumentType = new SessionsUpdatePoaDataParamsDocumentType(\"BANK_STATEMENT\"),\n Issuer = \"Banco Example S.A.\",\n IssueDate = \"2026-05-02\",\n PoaAddress = \"Avda de Madrid 34, 28013 Madrid\",\n NameOnDocument = \"Carmen Espanola\",\n ExtraFields = new Dictionary { [\"bank_iban\"] = \"ES9121000418450200051332\", [\"additional_names\"] = new object[] { \"Carmen E. Espanola\" } },\n PoaParsedAddress = new SessionsUpdatePoaDataParamsPoaParsedAddress\n {\n City = \"Madrid\",\n Street1 = \"Avda de Madrid 34\",\n PostalCode = \"28013\",\n Country = \"ES\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/{companyUuid}/update-data/": { "patch": { "summary": "Aggiorna i dati aziendali estratti dal registro delle imprese in una sessione di Verifica aziendale (KYB)", "description": "Correggi i dati aziendali estratti dal registro per una sessione di Verifica aziendale (KYB) — ragione sociale, numero di registrazione, indirizzi, stato, recapiti — identificata da `companyUuid`. I chiamanti tipici sono un analista di conformità che corregge un errore di lettura del registro o il tuo back office che sincronizza i dati aziendali corretti. Ogni campo nel corpo è facoltativo (semantica `PATCH`); un corpo JSON vuoto (`{}`) è un'operazione no-op che restituisce semplicemente il record aziendale corrente.\n\nLe modifiche vengono scritte in due punti contemporaneamente: i campi con una colonna aziendale canonica (name, registration number, country, incorporation date, tax number, type, statuses, campi relativi al capitale (`registered_capital`, `registered_capital_amount`, `registered_capital_currency`), alternative names, nature of business, website, email, phone, LEI, location e `legal_address` → `registered_address`) aggiornano tale colonna, e **ogni** chiave inviata viene inoltre unita nello snapshot `registry_data` (date come stringhe ISO) affinché la vista \"estratto dal registro\" rifletta la correzione. I campi senza una colonna — `region`, `registration_date`, `dissolution_date`, `control_scheme` — confluiscono esclusivamente in `registry_data`. I dati `user_provided_data` (ciò che l'utente finale ha confermato nel flusso ospitato) non vengono mai toccati, e `last_console_edit_at` viene registrato a ogni PATCH non vuota.\n\nA differenza degli endpoint di aggiornamento KYC/POA, **non vi è alcun vincolo di stato della sessione**: l'azienda può essere modificata in qualsiasi momento del ciclo di vita della sessione aziendale. L'azienda deve appartenere alla sessione indicata nel percorso (in caso contrario `404` con `\"KYB company does not belong to the given session.\"` ) e alla tua applicazione. Ogni PATCH non vuota attiva il [webhook](/it/integration/webhooks) `data.updated` sulla sessione aziendale (trigger `console_registry_edit`), anche se i valori inviati sono identici a quelli memorizzati. Lo stato e la decisione della sessione **non** vengono rivalutati, e non viene registrata alcuna voce di revisione/audit.\n\nAccetta una chiave API o un token utente della console; in entrambi i casi la credenziale deve disporre dell'autorizzazione `write:businesses`. Sia gli errori di autenticazione che quelli di autorizzazione restituiscono `403`: questa API non risponde mai con `401`. Tieni presente che la ricerca della sessione viene eseguita prima dei controlli sulle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche in assenza di credenziali. Si applica il budget di scrittura condiviso di 300 richieste al minuto per chiave API.\n\nPer le sessioni di Verifica degli utenti, la controparte KYC è `PATCH /v3/session/{sessionId}/update-data/`; per modificare la decisione della sessione stessa, usa `PATCH /v3/session/{sessionId}/update-status/`.", "operationId": "patch_v3_session_kyb_company_update_data", "x-didit-sdk": { "resource": "sessions", "method": "update_kyb_company_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione padre di Verifica aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "companyUuid", "in": "path", "required": true, "description": "UUID del record aziendale da aggiornare (`registry_checks[].company.uuid` nella decisione della sessione aziendale). Deve appartenere alla sessione a cui fa riferimento `sessionId`.", "schema": { "type": "string", "format": "uuid", "example": "88888888-9999-aaaa-bbbb-cccccccccccc" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Tutti i campi sono opzionali: invia solo ciò che desideri modificare. I campi forniti aggiornano le colonne canoniche dell'azienda (dove ne esiste una) e vengono uniti nello snapshot di `registry_data`.", "properties": { "company_name": { "type": "string", "maxLength": 255, "description": "Ragione sociale dell'azienda. Scritta nella colonna canonica e nello snapshot del registro.", "example": "Docs Probe Corp" }, "registration_number": { "type": "string", "maxLength": 100, "description": "Numero di registrazione ufficiale presso il registro delle imprese.", "example": "DPC-001" }, "country_code": { "type": "string", "maxLength": 2, "description": "Paese di costituzione, ISO 3166-1 alpha-2. Non fa distinzione tra maiuscole e minuscole (`us` viene memorizzato come `US`). I codici alpha-3 non superano il limite di 2 caratteri restituendo `400`.", "example": "US" }, "region": { "type": "string", "maxLength": 10, "nullable": true, "description": "Tag di suddivisione / regione laddove il registro ne preveda una (ad es. stato USA). Memorizzato solo nello snapshot del registro — non ha una colonna canonica." }, "incorporation_date": { "type": "string", "format": "date", "description": "Data di costituzione in `YYYY-MM-DD`. Opzionale come ogni altro campo: la richiesta `PATCH` è parziale. Qualsiasi altro formato di data restituisce `400`.", "example": "2015-04-12" }, "registration_date": { "type": "string", "format": "date", "nullable": true, "description": "Data di registrazione nei casi in cui il registro delle imprese la distingua da quella di costituzione. Memorizzata solo nello snapshot del registro delle imprese." }, "dissolution_date": { "type": "string", "format": "date", "nullable": true, "description": "Data di scioglimento per le aziende non più attive. Memorizzata solo nello snapshot del registro." }, "tax_number": { "type": "string", "maxLength": 100, "description": "Identificativo fiscale." }, "legal_address": { "type": "string", "description": "Sede legale / indirizzo registrato. Associato tramite alias lato server alla colonna canonica `registered_address` — la risposta lo restituisce sotto `registered_address`, mentre lo snapshot del registro mantiene la chiave `legal_address` inviata.", "example": "1 Example Plaza, Wilmington, DE 19801" }, "company_type": { "type": "string", "maxLength": 100, "description": "Tipo di entità giuridica (es. `Limited Liability Company`, `PLC`, `GmbH`).", "example": "Limited Liability Company" }, "registry_status": { "type": "string", "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off" ], "nullable": true, "description": "Stato aziendale riportato dal registro delle imprese. In minuscolo, alcuni valori contengono spazi (ad es. `struck off`, `no longer authorised`). Qualsiasi altro valore restituisce `400`.", "example": "active" }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "Esito della verifica del registro. Qualsiasi altro valore restituisce `400`.", "example": "verified" }, "alternative_names": { "type": "string", "description": "Nomi commerciali, denominazioni legali precedenti, denominazioni d'uso (testo libero)." }, "nature_of_business": { "type": "string", "description": "Breve descrizione dell'attività dell'azienda.", "example": "Software development" }, "registered_capital": { "type": "string", "maxLength": 100, "description": "Capitale registrato leggibile dall'utente (ad es. `USD 50000`). Usa `registered_capital_amount` + `registered_capital_currency` per valori strutturati, oppure questo campo per testo in formato libero.", "example": "USD 50000" }, "registered_capital_amount": { "type": "number", "format": "double", "nullable": true, "description": "Importo numerico del capitale sociale registrato (fino a 20 cifre, 2 decimali). Imposta la colonna `registered_capital_amount` e viene riportato in `registry_data` come stringa decimale; la risposta lo restituisce come stringa decimale (ad es. `\"1500000.50\"`)." }, "registered_capital_currency": { "type": "string", "maxLength": 3, "nullable": true, "description": "Codice valuta ISO 4217 per `registered_capital_amount`. Non fa distinzione tra maiuscole e minuscole (`usd` viene memorizzato come `USD`); i valori che non contengono esattamente 3 lettere restituiscono `400` con il messaggio ISO 4217. Imposta la colonna canonica `registered_capital_currency` e viene riflesso in `registry_data`.", "example": "USD" }, "website": { "type": "string", "maxLength": 500, "description": "Sito web dell'azienda. I domini semplici sono accettati e normalizzati con un prefisso `https://` (`docsprobe.example.com` viene salvato come `https://docsprobe.example.com`); i valori che continuano a non superare la validazione dell'URL restituiscono `400`.", "example": "https://docsprobe.example.com" }, "email": { "type": "string", "format": "email", "description": "Email di contatto registrata presso il registro.", "example": "legal@docsprobe.example.com" }, "phone": { "type": "string", "maxLength": 50, "description": "Telefono di contatto. Deve contenere solo `+`, cifre, spazi, trattini, punti o parentesi, con 7-15 cifre in totale; in caso contrario restituisce `400`.", "example": "+1 302 555 0143" }, "legal_entity_identifier": { "type": "string", "maxLength": 50, "description": "LEI, se l'azienda ne possiede uno." }, "location_of_registration": { "type": "string", "maxLength": 255, "description": "Città / suddivisione del registro ufficiale." }, "vat_number": { "type": "string", "maxLength": 64, "description": "Partita IVA UE. Unita solo nello snapshot di `registry_data`: la modifica qui non riesegue la validazione della partita IVA e dell'identificativo fiscale, pertanto `vat_validation_status` e gli altri campi di risultato `vat_*` rimangono invariati." }, "control_scheme": { "type": "string", "description": "Schema di controllo/governance quando il registro lo espone. Memorizzato solo nello snapshot del registro." } } }, "examples": { "Correct registry data": { "summary": "Correggi i campi dell'azienda estratti dal registro", "value": { "company_name": "Docs Probe Corp", "registration_number": "DPC-001", "country_code": "US", "incorporation_date": "2015-04-12", "company_type": "Limited Liability Company", "legal_address": "1 Example Plaza, Wilmington, DE 19801", "registry_status": "active", "verification_status": "verified", "website": "docsprobe.example.com", "email": "legal@docsprobe.example.com", "phone": "+1 302 555 0143", "registered_capital": "USD 50000", "nature_of_business": "Software development" } }, "Single field": { "summary": "Vengono scritte solo le chiavi inviate", "value": { "registry_status": "dissolved" } }, "No-op": { "summary": "Un corpo vuoto restituisce il record corrente senza attivare il webhook", "value": {} } } } } }, "responses": { "200": { "description": "Dati aziendali aggiornati (o restituiti invariati per un body vuoto). Restituisce il record aziendale KYB completo, con la stessa struttura di `registry_checks[].company` nella decisione della sessione aziendale. Da notare che `legal_address` viene restituito come `registered_address`. `registered_capital_amount`/`registered_capital_currency` popolano le rispettive colonne canoniche e vengono replicati in `registry_data`.", "content": { "application/json": { "schema": { "type": "object", "description": "Record aziendale KYB completo — con la stessa struttura dell'oggetto `company` all'interno di `registry_checks[]` nella decisione della sessione aziendale.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificatore del record aziendale (il parametro di percorso `companyUuid`)." }, "node_id": { "type": "string", "nullable": true, "description": "Nodo del grafo del workflow a cui appartiene questo record aziendale, quando il workflow è basato su grafo." }, "status": { "type": "string", "description": "Stato del ciclo di vita della funzionalità per il controllo del registro (ad es. `Not Finished`, `Approved`, `Declined`, `In Review`)." }, "registry_status": { "type": "string", "nullable": true, "description": "Stato aziendale riportato dal registro delle imprese (ad es. `active`, `dissolved`, `struck off`)." }, "data_resolved": { "type": "boolean", "description": "`true` quando i dati dell'azienda sono completi — sempre `true` per le aziende inserite manualmente; per le aziende ottenute dal registro delle imprese, `true` una volta completato il recupero dal registro." }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true, "description": "Paese di costituzione, codice ISO 3166-1 alpha-2." }, "region": { "type": "string", "nullable": true }, "company_type": { "type": "string", "nullable": true }, "incorporation_date": { "type": "string", "format": "date", "nullable": true }, "registered_address": { "type": "string", "nullable": true, "description": "Indirizzo registrato canonico — aggiornato quando invii `legal_address`." }, "tax_number": { "type": "string", "nullable": true }, "risk_level": { "type": "string", "nullable": true }, "verification_status": { "type": "string", "nullable": true, "description": "`verified`, `failed` o `unknown`." }, "is_from_registry": { "type": "boolean", "description": "`true` quando l'azienda è stata precompilata da una ricerca nel registro delle imprese anziché inserita manualmente." }, "fetch_status": { "type": "string", "nullable": true, "description": "Ciclo di vita del recupero dal registro delle imprese per le aziende provenienti dal registro (`pending` / `resolved`); `null` per le voci manuali." }, "alternative_names": { "type": "string", "nullable": true, "description": "Denominazioni aziendali alternative, commerciali, precedenti o nella lingua originale sotto forma di testo, se segnalate." }, "nature_of_business": { "type": "string", "nullable": true }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "Colonna canonica. Restituita come stringa decimale (ad es. `\"2750000.00\"`)." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Colonna canonica. Impostata dal flusso del registro delle imprese o da modifiche tramite console/API tramite questo endpoint." }, "website": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "legal_entity_identifier": { "type": "string", "nullable": true }, "location_of_registration": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true, "description": "Partita IVA UE, se raccolta durante il passaggio del registro ospitato o modificata successivamente." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Risultato della validazione della partita IVA o, qualora non presente, del `tax_number`, al momento dell'invio al registro. `valid` / `invalid`: stabilito dal registro ufficiale del paese (VIES UE, Norvegia, Svizzera, Brasile, Colombia, Costa Rica, Ecuador, Paraguay; per la Polonia anche dal registro IVA nazionale). `format_valid` / `invalid_format`: stabilito dalle regole di formato e cifra di controllo del paese laddove non sia possibile interrogare alcun registro. `could_not_validate`: il registro non era disponibile. `not_applicable`: nessun numero, paese privo di registro o regole, oppure sessione sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "Il numero verificato, così come noto alla fonte (ad esempio la partita IVA derivata da un SIREN francese o un RSIN olandese). `null` quando non è stato eseguito alcun controllo." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "La fonte che ha stabilito `vat_validation_status`: un registro ufficiale, oppure `format_rules`. `null` se non è stato eseguito alcun controllo." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registrato presso la fonte che ha validato il numero, quando ne fornisce uno. Impostato solo quando lo stato è `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Indirizzo registrato presso la fonte che ha convalidato il numero, quando ne comunica uno. Impostato solo quando lo stato è `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp del controllo. `null` se non è stato eseguito alcun controllo." }, "financial_summary": { "type": "object", "nullable": true, "additionalProperties": true }, "officers": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Amministratori / dirigenti collegati all'azienda, incluso l'avanzamento del KYC per singola persona." }, "beneficial_owners": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Titolari effettivi associati all'azienda, incluso l'avanzamento del KYC per ciascuna persona." }, "addresses": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "Dettaglio dell'indirizzo nel registro delle imprese, se restituito dal registro." }, "industries": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "Classificazione di settore del registro delle imprese, se disponibile." }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Date di deposito presso il registro delle imprese, se disponibili. Le dichiarazioni annuali e le assemblee generali utilizzano last_annual_return_date e last_agm_date; sono distinte dai bilanci di esercizio." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Cosa ha digitato l'utente finale durante il passaggio ospitato di conferma del registro. Non viene mai modificato da questo endpoint." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora di conferma dei dati aziendali da parte dell'utente finale nel flusso ospitato." }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Applicato a ogni richiesta PATCH riuscita e non vuota, in modo che le interfacce utente possano mostrare il contesto \"modificato dall'operatore\"." }, "is_editable": { "type": "boolean", "description": "`true` finché l'utente finale può ancora modificare i dati provenienti dal registro delle imprese nel flusso ospitato (provenienti dal registro e non ancora confermati)." } } }, "examples": { "Updated company": { "summary": "Record aziendale completo dopo la correzione", "value": { "uuid": "6b9479f5-6769-46c8-baf1-df63bbbc5f8c", "node_id": null, "status": "Not Finished", "registry_status": "active", "data_resolved": true, "company_name": "Docs Probe Corp", "registration_number": "DPC-001", "country_code": "US", "region": null, "company_type": "Limited Liability Company", "incorporation_date": "2015-04-12", "registered_address": "1 Example Plaza, Wilmington, DE 19801", "tax_number": null, "risk_level": null, "verification_status": "verified", "is_from_registry": false, "fetch_status": null, "alternative_names": null, "nature_of_business": "Software development", "registered_capital": "USD 50000", "registered_capital_amount": null, "registered_capital_currency": "USD", "website": "https://docsprobe.example.com", "email": "legal@docsprobe.example.com", "phone": "+1 302 555 0143", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": null, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": { "company_name": "Docs Probe Corp", "registration_number": "DPC-001", "country_code": "US", "incorporation_date": "2015-04-12", "legal_address": "1 Example Plaza, Wilmington, DE 19801", "company_type": "Limited Liability Company", "registry_status": "active", "verification_status": "verified", "nature_of_business": "Software development", "registered_capital": "USD 50000", "registered_capital_currency": "USD", "website": "https://docsprobe.example.com", "email": "legal@docsprobe.example.com", "phone": "+1 302 555 0143" }, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": "2026-06-12T00:02:34.276061Z", "is_editable": false } } } } } }, "400": { "description": "Errore di validazione. Gli errori di campo arrivano come `{\"\": [\"\"]}`. I controlli sulla lunghezza massima vengono eseguiti prima dei controlli di formato, quindi `country_code: \"USA\"` segnala il limite di 2 caratteri piuttosto che il messaggio ISO.", "content": { "application/json": { "examples": { "Alpha-3 country code": { "summary": "country_code deve essere alpha-2 — il controllo della lunghezza viene eseguito per primo", "value": { "country_code": [ "Ensure this field has no more than 2 characters." ] } }, "Non-alphabetic country code": { "summary": "2 caratteri ma non lettere", "value": { "country_code": [ "country_code must be a 2-letter ISO 3166-1 alpha-2 code." ] } }, "Invalid currency": { "summary": "3 caratteri ma non un codice ISO 4217", "value": { "registered_capital_currency": [ "Currency must be a 3-letter ISO 4217 code (e.g. USD, EUR, GBP)." ] } }, "Invalid phone": { "summary": "Il telefono non supera il controllo sul formato/conteggio delle cifre", "value": { "phone": [ "Invalid phone number format." ] } }, "Invalid registry status": { "summary": "registry_status non presente nell'enum", "value": { "registry_status": [ "\"liquidated\" is not a valid choice." ] } }, "Invalid email": { "summary": "Indirizzo email non valido", "value": { "email": [ "Enter a valid email address." ] } }, "Invalid website": { "summary": "Il valore non supera la validazione dell'URL anche dopo la normalizzazione con https://", "value": { "website": [ "Enter a valid URL." ] } }, "Bad date format": { "summary": "Le date devono essere YYYY-MM-DD", "value": { "incorporation_date": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } } } } } }, "403": { "description": "Credenziali mancanti o autorizzazioni insufficienti. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "La credenziale non dispone di write:businesses", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Sessione sconosciuta, azienda sconosciuta o azienda appartenente a una sessione diversa. Ciascun caso ha un messaggio `detail` distinto (vedi esempi). La ricerca della sessione sconosciuta viene eseguita prima dei controlli delle credenziali.", "content": { "application/json": { "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID nella tua applicazione (oppure è stata eliminata)", "value": { "detail": "Not found." } }, "Unknown company": { "summary": "Nessuna azienda con questo UUID nella tua applicazione", "value": { "detail": "No KYBCompany matches the given query." } }, "Company / session mismatch": { "summary": "companyUuid esiste ma appartiene a un'altra sessione", "value": { "detail": "KYB company does not belong to the given session." } } } } } }, "429": { "description": "Limite di frequenza di scrittura condiviso superato (300 richieste POST/PATCH/DELETE al minuto per chiave API). Esamina `Retry-After` e le intestazioni di risposta `X-RateLimit-*` prima di effettuare un nuovo tentativo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Budget di scrittura esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/33333333-4444-5555-6666-777777777777/kyb/88888888-9999-aaaa-bbbb-cccccccccccc/update-data/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"company_name\": \"Docs Probe Corp\",\n \"registration_number\": \"DPC-001\",\n \"country_code\": \"US\",\n \"incorporation_date\": \"2015-04-12\",\n \"company_type\": \"Limited Liability Company\",\n \"legal_address\": \"1 Example Plaza, Wilmington, DE 19801\",\n \"registry_status\": \"active\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_kyb_company_data(\n \"33333333-4444-5555-6666-777777777777\",\n \"88888888-9999-aaaa-bbbb-cccccccccccc\",\n company_name=\"Docs Probe Corp\",\n registration_number=\"DPC-001\",\n country_code=\"US\",\n incorporation_date=\"2015-04-12\",\n legal_address=\"1 Example Plaza, Wilmington, DE 19801\",\n company_type=\"Limited Liability Company\",\n registry_status=\"active\",\n verification_status=\"verified\",\n nature_of_business=\"Software development\",\n registered_capital=\"USD 50000\",\n website=\"docsprobe.example.com\",\n email=\"legal@docsprobe.example.com\",\n phone=\"+1 302 555 0143\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateKybCompanyData(\n \"33333333-4444-5555-6666-777777777777\",\n \"88888888-9999-aaaa-bbbb-cccccccccccc\",\n {\n company_name: \"Docs Probe Corp\",\n registration_number: \"DPC-001\",\n country_code: \"US\",\n incorporation_date: \"2015-04-12\",\n legal_address: \"1 Example Plaza, Wilmington, DE 19801\",\n company_type: \"Limited Liability Company\",\n registry_status: \"active\",\n verification_status: \"verified\",\n nature_of_business: \"Software development\",\n registered_capital: \"USD 50000\",\n website: \"docsprobe.example.com\",\n email: \"legal@docsprobe.example.com\",\n phone: \"+1 302 555 0143\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateKYBCompanyData(ctx, \"33333333-4444-5555-6666-777777777777\", \"88888888-9999-aaaa-bbbb-cccccccccccc\", didit.SessionsUpdateKYBCompanyDataParams{\n\tCompanyName: didit.String(\"Docs Probe Corp\"),\n\tRegistrationNumber: didit.String(\"DPC-001\"),\n\tCountryCode: didit.String(\"US\"),\n\tIncorporationDate: didit.String(\"2015-04-12\"),\n\tLegalAddress: didit.String(\"1 Example Plaza, Wilmington, DE 19801\"),\n\tCompanyType: didit.String(\"Limited Liability Company\"),\n\tRegistryStatus: didit.Some(didit.SessionsUpdateKYBCompanyDataParamsRegistryStatus(\"active\")),\n\tVerificationStatus: didit.Some(didit.SessionsUpdateKYBCompanyDataParamsVerificationStatus(\"verified\")),\n\tNatureOfBusiness: didit.String(\"Software development\"),\n\tRegisteredCapital: didit.String(\"USD 50000\"),\n\tWebsite: didit.String(\"docsprobe.example.com\"),\n\tEmail: didit.String(\"legal@docsprobe.example.com\"),\n\tPhone: didit.String(\"+1 302 555 0143\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdateKybCompanyDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateKybCompanyData(\"33333333-4444-5555-6666-777777777777\", \"88888888-9999-aaaa-bbbb-cccccccccccc\", SessionsUpdateKybCompanyDataParams.builder()\n .companyName(\"Docs Probe Corp\")\n .registrationNumber(\"DPC-001\")\n .countryCode(\"US\")\n .incorporationDate(LocalDate.parse(\"2015-04-12\"))\n .legalAddress(\"1 Example Plaza, Wilmington, DE 19801\")\n .companyType(\"Limited Liability Company\")\n .registryStatus(SessionsUpdateKybCompanyDataParams.RegistryStatus.of(\"active\"))\n .verificationStatus(SessionsUpdateKybCompanyDataParams.VerificationStatus.of(\"verified\"))\n .natureOfBusiness(\"Software development\")\n .registeredCapital(\"USD 50000\")\n .website(\"docsprobe.example.com\")\n .email(\"legal@docsprobe.example.com\")\n .phone(\"+1 302 555 0143\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateKybCompanyData('33333333-4444-5555-6666-777777777777', '88888888-9999-aaaa-bbbb-cccccccccccc', [\n 'company_name' => 'Docs Probe Corp',\n 'registration_number' => 'DPC-001',\n 'country_code' => 'US',\n 'incorporation_date' => '2015-04-12',\n 'legal_address' => '1 Example Plaza, Wilmington, DE 19801',\n 'company_type' => 'Limited Liability Company',\n 'registry_status' => 'active',\n 'verification_status' => 'verified',\n 'nature_of_business' => 'Software development',\n 'registered_capital' => 'USD 50000',\n 'website' => 'docsprobe.example.com',\n 'email' => 'legal@docsprobe.example.com',\n 'phone' => '+1 302 555 0143',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_kyb_company_data(\n \"33333333-4444-5555-6666-777777777777\",\n \"88888888-9999-aaaa-bbbb-cccccccccccc\",\n company_name: \"Docs Probe Corp\",\n registration_number: \"DPC-001\",\n country_code: \"US\",\n incorporation_date: \"2015-04-12\",\n legal_address: \"1 Example Plaza, Wilmington, DE 19801\",\n company_type: \"Limited Liability Company\",\n registry_status: \"active\",\n verification_status: \"verified\",\n nature_of_business: \"Software development\",\n registered_capital: \"USD 50000\",\n website: \"docsprobe.example.com\",\n email: \"legal@docsprobe.example.com\",\n phone: \"+1 302 555 0143\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateKybCompanyDataAsync(\"33333333-4444-5555-6666-777777777777\", \"88888888-9999-aaaa-bbbb-cccccccccccc\", new SessionsUpdateKybCompanyDataParams\n{\n CompanyName = \"Docs Probe Corp\",\n RegistrationNumber = \"DPC-001\",\n CountryCode = \"US\",\n IncorporationDate = \"2015-04-12\",\n LegalAddress = \"1 Example Plaza, Wilmington, DE 19801\",\n CompanyType = \"Limited Liability Company\",\n RegistryStatus = new SessionsUpdateKybCompanyDataParamsRegistryStatus(\"active\"),\n VerificationStatus = new SessionsUpdateKybCompanyDataParamsVerificationStatus(\"verified\"),\n NatureOfBusiness = \"Software development\",\n RegisteredCapital = \"USD 50000\",\n Website = \"docsprobe.example.com\",\n Email = \"legal@docsprobe.example.com\",\n Phone = \"+1 302 555 0143\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/parties/{partyUuid}/": { "patch": { "summary": "Salta (o richiedi nuovamente) un soggetto delle Persone chiave in una sessione di Verifica aziendale (KYB)", "description": "Esonera una persona chiave dalla verifica, oppure reinseriscila nell'ambito. Si tratta della via d'uscita per l'operatore per una persona chiave che non può completare il proprio controllo, molto spesso perché la sessione KYC individuale assegnata a un UBO o a un amministratore è stata eliminata, bloccando lo stato della sessione figlia e lasciando il KYB bloccato in `Awaiting User` senza alcuna possibilità di avanzamento.\n\nImpostando `is_skipped: true`, la persona chiave viene esclusa dall'aggregazione delle persone chiave e vengono ricalcolati immediatamente `KYBKeyPeopleCheck` e lo stato della sessione principale, consentendo alla sessione aziendale di concludersi per poi essere approvata o rifiutata. Inviando `is_skipped: false`, la persona chiave viene reinserita nell'ambito e il controllo torna in attesa della stessa.\n\nA differenza dell'opzione di esclusione disponibile al richiedente nella schermata ospitata delle persone chiave, questo endpoint **non** è vincolato dall'impostazione `allow_skip` del ruolo: tale flag limita ciò che il richiedente può decidere, non ciò che il tuo analista può sovrascrivere. Il campo `requires_verification` viene deliberatamente lasciato inalterato, per cui una persona chiave sovrascritta risulta con `requires_verification: true` **e** `is_skipped: true`, e il record continua a mostrare quanto richiesto dalle regole.\n\nLa persona chiave deve appartenere alla sessione indicata nel percorso (in caso contrario `404` con `\"Party does not belong to the given session.\"`) e alla tua applicazione. Una richiesta PATCH che modifica effettivamente il flag attiva il [webhook](/it/integration/webhooks) `data.updated` sulla sessione aziendale con trigger `console_key_people_skip`; una richiesta PATCH che imposta il flag sul suo valore corrente è un'operazione neutra che restituisce semplicemente la persona chiave.\n\nAccetta una chiave API o un token utente della console; in entrambi i casi la credenziale richiede l'autorizzazione `write:businesses`.", "operationId": "patch_v3_session_kyb_party_update", "x-didit-sdk": { "resource": "sessions", "method": "update_kyb_party", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione padre di Verifica aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "partyUuid", "in": "path", "required": true, "description": "UUID della parte relativa alle persone chiave da aggiornare (`key_people_checks[].submitted.parties[].uuid` nella decisione della sessione aziendale). Deve appartenere alla sessione a cui fa riferimento `sessionId`.", "schema": { "type": "string", "format": "uuid", "example": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_skipped" ], "properties": { "is_skipped": { "type": "boolean", "description": "`true` esenta la parte dalla verifica in modo che il controllo delle persone chiave possa risolversi senza di essa; `false` la reinserisce nell'ambito di verifica.", "example": true } } } } } }, "responses": { "200": { "description": "Parte aggiornata (o restituita invariata quando il flag aveva già questo valore). Restituisce la parte, con la stessa struttura di una voce di `key_people_checks[].submitted.parties[]` nella decisione della sessione aziendale.", "content": { "application/json": { "schema": { "type": "object", "description": "Record della parte relativa alle persone chiave: la stessa struttura di una voce di `key_people_checks[].submitted.parties[]` nella decisione della sessione aziendale.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificativo della parte." }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se la parte è una persona fisica o un'azienda." }, "name": { "type": "string", "description": "Nome visualizzato della parte." }, "is_skipped": { "type": "boolean", "description": "Indica se la parte è esente dalla verifica." }, "requires_verification": { "type": "boolean", "description": "Cosa richiedevano le regole di ruolo e di soglia. Lasciato invariato da questo endpoint." }, "kyc_session_status": { "type": "string", "nullable": true, "description": "Stato della sessione KYC individuale collegata, congelato al momento dell'eliminazione quando la sessione è stata eliminata." }, "kyc_session_url": { "type": "string", "nullable": true, "description": "Link alla sessione KYC individuale collegata. `null` se non è presente o se è stata eliminata." }, "kyc_session_deleted": { "type": "boolean", "description": "La sessione KYC individuale collegata è stata eliminata, pertanto non potrà mai concludersi." }, "kyb_sub_session_deleted": { "type": "boolean", "description": "Controparte aziendale di `kyc_session_deleted`." } } } } } }, "400": { "description": "Errore di validazione sul corpo della richiesta. `is_skipped` è l'unico campo letto da questo endpoint ed è obbligatorio. Gli errori di campo arrivano come `{\"\": [\"\"]}`. La validazione del corpo viene eseguita *dopo* la ricerca della parte, quindi un `is_skipped` non valido inviato a una parte inesistente restituisce `404`, non `400`.", "content": { "application/json": { "examples": { "Missing is_skipped": { "summary": "Corpo vuoto o corpo che omette `is_skipped`", "value": { "is_skipped": [ "This field is required." ] } }, "Non-boolean is_skipped": { "summary": "Il valore non è un booleano — `\"maybe\"`, `2`, `[]`. I booleani insieme a `\"true\"`/`\"false\"`, `1`/`0` e `\"yes\"`/`\"no\"` sono tutti accettati", "value": { "is_skipped": [ "Must be a valid boolean." ] } }, "Null is_skipped": { "summary": "`is_skipped` è presente ma è `null`", "value": { "is_skipped": [ "This field may not be null." ] } } } } } }, "403": { "description": "Credenziali mancanti o autorizzazioni insufficienti. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "La credenziale non dispone di write:businesses", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Parte sconosciuta o appartenente a una sessione diversa. Ciascun caso ha un messaggio `detail` distinto (vedi esempi). I controlli sulle credenziali e sulle autorizzazioni vengono eseguiti prima della ricerca della parte, pertanto una chiamata non autorizzata restituisce `403` invece di `404`. Non esiste una ricerca separata della sessione: un `sessionId` sconosciuto associato a una tua parte restituisce il messaggio di mancata corrispondenza.", "content": { "application/json": { "examples": { "Unknown party": { "summary": "Nessuna parte con questo UUID nella tua applicazione", "value": { "detail": "Not found." } }, "Party / session mismatch": { "summary": "partyUuid esiste ma è collegato a un'altra sessione", "value": { "detail": "Party does not belong to the given session." } } } } } }, "429": { "description": "Limite di frequenza di scrittura condiviso superato (300 richieste POST/PATCH/DELETE al minuto per chiave API). Esamina `Retry-After` e le intestazioni di risposta `X-RateLimit-*` prima di effettuare un nuovo tentativo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "Budget di scrittura esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n is_skipped=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateKybParty(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n {\n is_skipped: true,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateKYBParty(ctx, \"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\", didit.SessionsUpdateKYBPartyParams{\n\tIsSkipped: true,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateKybPartyParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateKybParty(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\", SessionsUpdateKybPartyParams.builder()\n .isSkipped(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateKybParty('33333333-4444-5555-6666-777777777777', '0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41', [\n 'is_skipped' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n is_skipped: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateKybPartyAsync(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\", new SessionsUpdateKybPartyParams\n{\n IsSkipped = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/travel-rule/settings/": { "get": { "summary": "Recupera impostazioni Travel Rule", "description": "Leggi le impostazioni di Travel Rule e il profilo VASP dell'applicazione. Crea automaticamente una riga di impostazioni predefinita (disabilitata) e un profilo vuoto alla prima lettura.", "operationId": "getTravelRuleSettings", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_settings", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/settings/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_settings()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveSettings();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveSettings(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveSettings();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveSettings();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_settings\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveSettingsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Impostazioni attuali di Travel Rule e profilo VASP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleSettingsDetail" }, "examples": { "Disabled (default)": { "value": { "is_enabled": false, "jurisdiction": "EU", "name_matching_strictness": "DEFAULT", "confirmation_timeout_hours": 48, "timeout_outcome": "HOLD", "threshold_amount": "0.00", "inbound_auto_accept": true, "allow_self_declaration": true, "allow_screenshot_proof": true, "auto_wallet_verification": true, "vasp_attribution_enabled": true, "legal_name": "", "lei": "", "compliance_email": "", "is_discoverable": true, "counterparty_screening_enabled": false, "sunrise_policy": "", "sunrise_jurisdictions": [ "CO", "KH", "VN" ], "non_responsive_policy": "", "travel_address": "", "disabled_networks": [], "networks": { "gtr": { "rail": "GTR", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "trust": { "rail": "TRUST", "mode": "unavailable", "state": "unavailable", "reason": "own_membership_only", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "verifyvasp": { "rail": "VERIFYVASP", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "sygna": { "rail": "SYGNA", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 } }, "didit_network": { "listed": false, "missing": [ "travel_rule_off", "legal_name_missing", "compliance_email_missing" ], "compliance_email_confirmed": false } } } } } } } } }, "put": { "summary": "Aggiorna le impostazioni di Travel Rule", "description": "Esegui l'upsert delle impostazioni della Travel Rule e del profilo VASP dell'applicazione. Aggiornamento parziale: invia solo i campi che desideri modificare. L'impostazione `is_enabled: true` richiede un valore non vuoto per `legal_name` (già memorizzato o incluso nella stessa richiesta), altrimenti restituisce 400.", "operationId": "updateTravelRuleSettings", "x-didit-sdk": { "resource": "travel_rule", "method": "update_settings", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleSettingsUpdate" }, "example": { "is_enabled": true, "legal_name": "Origin CASP SL", "jurisdiction": "EU", "name_matching_strictness": "DEFAULT", "confirmation_timeout_hours": 48, "timeout_outcome": "HOLD", "is_discoverable": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT https://verification.didit.me/v3/travel-rule/settings/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"is_enabled\": true, \"legal_name\": \"Origin CASP SL\", \"jurisdiction\": \"EU\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.update_settings(\n is_enabled=True,\n legal_name=\"Origin CASP SL\",\n jurisdiction=\"EU\",\n name_matching_strictness=\"DEFAULT\",\n confirmation_timeout_hours=48,\n timeout_outcome=\"HOLD\",\n is_discoverable=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.updateSettings({\n is_enabled: true,\n legal_name: \"Origin CASP SL\",\n jurisdiction: \"EU\",\n name_matching_strictness: \"DEFAULT\",\n confirmation_timeout_hours: 48,\n timeout_outcome: \"HOLD\",\n is_discoverable: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.UpdateSettings(ctx, didit.TravelRuleSettingsUpdate{\n\tIsEnabled: didit.Bool(true),\n\tLegalName: didit.String(\"Origin CASP SL\"),\n\tJurisdiction: didit.String(\"EU\"),\n\tNameMatchingStrictness: didit.Some(didit.TravelRuleSettingsUpdateNameMatchingStrictness(\"DEFAULT\")),\n\tConfirmationTimeoutHours: didit.Int(48),\n\tTimeoutOutcome: didit.Some(didit.TravelRuleSettingsUpdateTimeoutOutcome(\"HOLD\")),\n\tIsDiscoverable: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleSettingsUpdate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().updateSettings(TravelRuleSettingsUpdate.builder()\n .isEnabled(true)\n .legalName(\"Origin CASP SL\")\n .jurisdiction(\"EU\")\n .nameMatchingStrictness(TravelRuleSettingsUpdate.NameMatchingStrictness.of(\"DEFAULT\"))\n .confirmationTimeoutHours(48L)\n .timeoutOutcome(TravelRuleSettingsUpdate.TimeoutOutcome.of(\"HOLD\"))\n .isDiscoverable(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->updateSettings([\n 'is_enabled' => true,\n 'legal_name' => 'Origin CASP SL',\n 'jurisdiction' => 'EU',\n 'name_matching_strictness' => 'DEFAULT',\n 'confirmation_timeout_hours' => 48,\n 'timeout_outcome' => 'HOLD',\n 'is_discoverable' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.update_settings(\n is_enabled: true,\n legal_name: \"Origin CASP SL\",\n jurisdiction: \"EU\",\n name_matching_strictness: \"DEFAULT\",\n confirmation_timeout_hours: 48,\n timeout_outcome: \"HOLD\",\n is_discoverable: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.UpdateSettingsAsync(new TravelRuleSettingsUpdate\n{\n IsEnabled = true,\n LegalName = \"Origin CASP SL\",\n Jurisdiction = \"EU\",\n NameMatchingStrictness = new TravelRuleSettingsUpdateNameMatchingStrictness(\"DEFAULT\"),\n ConfirmationTimeoutHours = 48,\n TimeoutOutcome = new TravelRuleSettingsUpdateTimeoutOutcome(\"HOLD\"),\n IsDiscoverable = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Impostazioni e profilo aggiornati, con la stessa struttura del GET.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleSettingsDetail" } } } }, "400": { "description": "Errore di validazione, ad esempio abilitazione senza un legal_name, una sunrise_policy o non_responsive_policy diversa da HOLD, REJECT, PROCEED o vuota, un campo sconosciuto in `matching_rules`, oppure una scelta di `data_sharing_fields` che non è in grado di soddisfare gli obblighi dell'ordinante previsti dal regime della tua giurisdizione (gli errori sono indicizzati per tipo di entità sotto `data_sharing_fields`).", "content": { "application/json": { "schema": { "type": "object" }, "example": { "legal_name": [ "legal_name is required to enable travel rule." ] } } } } } } }, "/v3/travel-rule/settings/compliance-email/confirmation/": { "post": { "summary": "Invia la conferma via email della compliance", "description": "Invia un link di conferma monouso all'indirizzo compliance_email del tuo profilo VASP. Aprendo il link e premendo il pulsante di conferma si convalida l'indirizzo, operazione richiesta dalla rete Didit prima di pubblicare il tuo profilo. Una nuova richiesta sostituisce il link precedente; il link smette di funzionare se l'email di compliance viene modificata. Un'email al minuto per indirizzo.", "operationId": "sendTravelRuleComplianceEmailConfirmation", "x-didit-sdk": { "resource": "travel_rule", "method": "send_compliance_email_confirmation", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/settings/compliance-email/confirmation/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.send_compliance_email_confirmation()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.sendComplianceEmailConfirmation();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.SendComplianceEmailConfirmation(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().sendComplianceEmailConfirmation();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->sendComplianceEmailConfirmation();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.send_compliance_email_confirmation\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.SendComplianceEmailConfirmationAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "202": { "description": "L'email di conferma è stata inviata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent_to": { "type": "string", "format": "email" } } }, "example": { "sent_to": "compliance@your-vasp.example" } } } }, "400": { "description": "Nessuna email di compliance impostata, oppure è già confermata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "No compliance email": { "value": { "compliance_email": [ "Set a compliance email before confirming it." ] } }, "Already confirmed": { "value": { "compliance_email": [ "This compliance email is already confirmed." ] } } } } } }, "429": { "description": "Una conferma è stata inviata a questo indirizzo meno di un minuto fa." }, "503": { "description": "Impossibile inviare l'email. Non è cambiato nulla; riprova tra un momento." } } } }, "/v3/travel-rule/wallet-addresses/": { "get": { "summary": "Elenca le voci della rubrica degli indirizzi dei wallet", "description": "Elenco impaginato della rubrica degli indirizzi wallet della Travel Rule della tua applicazione, dal più recente.", "operationId": "listTravelRuleWalletAddresses", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/wallet-addresses/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.wallet_addresses.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.walletAddresses.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.WalletAddresses.ListAutoPaging(ctx, didit.TravelRuleWalletAddressesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().walletAddresses().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.wallet_addresses.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.WalletAddresses.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Voci della rubrica degli indirizzi wallet impaginate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WalletAddressEntry" } } } } } } } } }, "post": { "summary": "Registra un indirizzo wallet", "description": "Aggiungi una voce alla tua rubrica degli indirizzi wallet per la Travel Rule in modo che i trasferimenti in entrata tramite il canale INTERNAL-rail possano essere risolti rispetto a essa.", "operationId": "createTravelRuleWalletAddress", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntryCreate" }, "example": { "address": "0xBeneficiaryWallet01", "chain": "ETH", "holder_name": "Ana Diaz", "holder_vendor_data": "user-042", "self_declared": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"address\": \"0xBeneficiaryWallet01\", \"chain\": \"ETH\", \"holder_name\": \"Ana Diaz\", \"self_declared\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_addresses.create(\n address=\"0xBeneficiaryWallet01\",\n chain=\"ETH\",\n holder_vendor_data=\"user-042\",\n holder_name=\"Ana Diaz\",\n self_declared=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletAddresses.create({\n address: \"0xBeneficiaryWallet01\",\n chain: \"ETH\",\n holder_vendor_data: \"user-042\",\n holder_name: \"Ana Diaz\",\n self_declared: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.WalletAddresses.Create(ctx, didit.WalletAddressEntryCreate{\n\tAddress: \"0xBeneficiaryWallet01\",\n\tChain: didit.String(\"ETH\"),\n\tHolderVendorData: didit.String(\"user-042\"),\n\tHolderName: didit.String(\"Ana Diaz\"),\n\tSelfDeclared: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WalletAddressEntryCreate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletAddresses().create(WalletAddressEntryCreate.builder()\n .address(\"0xBeneficiaryWallet01\")\n .chain(\"ETH\")\n .holderVendorData(\"user-042\")\n .holderName(\"Ana Diaz\")\n .selfDeclared(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->create([\n 'address' => '0xBeneficiaryWallet01',\n 'chain' => 'ETH',\n 'holder_vendor_data' => 'user-042',\n 'holder_name' => 'Ana Diaz',\n 'self_declared' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_addresses.create(\n address: \"0xBeneficiaryWallet01\",\n chain: \"ETH\",\n holder_vendor_data: \"user-042\",\n holder_name: \"Ana Diaz\",\n self_declared: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletAddresses.CreateAsync(new WalletAddressEntryCreate\n{\n Address = \"0xBeneficiaryWallet01\",\n Chain = \"ETH\",\n HolderVendorData = \"user-042\",\n HolderName = \"Ana Diaz\",\n SelfDeclared = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "La voce creata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntry" } } } }, "400": { "description": "Wallet duplicato (indirizzo, blockchain e memo) per questa applicazione, un memo o X-address che la blockchain non può supportare, un `address` mancante, un `travel_address` non valido, `self_declared: true` mentre `allow_self_declaration` è disattivato, oppure `self_declared: true` mentre `ownership_validation_mode` è `FULL`.", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Duplicate entry": { "value": { "address": [ "A wallet address entry with this address and chain already exists." ] } }, "Invalid travel address": { "value": { "travel_address": [ "Invalid travel address." ] } }, "Self-declaration disabled": { "value": { "self_declared": [ "Self-declared ownership is disabled for this application." ] } } } } } } } } }, "/v3/travel-rule/wallet-addresses/{entry_uuid}/": { "patch": { "summary": "Aggiorna i metadati del titolare dell'indirizzo wallet", "description": "Aggiornamento parziale di holder_name, holder_vendor_data, entity_type e travel_address. L'impostazione di travel_address associa un indirizzo di instradamento TRP alla voce; i valori non validi vengono rifiutati con 400. La risposta restituisce solo questi quattro campi.", "operationId": "updateTravelRuleWalletAddress", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "entry_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntryUpdate" }, "example": { "holder_name": "Ana Updated", "travel_address": "ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH https://verification.didit.me/v3/travel-rule/wallet-addresses/{entry_uuid}/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"holder_name\": \"Ana Updated\", \"travel_address\": \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_addresses.update(\n \"11111111-2222-3333-4444-555555555555\",\n holder_name=\"Ana Updated\",\n travel_address=\"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletAddresses.update(\"11111111-2222-3333-4444-555555555555\", {\n holder_name: \"Ana Updated\",\n travel_address: \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.WalletAddresses.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WalletAddressEntryUpdateParam{\n\tHolderName: didit.String(\"Ana Updated\"),\n\tTravelAddress: didit.String(\"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WalletAddressEntryUpdate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletAddresses().update(\"11111111-2222-3333-4444-555555555555\", WalletAddressEntryUpdate.builder()\n .holderName(\"Ana Updated\")\n .travelAddress(\"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->update('11111111-2222-3333-4444-555555555555', [\n 'holder_name' => 'Ana Updated',\n 'travel_address' => 'ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_addresses.update(\n \"11111111-2222-3333-4444-555555555555\",\n holder_name: \"Ana Updated\",\n travel_address: \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletAddresses.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new WalletAddressEntryUpdate\n{\n HolderName = \"Ana Updated\",\n TravelAddress = \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "I campi aggiornati.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntryUpdate" } } } }, "400": { "description": "`travel_address` non è un Travel Address valido.", "content": { "application/json": { "examples": { "Invalid travel address": { "value": { "travel_address": [ "Invalid travel address." ] } } } } } }, "404": { "description": "Voce sconosciuta o eliminata." } } }, "delete": { "summary": "Elimina un indirizzo", "description": "Elimina la voce insieme alle relative prove di titolarità e agli screenshot memorizzati. Smette immediatamente di corrispondere a nuovi trasferimenti e l'indirizzo viene liberato per una nuova registrazione. I trasferimenti che hanno già utilizzato il wallet mantengono il proprio record e risultano invariati. L'eliminazione è irreversibile.", "operationId": "deleteTravelRuleWalletAddress", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "entry_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/travel-rule/wallet-addresses/{entry_uuid}/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.travel_rule.wallet_addresses.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.travelRule.walletAddresses.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.TravelRule.WalletAddresses.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.travelRule().walletAddresses().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.wallet_addresses.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.TravelRule.WalletAddresses.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "Eliminato." }, "404": { "description": "Voce sconosciuta o già eliminata." }, "503": { "description": "`wallet_address_deletion_incomplete`: non è stato possibile eliminare un file memorizzato, quindi l'eliminazione si è interrotta prima del completamento. La voce della rubrica è ancora presente; ripeti la stessa richiesta per completarla.", "content": { "application/json": { "example": { "detail": "A stored file could not be deleted, so the deletion stopped before it finished. Try again.", "code": "wallet_address_deletion_incomplete" } } } } } } }, "/v3/travel-rule/vasps/": { "get": { "summary": "Cerca nella directory dei VASP", "description": "Ricerca impaginata e ordinata per nome nella directory VASP: le voci della directory condivisa, che Didit crea dal registro provvisorio MiCA dell'ESMA, dalla directory pubblica TRISA, dal registro globale LEI e dalla propria selezione, oltre ai membri della rete Didit. Ogni riga riporta le rotte che la tua applicazione ha verso di essa oggi. Il profilo della tua applicazione non è mai elencato. Le righe riportano anche la valutazione di due diligence condivisa e la decisione, lo screening dell'entità e i questionari della tua applicazione.", "operationId": "listTravelRuleVasps", "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "Un frammento di nome o alias (senza distinzione tra maiuscole e minuscole), un LEI esatto o un dominio (example.com o un URL al suo interno). I membri della rete Didit corrispondono in base alla loro ragione sociale, al LEI o al dominio della loro email di compliance." }, { "name": "network", "in": "query", "schema": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA", "TRISA" ] }, "description": "Solo le voci di directory attualmente elencate nella directory dei membri di una rete." }, { "name": "jurisdiction", "in": "query", "schema": { "type": "string" }, "description": "Codice paese ISO 3166 alpha-2 o alpha-3. 400 per qualsiasi altra cosa." }, { "name": "reachable", "in": "query", "schema": { "type": "boolean" }, "description": "true: solo i VASP verso cui la tua applicazione ha un percorso disponibile (inclusi i membri della rete Didit). false: solo le voci della directory che la tua applicazione non può raggiungere oggi." }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "directory", "didit" ] }, "description": "Solo voci di directory, o solo membri della rete Didit." }, { "name": "risk", "in": "query", "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "description": "Solo le voci di directory il cui risk_level appartiene a questa fascia. I membri della rete Didit, a cui non viene assegnato un punteggio, non corrispondono mai." }, { "name": "responsiveness", "in": "query", "schema": { "type": "string", "enum": [ "RESPONSIVE", "UNRESPONSIVE", "UNKNOWN" ] }, "description": "Solo le voci di directory il cui responsiveness.status corrisponde a questo valore. I membri della rete Didit non corrispondono mai." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/travel-rule/vasps/?search=counterparty&reachable=true' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.list_vasps():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.listVasps()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.ListVASPsAutoPaging(ctx, didit.TravelRuleListVASPsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().listVasps()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->listVasps() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.list_vasps.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.ListVaspsAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Risultati della directory VASP impaginati e ordinati per nome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/VaspDirectoryEntry" } } } } } } }, "400": { "description": "Un filtro non è valido: il corpo indica ciascun campo, ad esempio una rete, un codice paese, una fascia di rischio o uno stato di reattività sconosciuto.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "jurisdiction": [ "Use an ISO 3166 alpha-2 or alpha-3 country code." ], "network": [ "\"SWIFT\" is not a valid choice." ] } } } } }, "x-didit-sdk": { "resource": "travel_rule", "method": "list_vasps", "auth": "api_key", "server": true } } }, "/v3/travel-rule/vasps/{vasp_id}/": { "get": { "summary": "Recupera una voce della directory VASP", "description": "Una voce della directory o un membro della rete Didit in base all'id restituito dalla ricerca, con gli stessi campi e le rotte che la tua applicazione ha verso di esso.", "operationId": "getTravelRuleVasp", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_vasp", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "L'id di una riga di GET /v3/travel-rule/vasps/." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_vasp(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveVasp(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveVASP(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveVasp(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveVasp('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_vasp(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveVaspAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La voce.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaspDirectoryEntry" } } } }, "404": { "description": "Nessuna voce o membro elencato della rete Didit ha questo id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry has this id." } } } } } } }, "/v3/travel-rule/vasps/{vasp_id}/decision/": { "get": { "summary": "Recupera la tua decisione su un VASP", "description": "La decisione della tua applicazione su una controparte (una voce della directory o un membro della rete Didit): approvata, limitata o bloccata. Un'entità di un brand senza una propria decisione segue la decisione del brand, indicata in inherited_from. Privata per la tua applicazione.", "operationId": "getTravelRuleVaspDecision", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_vasp_decision", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "L'id di una riga di GET /v3/travel-rule/vasps/: una voce della directory o un membro della rete Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveVASPDecision(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveVaspDecision('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_vasp_decision(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveVaspDecisionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La decisione applicabile, o null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionResponse" }, "examples": { "Own decision": { "value": { "decision": { "decision": "APPROVED", "reason": "Licensed in DE, questionnaire reviewed", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": null } } }, "Inherited from the brand": { "value": { "decision": { "decision": "BLOCKED", "reason": "Group refused after review", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": { "id": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b", "name": "Example Group" } } } }, "No decision": { "value": { "decision": null } } } } } }, "404": { "description": "Nessuna voce della directory o membro elencato della rete Didit ha questo id. Il tuo profilo VASP non è mai una tua controparte.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "put": { "summary": "Imposta la tua decisione su un VASP", "description": "Prendi o modifica la decisione della tua applicazione su una controparte: APPROVED, RESTRICTED o BLOCKED, con un motivo facoltativo. Non modifica mai la voce nella directory condivisa e agisce solo tramite le regole sulle transazioni (counterparty_dd_status). Una decisione su un brand copre anche ciascuna delle sue entità che non ha una propria decisione.", "operationId": "updateTravelRuleVaspDecision", "x-didit-sdk": { "resource": "travel_rule", "method": "update_vasp_decision", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "L'id di una riga di GET /v3/travel-rule/vasps/: una voce della directory o un membro della rete Didit." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionRequest" }, "example": { "decision": "BLOCKED", "reason": "Unlicensed in its home jurisdiction" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"decision\": \"BLOCKED\", \"reason\": \"Unlicensed in its home jurisdiction\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.update_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n decision=\"BLOCKED\",\n reason=\"Unlicensed in its home jurisdiction\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.updateVaspDecision(\"11111111-2222-3333-4444-555555555555\", {\n decision: \"BLOCKED\",\n reason: \"Unlicensed in its home jurisdiction\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.UpdateVASPDecision(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleCounterpartyDecisionRequest{\n\tDecision: \"BLOCKED\",\n\tReason: didit.String(\"Unlicensed in its home jurisdiction\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyDecisionRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().updateVaspDecision(\"11111111-2222-3333-4444-555555555555\", TravelRuleCounterpartyDecisionRequest.builder()\n .decision(TravelRuleCounterpartyDecisionRequest.Decision.of(\"BLOCKED\"))\n .reason(\"Unlicensed in its home jurisdiction\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->updateVaspDecision('11111111-2222-3333-4444-555555555555', [\n 'decision' => 'BLOCKED',\n 'reason' => 'Unlicensed in its home jurisdiction',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.update_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n decision: \"BLOCKED\",\n reason: \"Unlicensed in its home jurisdiction\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.UpdateVaspDecisionAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleCounterpartyDecisionRequest\n{\n Decision = \"BLOCKED\",\n Reason = \"Unlicensed in its home jurisdiction\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La decisione così come si applica ora.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionResponse" }, "example": { "decision": { "decision": "BLOCKED", "reason": "Unlicensed in its home jurisdiction", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": null } } } } }, "400": { "description": "La decisione è mancante o diversa da APPROVED, RESTRICTED o BLOCKED, oppure il motivo supera i 255 caratteri.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "decision": [ "\"MAYBE\" is not a valid choice." ] } } } }, "404": { "description": "Nessuna voce della directory o membro elencato della rete Didit ha questo id. Il tuo profilo VASP non è mai una tua controparte.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "delete": { "summary": "Cancella la tua decisione su un VASP", "description": "Cancella la decisione della tua applicazione su una controparte. La risposta mostra la decisione che si applica successivamente: null, oppure per un'entità di un brand la decisione del brand, che l'entità torna a seguire.", "operationId": "clearTravelRuleVaspDecision", "x-didit-sdk": { "resource": "travel_rule", "method": "clear_vasp_decision", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "L'id di una riga di GET /v3/travel-rule/vasps/: una voce della directory o un membro della rete Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.clear_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.clearVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.ClearVASPDecision(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().clearVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->clearVaspDecision('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.clear_vasp_decision(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.ClearVaspDecisionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La decisione è stata cancellata; il corpo mostra la decisione attualmente applicabile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionResponse" }, "example": { "decision": null } } } }, "404": { "description": "Nessuna controparte ha questo id, oppure la tua applicazione non ha una propria decisione su di essa (una decisione ereditata unicamente dal proprio brand non può essere rimossa qui: rimuovi quella del brand).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Unknown id": { "value": { "detail": "No directory entry or Didit network member has this id." } }, "No decision of its own": { "value": { "detail": "This application has no decision of its own on this counterparty." } } } } } } } } }, "/v3/travel-rule/vasps/{vasp_id}/screening/": { "get": { "summary": "Recupera lo screening dell'entità di un VASP", "description": "Indica se lo screening della controparte è attivo per la tua applicazione, quanto costa un singolo screening alla tua organizzazione, per quanto tempo un risultato rimane valido e il tuo screening più recente della controparte per sanzioni e notizie negative. La lettura è gratuita.", "operationId": "getTravelRuleVaspScreening", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_vasp_screening", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "L'id di una riga di GET /v3/travel-rule/vasps/: una voce della directory o un membro della rete Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/screening/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_vasp_screening(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveVaspScreening(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveVASPScreening(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveVaspScreening(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveVaspScreening('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_vasp_screening(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveVaspScreeningAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La tua impostazione di screening, il relativo prezzo e il tuo ultimo screening.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningStatus" }, "example": { "enabled": true, "price": "0.20", "fresh_days": 30, "screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "Approved", "total_hits": 0, "score": null, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": false } } } } }, "403": { "description": "Il contratto della tua organizzazione non prevede una tariffa configurata per lo screening delle controparti.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No contract rate is configured for this usage type." } } } }, "404": { "description": "Nessuna voce della directory o membro elencato della rete Didit ha questo id. Il tuo profilo VASP non è mai una tua controparte.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "post": { "summary": "Esegui lo screening di un VASP", "description": "Esegui lo screening dell'entità della controparte rispetto a sanzioni e notizie negative per la tua applicazione. Funzionalità facoltativa: counterparty_screening_enabled deve essere attivo nelle tue impostazioni di Travel Rule. Ciascun nuovo screening viene fatturato al prezzo di Screening AML aziendale della tua organizzazione; in caso contrario, viene restituito uno screening risalente a meno di 30 giorni fa (200, non fatturato), a meno che non invii refresh: true. Viene eseguito uno screening di una controparte alla volta per applicazione. Il risultato è privato per la tua applicazione. Le applicazioni sandbox non vengono mai sottoposte a screening.", "operationId": "screenTravelRuleVasp", "x-didit-sdk": { "resource": "travel_rule", "method": "screen_vasp", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "L'id di una riga di GET /v3/travel-rule/vasps/: una voce della directory o un membro della rete Didit." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningRequest" }, "example": { "refresh": false } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/screening/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"refresh\": false}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.screen_vasp(\n \"11111111-2222-3333-4444-555555555555\",\n refresh=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.screenVasp(\"11111111-2222-3333-4444-555555555555\", {\n refresh: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.ScreenVASP(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleCounterpartyScreeningRequest{\n\tRefresh: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyScreeningRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().screenVasp(\"11111111-2222-3333-4444-555555555555\", TravelRuleCounterpartyScreeningRequest.builder()\n .refresh(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->screenVasp('11111111-2222-3333-4444-555555555555', [\n 'refresh' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.screen_vasp(\n \"11111111-2222-3333-4444-555555555555\",\n refresh: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.ScreenVaspAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleCounterpartyScreeningRequest\n{\n Refresh = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Esisteva già uno screening recente che è stato restituito. Nessun addebito applicato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningResult" }, "example": { "outcome": "reused", "screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "Approved", "total_hits": 0, "score": null, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": false } } } } }, "201": { "description": "È stato eseguito un nuovo screening ed è stato fatturato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningResult" }, "example": { "outcome": "screened", "screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "In Review", "total_hits": 2, "score": 85.0, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": true } } } } }, "400": { "description": "Il body non è valido oppure la controparte non ha un nome da sottoporre a screening.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "detail": [ "This counterparty has no name to screen." ] } } } }, "403": { "description": "Il saldo della tua organizzazione non è sufficiente a coprire lo screening (codice insufficient_credits; nulla è stato eseguito e nulla è stato fatturato), oppure il tuo contratto non ha una tariffa configurata per questa operazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } }, "example": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me", "code": "insufficient_credits" } } } }, "404": { "description": "Nessuna voce della directory o membro elencato della rete Didit ha questo id. Il tuo profilo VASP non è mai una tua controparte.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } }, "409": { "description": "Non è stato eseguito nulla e non è stato addebitato alcun importo: lo screening della controparte è disattivato per la tua applicazione, l'applicazione è in ambiente sandbox oppure è già in corso uno screening per questa controparte.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Screening off": { "value": { "detail": "Counterparty screening is turned off. Enable it in the Travel Rule settings first." } }, "Sandbox application": { "value": { "detail": "Counterparty screening does not run for sandbox applications." } }, "Already running": { "value": { "detail": "A screening of this counterparty is already running. Try again in a moment." } } } } } }, "502": { "description": "Non è stato possibile completare lo screening. Non è stato fatturato nulla; riprova tra un momento.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "The screening provider did not answer. Try again in a moment." } } } } } } }, "/v3/travel-rule/vasps/{vasp_id}/questionnaires/": { "get": { "summary": "Elenca i questionari di due diligence con un VASP", "description": "Ogni questionario di due diligence inviato dalla tua applicazione alla controparte, dal più recente al più vecchio, con il rispettivo stato e, una volta compilato, le risposte. Riservato alla tua applicazione.", "operationId": "listTravelRuleVaspQuestionnaires", "x-didit-sdk": { "resource": "travel_rule", "method": "list_vasp_questionnaires", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "L'id di una riga di GET /v3/travel-rule/vasps/: una voce della directory o un membro della rete Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/questionnaires/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.list_vasp_questionnaires(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.listVaspQuestionnaires(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.ListVASPQuestionnaires(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().listVaspQuestionnaires(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->listVaspQuestionnaires('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.list_vasp_questionnaires(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.ListVaspQuestionnairesAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "I tuoi questionari con questa controparte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaireList" }, "example": { "questionnaires": [ { "id": "3f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f", "status": "SENT", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-10-14T10:00:00Z", "expires_at": "2026-11-13T10:00:00Z", "answered_at": null, "valid_until": null, "current": false, "answers": {} }, { "id": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "status": "ANSWERED", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-09-02T08:00:00Z", "expires_at": "2026-10-02T08:00:00Z", "answered_at": "2026-09-04T15:20:00Z", "valid_until": "2027-09-04T15:20:00Z", "current": true, "answers": { "legal_name": "Example Counterparty VASP, incorporated in the example jurisdiction.", "licensing": "Crypto-asset service provider authorised under MiCA by its national regulator, licence active.", "jurisdictions": "EU and EEA. We do not serve the United States.", "aml_program": "Written AML/CFT policy, annual independent review, last completed in March 2026.", "compliance_officer": "Head of Compliance, reachable at compliance@counterparty.example.", "sanctions_screening": "Customers at onboarding and daily; counterparties on every transfer.", "transaction_monitoring": "Rule-based monitoring with analyst review; suspicious activity reports filed with the FIU.", "travel_rule": "TRP and email; we answer requests within one business day.", "custody": "Segregated customer wallets held with a qualified custodian, insured.", "ownership": "No shareholder holds 25 percent or more; parent company Example Holding Group.", "record_keeping": "Five-year record-keeping for Travel Rule and transaction data, as our regulator requires.", "data_protection": "Encrypted at rest and in transit, stored in the EU." } } ] } } } }, "404": { "description": "Nessuna voce della directory o membro elencato della rete Didit ha questo id. Il tuo profilo VASP non è mai una tua controparte.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "post": { "summary": "Invia un questionario di due diligence a un VASP", "description": "Invia via email il questionario standard di due diligence di Didit a un indirizzo di compliance registrato per la controparte, con un link di risposta monouso. La controparte ha 30 giorni per rispondere a ogni domanda; le risposte rimangono valide per 365 giorni. Un nuovo invio sostituisce il precedente questionario senza risposta inviato alla stessa controparte, il cui link smetterà di funzionare. Un'email al minuto per indirizzo.", "operationId": "sendTravelRuleVaspQuestionnaire", "x-didit-sdk": { "resource": "travel_rule", "method": "send_vasp_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "L'id di una riga di GET /v3/travel-rule/vasps/: una voce della directory o un membro della rete Didit." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaireRequest" }, "example": { "sent_to": "travelrule@counterparty.example" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/questionnaires/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"sent_to\": \"travelrule@counterparty.example\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.send_vasp_questionnaire(\n \"11111111-2222-3333-4444-555555555555\",\n sent_to=\"travelrule@counterparty.example\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.sendVaspQuestionnaire(\"11111111-2222-3333-4444-555555555555\", {\n sent_to: \"travelrule@counterparty.example\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.SendVASPQuestionnaire(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleCounterpartyQuestionnaireRequest{\n\tSentTo: didit.String(\"travelrule@counterparty.example\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyQuestionnaireRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().sendVaspQuestionnaire(\"11111111-2222-3333-4444-555555555555\", TravelRuleCounterpartyQuestionnaireRequest.builder()\n .sentTo(\"travelrule@counterparty.example\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->sendVaspQuestionnaire('11111111-2222-3333-4444-555555555555', [\n 'sent_to' => 'travelrule@counterparty.example',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.send_vasp_questionnaire(\n \"11111111-2222-3333-4444-555555555555\",\n sent_to: \"travelrule@counterparty.example\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.SendVaspQuestionnaireAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleCounterpartyQuestionnaireRequest\n{\n SentTo = \"travelrule@counterparty.example\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "202": { "description": "Il questionario è stato inviato via email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaire" }, "example": { "id": "3f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f", "status": "SENT", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-10-14T10:00:00Z", "expires_at": "2026-11-13T10:00:00Z", "answered_at": null, "valid_until": null, "current": false, "answers": {} } } } }, "400": { "description": "sent_to non è un indirizzo email valido o non è un indirizzo di compliance registrato per la controparte, oppure la controparte non ha alcun indirizzo di compliance registrato.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Not on record": { "value": { "sent_to": [ "Send the questionnaire to a compliance address on record for this counterparty." ] } }, "No address": { "value": { "sent_to": [ "No compliance address is on record for this counterparty. Add a contact for it first." ] } } } } } }, "404": { "description": "Nessuna voce della directory o membro elencato della rete Didit ha questo id. Il tuo profilo VASP non è mai una tua controparte.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } }, "429": { "description": "Un questionario è stato inviato a questo indirizzo meno di un minuto fa." }, "503": { "description": "Impossibile inviare l'email e non è stato creato alcun questionario. Riprova tra un momento." } } } }, "/v3/transactions/{transaction_id}/travel-rule/": { "patch": { "summary": "Concludi, annulla, invia nuovamente o aggiorna il wallet dell'ordinante di un trasferimento Travel Rule", "description": "Fornisci `payment_txn_id` per comunicare l'hash on-chain e spostare un trasferimento in uscita da COMPLETED a FINISHED (anche la sua controparte su canale INTERNAL passa a FINISHED), `{\"action\": \"cancel\"}` per annullare un trasferimento non terminale, oppure `{\"action\": \"resend\"}` per instradare nuovamente un trasferimento in uscita bloccato in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE o NOT_ENOUGH_COUNTERPARTY_DATA (migliora prima i dati della controparte, ad es. aggiungendo un travel_address alla voce del wallet di destinazione). resend si applica solo ai trasferimenti in uscita. `{\"action\": \"update_compliance_email\", \"compliance_email\": \"desk@example.com\"}` sostituisce l'email di compliance di un trasferimento in uscita in uno di questi tre stati, la soluzione per `reason: email_undeliverable`: lo stato non cambia e il successivo `resend` invia la richiesta a quell'indirizzo. Un nuovo invio viene accodato, non eseguito all'interno della richiesta: la risposta mostra il trasferimento di nuovo in AWAITING_COUNTERPARTY con una voce `resend queued` nella timeline e una `delivery` in coda, e la destinazione raggiunta viene notificata tramite un webhook `travel_rule.status.updated`. Quando il trasferimento è passato tramite GTR, VerifyVASP o Sygna Bridge, la rete riceve l'hash on-chain o l'annullamento dopo la risposta, con nuovi tentativi; `delivery` mostra lo stato di quel messaggio. `{\"action\": \"update_originator_wallet\", \"wallet_address\": \"...\"}` registra il wallet da cui sono effettivamente partiti i fondi per un trasferimento in uscita, ad esempio l'indirizzo da cui è stato trasmesso un prelievo UTXO anziché il wallet principale dichiarato. Modifica solo la registrazione: non viene inviato nuovamente nulla alla controparte e lo stato rimane invariato. L'ordinante diventa `chain_details.originator` con `source: updated`, la modifica viene aggiunta alla `timeline` con il wallet precedente e quello nuovo, e la controparte su canale INTERNAL del trasferimento viene aggiornata nello stesso modo. `{\"action\": \"beneficiary_vasp\", \"beneficiary_vasp\": \"\"}` indica direttamente la controparte quando il rilevamento automatico non è riuscito, su un trasferimento in uscita in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE o NOT_ENOUGH_COUNTERPARTY_DATA: il trasferimento viene instradato verso quel VASP e inviato nuovamente.", "operationId": "patchTravelRuleTransfer", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "update_transfer", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID della transazione stabile di Didit a cui appartiene il trasferimento.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTransferPatchRequest" }, "examples": { "Finish": { "value": { "payment_txn_id": "0xchainhash" } }, "Cancel": { "value": { "action": "cancel" } }, "Resend": { "value": { "action": "resend" } }, "Update compliance email": { "value": { "action": "update_compliance_email", "compliance_email": "desk@example.com" } }, "Update originator wallet": { "value": { "action": "update_originator_wallet", "wallet_address": "bc1qOriginatorInputAddress01" } }, "Name the counterparty": { "value": { "action": "beneficiary_vasp", "beneficiary_vasp": "9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"payment_txn_id\": \"0xchainhash\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.update_transfer(\n \"11111111-2222-3333-4444-555555555555\",\n payment_txn_id=\"0xchainhash\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.updateTransfer(\"11111111-2222-3333-4444-555555555555\", {\n payment_txn_id: \"0xchainhash\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.UpdateTransfer(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleTransferPatchRequest{\n\tPaymentTxnID: didit.String(\"0xchainhash\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleTransferPatchRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().updateTransfer(\"11111111-2222-3333-4444-555555555555\", TravelRuleTransferPatchRequest.builder()\n .paymentTxnId(\"0xchainhash\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->updateTransfer('11111111-2222-3333-4444-555555555555', [\n 'payment_txn_id' => '0xchainhash',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.update_transfer(\n \"11111111-2222-3333-4444-555555555555\",\n payment_txn_id: \"0xchainhash\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.UpdateTransferAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleTransferPatchRequest\n{\n PaymentTxnId = \"0xchainhash\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il trasferimento aggiornato. Dopo `update_compliance_email`, il suo stato rimane invariato e mantiene `reason: email_undeliverable` fino al successivo `resend`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } } }, "400": { "description": "Non è stato fornito né payment_txn_id né un'azione supportata, `compliance_email` è mancante o non è un indirizzo email su `update_compliance_email`, oppure, per `update_originator_wallet`, manca wallet_address, è presente un wallet o memo non supportato dalla blockchain del trasferimento, o un wallet che non fa parte degli input UTXO del trasferimento, oppure `beneficiary_vasp` è mancante o non è un ID VASP valido della directory.", "content": { "application/json": { "examples": { "No action": { "value": { "detail": [ "Provide payment_txn_id, action=cancel, action=resend, action=beneficiary_vasp, action=update_originator_wallet or action=update_compliance_email." ] } }, "Invalid compliance email": { "value": { "compliance_email": [ "Enter a valid email address." ] } } } } } }, "404": { "description": "Transazione sconosciuta, la transazione non contiene alcun trasferimento Travel Rule oppure (azione `beneficiary_vasp`) nessuna voce della directory ha quell'id." }, "409": { "description": "Il trasferimento non si trova in uno stato che consente questa operazione (ad es. non COMPLETED/in uscita per finish, già in stato finale per cancel, oppure non un trasferimento in uscita in uno stato reinviabile per resend). `update_compliance_email` risponde con `409` per un trasferimento in entrata, e per uno in uscita al di fuori di COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE e NOT_ENOUGH_COUNTERPARTY_DATA. `update_originator_wallet` risponde con `409` per un trasferimento in entrata, annullato o scaduto. `beneficiary_vasp` risponde con `409` a meno che il trasferimento non sia in uscita e in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE o NOT_ENOUGH_COUNTERPARTY_DATA.", "content": { "application/json": { "examples": { "Cancel from a terminal status": { "value": { "detail": "Transfer is already in a terminal state." } }, "Resend not allowed": { "value": { "detail": "Transfer cannot be resent from its current state." } }, "Finish not allowed": { "value": { "detail": "Transfer must be an outbound transfer in COMPLETED status to finish." } }, "Compliance email cannot change": { "value": { "detail": "The compliance email of this transfer cannot change from its current state." } } } } } } } } }, "/v3/transactions/{transaction_id}/travel-rule/ownership/": { "post": { "summary": "Conferma o nega l'assetto proprietario del wallet", "description": "Risolvi un trasferimento in attesa dell'assetto proprietario del wallet: chiamalo dal tuo lato del trasferimento quando è UNCONFIRMED_OWNERSHIP, oppure quando è un trasferimento in entrata in ON_HOLD. La conferma contrassegna la voce corrispondente nella rubrica degli indirizzi wallet come verificata per la proprietà (per un trasferimento in entrata ON_HOLD senza alcuna voce, Didit ne crea una da beneficiary_data.wallet_address) ed esegue la corrispondenza del nome del beneficiario su entrambi i lati del trasferimento; il diniego rifiuta entrambi i lati. Un trasferimento in entrata il cui deposito è già stato regolato passa a FINISHED quando la corrispondenza ha successo. Quando il wallet della controparte è stato dichiarato in autocustodia (counterparty.payment_method.method_type: unhosted_wallet), la conferma registra che il cliente ha verificato chi controlla tale wallet e completa il trasferimento (COMPLETED) in entrambe le direzioni, o FINISHED per un deposito in entrata il cui hash on-chain è già noto. Il wallet verificato è quello della controparte: la destinazione di un prelievo in uscita o l'origine (il wallet dell'ordinante) di un deposito in entrata. Se non è ancora presente nella tua rubrica degli indirizzi wallet, Didit lo aggiunge come verificato per la proprietà con il nome della controparte; se la rubrica lo contiene già con un nome di titolare diverso, il trasferimento passa a COUNTERPARTY_MISMATCHED_DATA. Per un trasferimento TRP in entrata in UNCONFIRMED_OWNERSHIP, ON_HOLD o COUNTERPARTY_MISMATCHED_DATA, Didit invia invece la tua decisione al VASP ordinante: l'approvazione restituisce l'indirizzo di pagamento (wallet_address o l'indirizzo della voce corrispondente) e sposta il trasferimento a COMPLETED, mentre il diniego lo rifiuta. La stessa chiamata decide anche un trasferimento in entrata inviato da una controparte GTR o Sygna Bridge e in attesa della tua revisione (`UNCONFIRMED_OWNERSHIP`, `ON_HOLD` o `COUNTERPARTY_MISMATCHED_DATA`): `confirmed: true` lo approva (passa `wallet_address` quando il trasferimento non ne indica alcuno) e `confirmed: false` lo rifiuta, e la rete riceve la risposta successivamente, con nuovi tentativi. VerifyVASP riceve la risposta al momento della richiesta, pertanto un trasferimento VerifyVASP che richiederebbe la tua revisione viene rifiutato immediatamente e non può essere deciso in seguito.", "operationId": "confirmTravelRuleOwnership", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "confirm_ownership", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID stabile di Didit della transazione che la tua applicazione detiene per questo trasferimento: la transazione lato beneficiario su un trasferimento su circuito INTERNAL, o la transazione che hai creato (in entrata o in uscita) quando il wallet della controparte è stato dichiarato in autocustodia.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleOwnershipConfirmRequest" }, "example": { "confirmed": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/ownership/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"confirmed\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.confirm_ownership(\n \"11111111-2222-3333-4444-555555555555\",\n confirmed=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.confirmOwnership(\"11111111-2222-3333-4444-555555555555\", {\n confirmed: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.ConfirmOwnership(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleOwnershipConfirmRequest{\n\tConfirmed: true,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleOwnershipConfirmRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().confirmOwnership(\"11111111-2222-3333-4444-555555555555\", TravelRuleOwnershipConfirmRequest.builder()\n .confirmed(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->confirmOwnership('11111111-2222-3333-4444-555555555555', [\n 'confirmed' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.confirm_ownership(\n \"11111111-2222-3333-4444-555555555555\",\n confirmed: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.ConfirmOwnershipAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleOwnershipConfirmRequest\n{\n Confirmed = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il trasferimento aggiornato. Per un trasferimento in entrata, i dati originator_data/beneficiary_data della controparte rimangono mascherati (`data_masked: true`) finché la titolarità non viene confermata; successivamente `data_unmasked` registra quando, perché e da chi.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } } }, "409": { "description": "Il trasferimento non è in attesa di conferma dell'assetto proprietario, nessuna voce della rubrica degli indirizzi wallet corrisponde al relativo wallet della controparte, un trasferimento INTERNAL da un altro cliente Didit richiede una prova di controllo (un messaggio firmato o un deposito di prova) prima di poter essere confermato, oppure un trasferimento di rete ha già ricevuto risposta sulla relativa rete (un trasferimento VerifyVASP, o un trasferimento GTR o Sygna Bridge su cui tu o Didit avete già deciso).", "content": { "application/json": { "examples": { "Not awaiting confirmation": { "value": { "detail": "Transfer is not awaiting ownership confirmation." } }, "No matching address book entry": { "value": { "detail": "wallet address entry no longer available" } } } } } }, "400": { "description": "Errore di validazione: confirmed è mancante, un'approvazione TRP in entrata non ha alcun wallet_address e nessun indirizzo su cui ripiegare, oppure `confirmed: true` su un trasferimento dichiarato verso un wallet in autocustodia che non specifica alcun wallet della controparte e non è stato inviato alcun `wallet_address`.", "content": { "application/json": { "examples": { "No payment address": { "value": { "wallet_address": [ "wallet_address is required to approve." ] } } } } } }, "404": { "description": "Transazione sconosciuta, oppure la transazione non contiene alcun trasferimento Travel Rule." }, "502": { "description": "Solo per trasferimenti TRP in entrata: Didit non è riuscito a recapitare la tua decisione al VASP ordinante, pertanto lo stato del trasferimento non cambia.", "content": { "application/json": { "examples": { "Callback not delivered": { "value": { "detail": "Counterparty inquiry-resolution callback could not be delivered." } } } } } } } } }, "/v3/transactions/{transaction_id}/travel-rule/messages/": { "get": { "summary": "Elenca i messaggi Travel Rule", "description": "Messaggi e richieste di documenti scambiati con il VASP di controparte in merito a questo trasferimento.", "operationId": "listTravelRuleMessages", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "list_messages", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID della transazione stabile di Didit a cui appartiene il trasferimento.", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/messages/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.list_messages(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.listMessages(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.ListMessages(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().listMessages(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->listMessages('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.travel_rule.list_messages(\"11111111-2222-3333-4444-555555555555\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.ListMessagesAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "I messaggi, dai meno recenti ai più recenti.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleMessage" } } } } }, "404": { "description": "Transazione o token sconosciuti, oppure nessun trasferimento Travel Rule presente nella transazione." } } }, "post": { "summary": "Invia un messaggio o una richiesta di documenti Travel Rule", "description": "Invia un messaggio o una richiesta di documento al VASP di controparte. Funziona sui trasferimenti INTERNAL (l'altro cliente Didit lo vede sul proprio lato della coppia) e sui trasferimenti EMAIL (la controparte riceve un'email e risponde nel portale di ritiro). Un trasferimento tramite TRP, GTR, TRUST, VerifyVASP o Sygna non trasmette messaggi, poiché tali protocolli non ne prevedono. Limiti: 100 messaggi per trasferimento, 5000 caratteri per corpo, 10 documenti richiesti, 5 file da 10 MB ciascuno.", "operationId": "createTravelRuleMessage", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "create_message", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID della transazione stabile di Didit a cui appartiene il trasferimento.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" }, "example": { "kind": "DOCUMENT_REQUEST", "body": "Please confirm the date of birth of the beneficiary.", "requested_documents": [ "Proof of address" ] } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/messages/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"kind\": \"DOCUMENT_REQUEST\", \"body\": \"Please confirm the date of birth of the beneficiary.\", \"requested_documents\": [\"Proof of address\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.create_message(\n \"11111111-2222-3333-4444-555555555555\",\n kind=\"DOCUMENT_REQUEST\",\n body=\"Please confirm the date of birth of the beneficiary.\",\n requested_documents=[\"Proof of address\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.createMessage(\"11111111-2222-3333-4444-555555555555\", {\n kind: \"DOCUMENT_REQUEST\",\n body: \"Please confirm the date of birth of the beneficiary.\",\n requested_documents: [\"Proof of address\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.CreateMessage(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleMessageCreateRequest{\n\tKind: didit.Some(didit.TravelRuleMessageCreateRequestKind(\"DOCUMENT_REQUEST\")),\n\tBody: didit.String(\"Please confirm the date of birth of the beneficiary.\"),\n\tRequestedDocuments: didit.Some([]string{\"Proof of address\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TravelRuleMessageCreateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().createMessage(\"11111111-2222-3333-4444-555555555555\", TravelRuleMessageCreateRequest.builder()\n .kind(TravelRuleMessageCreateRequest.Kind.of(\"DOCUMENT_REQUEST\"))\n .body(\"Please confirm the date of birth of the beneficiary.\")\n .requestedDocuments(List.of(\"Proof of address\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->createMessage('11111111-2222-3333-4444-555555555555', [\n 'kind' => 'DOCUMENT_REQUEST',\n 'body' => 'Please confirm the date of birth of the beneficiary.',\n 'requested_documents' => ['Proof of address'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.create_message(\n \"11111111-2222-3333-4444-555555555555\",\n kind: \"DOCUMENT_REQUEST\",\n body: \"Please confirm the date of birth of the beneficiary.\",\n requested_documents: [\"Proof of address\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.CreateMessageAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleMessageCreateRequest\n{\n Kind = new TravelRuleMessageCreateRequestKind(\"DOCUMENT_REQUEST\"),\n Body = \"Please confirm the date of birth of the beneficiary.\",\n RequestedDocuments = new string[] { \"Proof of address\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Il messaggio memorizzato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessage" } } } }, "400": { "description": "Corpo non valido, un tipo o una dimensione di file non accettati, più di 100 messaggi sul trasferimento o un `reply_to` che non è un messaggio di questo trasferimento.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "requested_documents": [ "Name at least one document the counterparty should send." ] } } } }, "404": { "description": "Transazione o token sconosciuti, oppure nessun trasferimento Travel Rule presente nella transazione." }, "409": { "description": "Nessun messaggio può raggiungere la controparte. `detail` specifica il motivo: il trasferimento viene eseguito su un circuito di rete (TRP, GTR, TRUST, VerifyVASP o Sygna), non ha ancora una controparte, i dati di un trasferimento INTERNAL non corrispondevano al titolare del wallet quindi nulla ha raggiunto il destinatario, oppure il link di ritiro di un trasferimento EMAIL è scaduto o il trasferimento è chiuso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/travel-rule/pickup/{token}/": { "get": { "summary": "Recupera informazioni di ritiro via email-rail", "description": "Pubblico, non autenticato. Consente a un VASP di controparte non Didit di visualizzare in anteprima lo scambio in sospeso dal link di ritiro inviato via email. Il token stesso funge da autenticazione.", "operationId": "getTravelRulePickup", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_pickup", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Il valore `?contact=` del link, il contatto a cui è stato inviato il link. Viene restituito inalterato come `contact`; non viene validato." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/pickup/{token}/" } ], "responses": { "200": { "description": "Anteprima del ritiro.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRulePickupInfo" }, "example": { "reference": "33333333-4444-5555-6666-777777777777", "requested_at": "2026-07-05T10:00:00Z", "originator_vasp_name": "Origin CASP SL", "originator_vasp_lei": "529900EXAMPLEORIG001", "recipient_vasp_name": "Example Counterparty VASP", "language": "es", "amount": "0.250000000000000000", "currency": "ETH", "fiat_amount": "", "fiat_currency": "", "chain": "ETH", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "status": "AWAITING_COUNTERPARTY", "ivms_version": "ivms101.2023", "deadline_at": "2026-07-07T10:00:00Z", "reminders_sent": 0, "contact": "", "decline_reasons": [ "data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other" ], "join_invitation": { "eligible": false, "url": "" }, "originator_data": { "name": "Jane Doe", "wallet_address": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" }, "beneficiary_data": { "name": "Ana Diaz", "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb" }, "ivms_request": { "originator": { "originatorPersons": [ { "naturalPerson": { "name": { "nameIdentifier": [ { "primaryIdentifier": "Doe", "secondaryIdentifier": "Jane", "nameIdentifierType": "LEGL" } ] } } } ], "accountNumber": [ "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" ] }, "beneficiary": { "beneficiaryPersons": [ { "naturalPerson": { "name": { "nameIdentifier": [ { "primaryIdentifier": "Diaz", "secondaryIdentifier": "Ana", "nameIdentifierType": "LEGL" } ] } } } ], "accountNumber": [ "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb" ] } }, "data_masked": false } } } }, "404": { "description": "Token sconosciuto." }, "410": { "description": "La finestra si è chiusa: la controparte ha già risposto, il trasferimento ha lasciato lo stato AWAITING_COUNTERPARTY oppure il termine è scaduto." } } } }, "/v3/travel-rule/pickup/{token}/respond/": { "post": { "summary": "Rispondi a una presa in carico tramite canale email", "description": "Pubblico, non autenticato. Accetta o rifiuta lo scambio dal link di ritiro inviato via email. In caso di accettazione, beneficiary_name viene verificato rispetto alla policy name_matching_strictness dell'ordinante.", "operationId": "respondTravelRulePickup", "x-didit-sdk": { "resource": "travel_rule", "method": "respond_pickup", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Il valore `?contact=` del link. Utilizzato quando il payload non invia alcun `contact`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRulePickupRespondRequest" }, "example": { "decision": "accept", "beneficiary_name": "Carlos Ruiz" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/respond/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"decision\": \"accept\", \"beneficiary_name\": \"Carlos Ruiz\"}'" } ], "responses": { "200": { "description": "Lo stato dello scambio risultante: COMPLETED o COUNTERPARTY_MISMATCHED_DATA dopo un'accettazione, COUNTERPARTY_VASP_GENERAL_DECLINE dopo un rifiuto, che riporta anche `decline_reason`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "decline_reason": { "type": "string", "description": "Presente dopo un rifiuto." } } }, "examples": { "accepted": { "value": { "status": "COMPLETED" } }, "declined": { "value": { "status": "COUNTERPARTY_VASP_GENERAL_DECLINE", "decline_reason": "not_our_customer" } } } } } }, "400": { "description": "Un campo non è valido: ad esempio `decision` mancante o diverso da `accept` o `decline`, `decline_detail` mancante in caso di rifiuto con `decline_reason: other`, una `ivms_response` che non è un oggetto IVMS 101 o supera i 16384 caratteri, oppure un `contact` nel body che non è un UUID (`{\"contact\": [\"Must be a valid UUID.\"]}`).", "content": { "application/json": { "example": { "decline_detail": [ "Say what the reason is when you choose another reason." ] } } } }, "404": { "description": "Token sconosciuto." }, "410": { "description": "La finestra si è chiusa: la controparte ha già risposto, il trasferimento ha lasciato lo stato AWAITING_COUNTERPARTY oppure il termine è scaduto." } } } }, "/v3/travel-rule/pickup/{token}/messages/": { "get": { "summary": "Elenca i messaggi di ritiro", "description": "Pubblico, non autenticato. I messaggi di un trasferimento su circuito EMAIL così come vengono letti dal VASP di controparte: ciò che il cliente ha inviato è `INBOUND` ed è firmato con il nome del VASP del cliente. Il token funge da autenticazione.", "operationId": "listTravelRulePickupMessages", "x-didit-sdk": { "resource": "travel_rule", "method": "list_pickup_messages", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/pickup/{token}/messages/" } ], "responses": { "200": { "description": "I messaggi, dai meno recenti ai più recenti, provenienti dalla controparte.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleMessage" } } } } }, "404": { "description": "Token sconosciuto." }, "410": { "description": "Il link di ritiro è scaduto o il trasferimento è chiuso." } } }, "post": { "summary": "Rispondi nel portale di ritiro", "description": "Pubblico, non autenticato. Il VASP di controparte risponde su un trasferimento su circuito EMAIL. Stesso corpo dei messaggi della transazione; gli allegati devono essere in formato PDF, PNG, JPEG o WebP. Il token funge da autenticazione.", "operationId": "createTravelRulePickupMessage", "x-didit-sdk": { "resource": "travel_rule", "method": "create_pickup_message", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" }, "example": { "kind": "MESSAGE", "body": "Attached is the proof of address of the wallet holder." } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/messages/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"kind\": \"MESSAGE\", \"body\": \"Attached is the proof of address of the wallet holder.\"}'" } ], "responses": { "201": { "description": "Il messaggio memorizzato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessage" } } } }, "400": { "description": "Corpo non valido, un tipo o una dimensione di file non accettati, più di 100 messaggi sul trasferimento o un `reply_to` che non è un messaggio di questo trasferimento.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "requested_documents": [ "Name at least one document the counterparty should send." ] } } } }, "404": { "description": "Token sconosciuto." }, "410": { "description": "Il link di ritiro è scaduto o il trasferimento è chiuso." } } } }, "/v3/travel-rule/inbound/": { "post": { "summary": "Registra un trasferimento in entrata successivo al deposito (sunrise)", "description": "Registra i dati della Travel Rule per un deposito in criptovalute già regolato on-chain prima che avvenisse qualsiasi scambio. Crea una transazione travelRule in entrata (o riutilizza un deposito non riscattato) e riconcilia il trasferimento con la rubrica dei tuoi indirizzi wallet. Per una transazione appena creata, Didit invia prima transaction.created e successivamente i webhook travel_rule.status.updated.", "operationId": "registerTravelRuleInbound", "x-didit-sdk": { "resource": "travel_rule", "method": "register_inbound", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleInboundRequest" }, "example": { "chain": "ETH", "txid": "0xdeposit-hash", "wallet_address": "0xYourDepositWallet", "amount": "500.00", "currency": "USDC", "originator_data": { "name": "Origin CASP SL" }, "beneficiary_data": { "name": "Ana Diaz" }, "originating_vasp": { "name": "Origin CASP SL", "lei": "", "travel_address": "ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/inbound/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"chain\":\"ETH\",\"txid\":\"0xdeposit-hash\",\"wallet_address\":\"0xYourDepositWallet\",\"amount\":\"500.00\",\"currency\":\"USDC\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.register_inbound(\n chain=\"ETH\",\n txid=\"0xdeposit-hash\",\n wallet_address=\"0xYourDepositWallet\",\n amount=\"500.00\",\n currency=\"USDC\",\n originator_data={\"name\": \"Origin CASP SL\"},\n beneficiary_data={\"name\": \"Ana Diaz\"},\n originating_vasp={\n \"name\": \"Origin CASP SL\",\n \"lei\": \"\",\n \"travel_address\": \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.registerInbound({\n chain: \"ETH\",\n txid: \"0xdeposit-hash\",\n wallet_address: \"0xYourDepositWallet\",\n amount: \"500.00\",\n currency: \"USDC\",\n originator_data: { name: \"Origin CASP SL\" },\n beneficiary_data: { name: \"Ana Diaz\" },\n originating_vasp: {\n name: \"Origin CASP SL\",\n lei: \"\",\n travel_address: \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RegisterInbound(ctx, didit.TravelRuleInboundRequest{\n\tChain: \"ETH\",\n\tTxid: \"0xdeposit-hash\",\n\tWalletAddress: \"0xYourDepositWallet\",\n\tAmount: \"500.00\",\n\tCurrency: \"USDC\",\n\tOriginatorData: didit.Some(map[string]any{\"name\": \"Origin CASP SL\"}),\n\tBeneficiaryData: didit.Some(map[string]any{\"name\": \"Ana Diaz\"}),\n\tOriginatingVASP: didit.Some(didit.TravelRuleInboundRequestOriginatingVASP{\n\t\tName: didit.String(\"Origin CASP SL\"),\n\t\tLei: didit.String(\"\"),\n\t\tTravelAddress: didit.String(\"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.TravelRuleInboundRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().registerInbound(TravelRuleInboundRequest.builder()\n .chain(\"ETH\")\n .txid(\"0xdeposit-hash\")\n .walletAddress(\"0xYourDepositWallet\")\n .amount(\"500.00\")\n .currency(\"USDC\")\n .originatorData(Map.of(\"name\", \"Origin CASP SL\"))\n .beneficiaryData(Map.of(\"name\", \"Ana Diaz\"))\n .originatingVasp(TravelRuleInboundRequest.OriginatingVasp.builder()\n .name(\"Origin CASP SL\")\n .lei(\"\")\n .travelAddress(\"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->registerInbound([\n 'chain' => 'ETH',\n 'txid' => '0xdeposit-hash',\n 'wallet_address' => '0xYourDepositWallet',\n 'amount' => '500.00',\n 'currency' => 'USDC',\n 'originator_data' => ['name' => 'Origin CASP SL'],\n 'beneficiary_data' => ['name' => 'Ana Diaz'],\n 'originating_vasp' => [\n 'name' => 'Origin CASP SL',\n 'lei' => '',\n 'travel_address' => 'ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.register_inbound(\n chain: \"ETH\",\n txid: \"0xdeposit-hash\",\n wallet_address: \"0xYourDepositWallet\",\n amount: \"500.00\",\n currency: \"USDC\",\n originator_data: { name: \"Origin CASP SL\" },\n beneficiary_data: { name: \"Ana Diaz\" },\n originating_vasp: {\n name: \"Origin CASP SL\",\n lei: \"\",\n travel_address: \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RegisterInboundAsync(new TravelRuleInboundRequest\n{\n Chain = \"ETH\",\n Txid = \"0xdeposit-hash\",\n WalletAddress = \"0xYourDepositWallet\",\n Amount = \"500.00\",\n Currency = \"USDC\",\n OriginatorData = new Dictionary { [\"name\"] = \"Origin CASP SL\" },\n BeneficiaryData = new Dictionary { [\"name\"] = \"Ana Diaz\" },\n OriginatingVasp = new TravelRuleInboundRequestOriginatingVasp\n {\n Name = \"Origin CASP SL\",\n Lei = \"\",\n TravelAddress = \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Un trasferimento per questo txid e wallet_address era già registrato; quello esistente viene restituito invariato (created è false).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleInboundResponse" } } } }, "201": { "description": "È stato registrato un nuovo trasferimento Travel Rule, su una nuova transazione in entrata o su un deposito esistente non reclamato (created è true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleInboundResponse" } } } }, "400": { "description": "Un campo obbligatorio (`chain`, `txid`, `wallet_address`, `amount`, `currency`) è mancante, `originating_vasp.lei` non è un LEI valido, `originating_vasp.travel_address` non è un Travel Address valido, un memo, un X-address o un `utxo` che la rete non può supportare, oppure `originator_data` / `beneficiary_data` non è un oggetto.", "content": { "application/json": { "examples": { "Missing field": { "value": { "txid": [ "This field is required." ] } }, "Invalid LEI": { "value": { "originating_vasp": { "lei": [ "Invalid LEI: expected 20 alphanumeric characters (ISO 17442)." ] } } } } } } } } } }, "/v3/travel-rule/test-vasp/inbound/": { "post": { "summary": "Attiva un trasferimento in entrata dal VASP di test di Didit (sandbox)", "description": "Solo per applicazioni sandbox. Il Test VASP di Didit invia alla tua applicazione un trasferimento Travel Rule in entrata, consentendoti di testare end-to-end il lato ricevente di un exchange prima di passare in produzione. Il trasferimento viene registrato e valutato con la stessa logica applicata da un trasferimento reale in entrata proveniente da una rete alla tua rubrica degli indirizzi wallet; pertanto la casella di posta, la decisione e il flusso di proprietà del wallet operano esattamente come in produzione. Nulla esce da Didit. Un'applicazione in produzione riceve 400. Invia nuovamente lo stesso `reference` per recuperare il trasferimento registrato dalla prima chiamata anziché crearne un secondo.", "operationId": "triggerTravelRuleTestVaspInbound", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "trigger_test_vasp_inbound", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTestVaspInboundRequest" }, "example": { "beneficiary_wallet_address": "0xYourSandboxWallet", "scenario": "accept", "amount": "1", "reference": "demo-001" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/test-vasp/inbound/ \\\n -H 'x-api-key: YOUR_SANDBOX_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"beneficiary_wallet_address\":\"0xYourSandboxWallet\",\"scenario\":\"accept\",\"reference\":\"demo-001\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.trigger_test_vasp_inbound(\n beneficiary_wallet_address=\"0xYourSandboxWallet\",\n scenario=\"accept\",\n amount=\"1\",\n reference=\"demo-001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.triggerTestVaspInbound({\n beneficiary_wallet_address: \"0xYourSandboxWallet\",\n scenario: \"accept\",\n amount: \"1\",\n reference: \"demo-001\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.TriggerTestVASPInbound(ctx, didit.TravelRuleTestVASPInboundRequest{\n\tBeneficiaryWalletAddress: \"0xYourSandboxWallet\",\n\tScenario: didit.Some(didit.TravelRuleTestVASPInboundRequestScenario(\"accept\")),\n\tAmount: didit.String(\"1\"),\n\tReference: didit.String(\"demo-001\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleTestVaspInboundRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().triggerTestVaspInbound(TravelRuleTestVaspInboundRequest.builder()\n .beneficiaryWalletAddress(\"0xYourSandboxWallet\")\n .scenario(TravelRuleTestVaspInboundRequest.Scenario.of(\"accept\"))\n .amount(\"1\")\n .reference(\"demo-001\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->triggerTestVaspInbound([\n 'beneficiary_wallet_address' => '0xYourSandboxWallet',\n 'scenario' => 'accept',\n 'amount' => '1',\n 'reference' => 'demo-001',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.trigger_test_vasp_inbound(\n beneficiary_wallet_address: \"0xYourSandboxWallet\",\n scenario: \"accept\",\n amount: \"1\",\n reference: \"demo-001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.TriggerTestVaspInboundAsync(new TravelRuleTestVaspInboundRequest\n{\n BeneficiaryWalletAddress = \"0xYourSandboxWallet\",\n Scenario = new TravelRuleTestVaspInboundRequestScenario(\"accept\"),\n Amount = \"1\",\n Reference = \"demo-001\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Il trasferimento in entrata è stato registrato e deciso. Una ripetizione con lo stesso `reference` restituisce il medesimo corpo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTestVaspInboundResponse" } } } }, "400": { "description": "Corpo non valido, uno `scenario` sconosciuto o non supportato, oppure l'applicazione è in produzione.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Impossibile registrare il trasferimento, ad esempio perché Travel Rule non è abilitata per l'applicazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/travel-rule/widget-session/": { "post": { "summary": "Genera una sessione del widget di titolarità del wallet", "description": "Genera l'URL/token del widget ospitato per la titolarità del wallet. Invia il cliente all'URL restituito per dimostrare il controllo di un wallet (firma del messaggio, test di Satoshi, screenshot o autodichiarazione). In questa versione il widget è disponibile solo per il web: apri l'URL nel browser di sistema o in un custom tab, mai all'interno di una webview dell'SDK mobile.", "operationId": "createTravelRuleWidgetSession", "x-didit-sdk": { "resource": "travel_rule", "method": "create_widget_session", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetSessionCreate" }, "example": { "wallet_address": "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9", "chain": "ETH", "holder_name": "Jane Doe", "vendor_data": "user-042", "transaction_id": "99999999-aaaa-bbbb-cccc-dddddddddddd", "expires_in_minutes": 60 } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget-session/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"wallet_address\":\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\"chain\":\"ETH\",\"holder_name\":\"Jane Doe\",\"transaction_id\":\"99999999-aaaa-bbbb-cccc-dddddddddddd\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.create_widget_session(\n wallet_address=\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n chain=\"ETH\",\n holder_name=\"Jane Doe\",\n vendor_data=\"user-042\",\n transaction_id=\"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n expires_in_minutes=60,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.createWidgetSession({\n wallet_address: \"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n chain: \"ETH\",\n holder_name: \"Jane Doe\",\n vendor_data: \"user-042\",\n transaction_id: \"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n expires_in_minutes: 60,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.CreateWidgetSession(ctx, didit.TravelRuleWidgetSessionCreate{\n\tWalletAddress: didit.String(\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\"),\n\tChain: didit.String(\"ETH\"),\n\tHolderName: didit.String(\"Jane Doe\"),\n\tVendorData: didit.String(\"user-042\"),\n\tTransactionID: didit.String(\"99999999-aaaa-bbbb-cccc-dddddddddddd\"),\n\tExpiresInMinutes: didit.Int(60),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWidgetSessionCreate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().createWidgetSession(TravelRuleWidgetSessionCreate.builder()\n .walletAddress(\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\")\n .chain(\"ETH\")\n .holderName(\"Jane Doe\")\n .vendorData(\"user-042\")\n .transactionId(\"99999999-aaaa-bbbb-cccc-dddddddddddd\")\n .expiresInMinutes(60L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->createWidgetSession([\n 'wallet_address' => '0xd3b62acb76fb27a7f8961ec40fa11746b113aca9',\n 'chain' => 'ETH',\n 'holder_name' => 'Jane Doe',\n 'vendor_data' => 'user-042',\n 'transaction_id' => '99999999-aaaa-bbbb-cccc-dddddddddddd',\n 'expires_in_minutes' => 60,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.create_widget_session(\n wallet_address: \"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n chain: \"ETH\",\n holder_name: \"Jane Doe\",\n vendor_data: \"user-042\",\n transaction_id: \"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n expires_in_minutes: 60\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.CreateWidgetSessionAsync(new TravelRuleWidgetSessionCreate\n{\n WalletAddress = \"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n Chain = \"ETH\",\n HolderName = \"Jane Doe\",\n VendorData = \"user-042\",\n TransactionId = \"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n ExpiresInMinutes = 60,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "La sessione del widget emessa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetSessionResponse" } } } }, "400": { "description": "Corpo non valido: `callback_url` non è un URL http(s) assoluto, `expires_in_minutes` non è compreso tra 5 e 10080, `transaction_id` non è un UUID o un campo supera il limite consentito.", "content": { "application/json": { "examples": { "Invalid callback_url": { "value": { "callback_url": [ "callback_url must be an absolute http(s) URL." ] } } } } } }, "404": { "description": "`transaction_id` non fa riferimento a un trasferimento Travel Rule in questa applicazione." } } } }, "/v3/travel-rule/widget/{token}/": { "get": { "summary": "Recupera contesto del widget di titolarità del wallet", "description": "Endpoint pubblico di lettura associato al token di sessione del widget, nessuna chiave API richiesta. Restituisce il contesto del widget e lo stato di ogni prova, consentendoti di effettuare il polling per rilevarne il completamento; completed_at diventa non nullo una volta verificata una prova. Una prova SATOSHI_TEST può rimanere nello stato PENDING mentre il relativo deposito è visibile on-chain ma non confermato: un job in background la ricontrolla automaticamente e la completa una volta confermato il deposito, quindi non è richiesta alcuna azione da parte del client durante l'attesa. Ciascuna prova include i campi richiesti dal rispettivo metodo: deposit_address, expected_amount e il proprio expires_at per SATOSHI_TEST; challenge per MESSAGE_SIGNING. È preferibile utilizzare il webhook travel_rule.status.updated rispetto al polling quando la sessione è collegata a un trasferimento.", "operationId": "getTravelRuleWidgetContext", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_widget_context", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token di sessione opaco restituito quando la sessione del widget è stata creata.", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/widget/{token}/" } ], "responses": { "200": { "description": "Il contesto del widget e gli stati della prova.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetContext" } } } }, "404": { "description": "Token sconosciuto." }, "410": { "description": "La sessione è scaduta senza essere completata." } } } }, "/v3/travel-rule/widget/{token}/vasps/": { "get": { "summary": "Cerca VASP dal widget del wallet", "description": "Endpoint pubblico di lettura associato al token di sessione del widget, nessuna chiave API richiesta: il selettore VASP del widget per l'utente finale. Stessi parametri di ricerca e filtri di GET /v3/travel-rule/vasps/ per l'applicazione del widget, fornendo solo chi è ciascun VASP e indicando se è raggiungibile.", "operationId": "listTravelRuleWidgetVasps", "x-didit-sdk": { "resource": "travel_rule", "method": "list_widget_vasps", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token di sessione opaco restituito quando la sessione del widget è stata creata.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "Un frammento di nome o alias (senza distinzione tra maiuscole e minuscole), un LEI esatto o un dominio (example.com o un URL al suo interno). I membri della rete Didit corrispondono in base alla loro ragione sociale, al LEI o al dominio della loro email di compliance." }, { "name": "network", "in": "query", "schema": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA", "TRISA" ] }, "description": "Solo le voci di directory attualmente elencate nella directory dei membri di una rete." }, { "name": "jurisdiction", "in": "query", "schema": { "type": "string" }, "description": "Codice paese ISO 3166 alpha-2 o alpha-3. 400 per qualsiasi altra cosa." }, { "name": "reachable", "in": "query", "schema": { "type": "boolean" }, "description": "true: solo i VASP verso cui la tua applicazione ha un percorso disponibile (inclusi i membri della rete Didit). false: solo le voci della directory che la tua applicazione non può raggiungere oggi." }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "directory", "didit" ] }, "description": "Solo voci di directory, o solo membri della rete Didit." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl 'https://verification.didit.me/v3/travel-rule/widget/{token}/vasps/?search=counterparty'" } ], "responses": { "200": { "description": "Risultati impaginati e ordinati per nome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/VaspDirectoryWidgetEntry" } } } } } } }, "400": { "description": "Un filtro non è valido: il corpo indica ciascun campo, ad esempio una rete o un codice paese sconosciuto.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "jurisdiction": [ "Use an ISO 3166 alpha-2 or alpha-3 country code." ], "network": [ "\"SWIFT\" is not a valid choice." ] } } } }, "404": { "description": "Token sconosciuto." }, "410": { "description": "La sessione è scaduta." } } }, "post": { "summary": "Scegli il VASP di controparte nel widget del wallet", "description": "Endpoint pubblico di scrittura associato al token di sessione del widget, nessuna chiave API richiesta: l'utente finale ha scelto il VASP di destinazione che l'individuazione automatica non è riuscita a identificare. È accettato solo per un trasferimento in uscita con stato COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE o NOT_ENOUGH_COUNTERPARTY_DATA. Il trasferimento viene instradato verso quel VASP e inviato di nuovo; l'individuazione automatica non sovrascrive mai la scelta effettuata.", "operationId": "selectTravelRuleWidgetVasp", "x-didit-sdk": { "resource": "travel_rule", "method": "select_widget_vasp", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token di sessione opaco restituito quando la sessione del widget è stata creata.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vasp" ], "properties": { "vasp": { "type": "string", "format": "uuid", "description": "L'`id` di un VASP proveniente da `GET /v3/travel-rule/widget/{token}/vasps/`." } } }, "example": { "vasp": "9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget/{token}/vasps/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"vasp\": \"9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607\"}'" } ], "responses": { "200": { "description": "La scelta è stata registrata e il trasferimento viene inviato di nuovo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "transfer_status": { "type": "string", "description": "Lo stato del trasferimento dopo la selezione." }, "counterparty_vasp": { "type": "string", "description": "Il nome del VASP scelto dall'utente finale." } } }, "example": { "detail": "Counterparty VASP selected; the transfer is being resent.", "transfer_status": "AWAITING_COUNTERPARTY", "counterparty_vasp": "Northwind Exchange" } } } }, "400": { "description": "`vasp` è mancante oppure nessuna voce attiva nella directory ha quell'id.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "vasp": [ "No directory entry has this id." ] } } } }, "404": { "description": "Token sconosciuto." }, "409": { "description": "La sessione del widget non è collegata a un trasferimento Travel Rule, oppure il trasferimento non è in uscita in uno stato che accetta una controparte." }, "410": { "description": "La sessione è scaduta." } } } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/": { "patch": { "summary": "Attiva o disattiva il monitoraggio AML continuo per gli utenti", "description": "Abilita o disabilita il monitoraggio AML continuo a livello di utente. Viene mantenuto esattamente uno screening AML monitorato per utente; per gli utenti privi di screening AML (ad esempio gli utenti importati) ne viene prima creato e sottoposto a screening uno, fatturato come un normale screening AML. Imposta estimate_only per visualizzare in anteprima conteggi e costi senza scrivere. I batch di 20 o meno elementi vengono elaborati inline (200, COMPLETED); i batch più grandi restituiscono 202 e vengono eseguiti in modo asincrono.", "operationId": "toggle_vendor_users_ongoing_monitoring", "x-didit-sdk": { "resource": "users", "method": "set_ongoing_monitoring", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Users" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleRequest" }, "example": { "is_enabled": true, "didit_internal_id_list": [ "5b9a0000-0000-4000-8000-00000000f00d" ] } } } }, "responses": { "200": { "description": "Stima (quando estimate_only) o il processo completato per piccoli lotti elaborati inline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleResult" } } } }, "202": { "description": "I batch più grandi vengono elaborati in modo asincrono; esegui il polling dell'endpoint del job con il job_id restituito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "403": { "description": "Privilegio write:sessions mancante o saldo insufficiente per l'abilitazione (la stima è inclusa nel corpo dell'errore)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.set_ongoing_monitoring(\n is_enabled=True,\n didit_internal_id_list=[\"5b9a0000-0000-4000-8000-00000000f00d\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.setOngoingMonitoring({\n is_enabled: true,\n didit_internal_id_list: [\"5b9a0000-0000-4000-8000-00000000f00d\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.SetOngoingMonitoring(ctx, didit.OngoingMonitoringToggleRequest{\n\tIsEnabled: true,\n\tDiditInternalIDList: didit.Some([]string{\"5b9a0000-0000-4000-8000-00000000f00d\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.OngoingMonitoringToggleRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().setOngoingMonitoring(OngoingMonitoringToggleRequest.builder()\n .isEnabled(true)\n .diditInternalIdList(List.of(\"5b9a0000-0000-4000-8000-00000000f00d\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->setOngoingMonitoring([\n 'is_enabled' => true,\n 'didit_internal_id_list' => ['5b9a0000-0000-4000-8000-00000000f00d'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.set_ongoing_monitoring(\n is_enabled: true,\n didit_internal_id_list: [\"5b9a0000-0000-4000-8000-00000000f00d\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.SetOngoingMonitoringAsync(new OngoingMonitoringToggleRequest\n{\n IsEnabled = true,\n DiditInternalIdList = new string[] { \"5b9a0000-0000-4000-8000-00000000f00d\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/{job_id}/": { "get": { "summary": "Recupera un job di monitoraggio AML continuo", "description": "Avanzamento e contatori per esito di un job di commutazione del monitoraggio. Esegui il polling ogni paio di secondi mentre lo stato è PENDING o PROCESSING.", "operationId": "get_vendor_users_ongoing_monitoring_job", "x-didit-sdk": { "resource": "users", "method": "retrieve_ongoing_monitoring_job", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Users" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID del job di monitoraggio restituito dall'endpoint di attivazione/disattivazione." } ], "responses": { "200": { "description": "Il job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "404": { "description": "Job sconosciuto per questa applicazione." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.retrieve_ongoing_monitoring_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.RetrieveOngoingMonitoringJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->retrieveOngoingMonitoringJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.retrieve_ongoing_monitoring_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.RetrieveOngoingMonitoringJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/": { "patch": { "summary": "Attiva o disattiva il monitoraggio AML continuo per le aziende", "description": "Equivalente a livello aziendale del toggle a livello utente: uno screening AML monitorato per azienda, dando priorità alle aziende prive di screening AML (entità aziendale). Stesso estimate_only, percorso rapido inline e contratto per job asincroni.", "operationId": "toggle_vendor_businesses_ongoing_monitoring", "x-didit-sdk": { "resource": "businesses", "method": "set_ongoing_monitoring", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleRequest" }, "example": { "is_enabled": true, "didit_internal_id_list": [ "b0000000-0000-4000-8000-0000000000b1" ] } } } }, "responses": { "200": { "description": "Stima (quando estimate_only) o il processo completato per piccoli lotti elaborati inline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleResult" } } } }, "202": { "description": "I batch più grandi vengono elaborati in modo asincrono; esegui il polling dell'endpoint del job con il job_id restituito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "403": { "description": "Privilegio write:sessions mancante o saldo insufficiente per l'abilitazione (la stima è inclusa nel corpo dell'errore)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.set_ongoing_monitoring(\n is_enabled=True,\n didit_internal_id_list=[\"b0000000-0000-4000-8000-0000000000b1\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.setOngoingMonitoring({\n is_enabled: true,\n didit_internal_id_list: [\"b0000000-0000-4000-8000-0000000000b1\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.SetOngoingMonitoring(ctx, didit.OngoingMonitoringToggleRequest{\n\tIsEnabled: true,\n\tDiditInternalIDList: didit.Some([]string{\"b0000000-0000-4000-8000-0000000000b1\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.OngoingMonitoringToggleRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().setOngoingMonitoring(OngoingMonitoringToggleRequest.builder()\n .isEnabled(true)\n .diditInternalIdList(List.of(\"b0000000-0000-4000-8000-0000000000b1\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->setOngoingMonitoring([\n 'is_enabled' => true,\n 'didit_internal_id_list' => ['b0000000-0000-4000-8000-0000000000b1'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.set_ongoing_monitoring(\n is_enabled: true,\n didit_internal_id_list: [\"b0000000-0000-4000-8000-0000000000b1\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.SetOngoingMonitoringAsync(new OngoingMonitoringToggleRequest\n{\n IsEnabled = true,\n DiditInternalIdList = new string[] { \"b0000000-0000-4000-8000-0000000000b1\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/{job_id}/": { "get": { "summary": "Recupera un job di monitoraggio AML continuo", "description": "Avanzamento e contatori per esito di un job di commutazione del monitoraggio. Esegui il polling ogni paio di secondi mentre lo stato è PENDING o PROCESSING.", "operationId": "get_vendor_businesses_ongoing_monitoring_job", "x-didit-sdk": { "resource": "businesses", "method": "retrieve_ongoing_monitoring_job", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID del job di monitoraggio restituito dall'endpoint di attivazione/disattivazione." } ], "responses": { "200": { "description": "Il job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "404": { "description": "Job sconosciuto per questa applicazione." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.retrieve_ongoing_monitoring_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.RetrieveOngoingMonitoringJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->retrieveOngoingMonitoringJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.retrieve_ongoing_monitoring_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.RetrieveOngoingMonitoringJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/": { "patch": { "summary": "Attiva o disattiva il monitoraggio AML continuo per le sessioni aziendali", "description": "Toggle a livello di sessione per le verifiche KYB, indirizzato tramite numero di sessione. Per le sessioni senza uno Screening AML, ne viene creato uno e allegato alla sessione stessa. Stesso estimate_only, percorso rapido inline e contratto per job asincroni degli endpoint a livello di utente. Sostituisce il comportamento sincrono legacy che ignorava le sessioni senza Screening AML.", "operationId": "toggle_business_sessions_ongoing_monitoring", "x-didit-sdk": { "resource": "businesses", "method": "set_session_ongoing_monitoring", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_enabled" ], "properties": { "is_enabled": { "type": "boolean", "description": "true per abilitare il monitoraggio, false per disabilitarlo." }, "estimate_only": { "type": "boolean", "default": false, "description": "Se true, restituisce la stima dei costi e non esegue scritture." }, "update_all": { "type": "boolean", "default": false, "description": "Applica a ogni entità dell'applicazione (con ambito limitato dai parametri filter_* se presenti)." }, "filter_search": { "type": "string" }, "filter_status": { "type": "array", "items": { "type": "string" } }, "filter_country": { "type": "string" }, "filter_date_from": { "type": "string", "format": "date" }, "filter_date_to": { "type": "string", "format": "date" }, "session_numbers": { "type": "array", "items": { "type": "string" }, "description": "Numeri delle sessioni aziendali da attivare/disattivare. Obbligatorio a meno che update_all (o l'alias legacy toggle_all) non sia true." }, "toggle_all": { "type": "boolean", "default": false, "description": "Alias legacy di update_all." }, "filter_workflow_id": { "type": "string" } } }, "example": { "is_enabled": true, "session_numbers": [ "1001", "1002" ] } } } }, "responses": { "200": { "description": "Stima (quando estimate_only) o il processo completato per piccoli lotti elaborati inline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleResult" } } } }, "202": { "description": "I batch più grandi vengono elaborati in modo asincrono; esegui il polling dell'endpoint del job con il job_id restituito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "403": { "description": "Privilegio write:sessions mancante o saldo insufficiente per l'abilitazione (la stima è inclusa nel corpo dell'errore)." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.set_session_ongoing_monitoring(\n is_enabled=True,\n session_numbers=[\"1001\", \"1002\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.setSessionOngoingMonitoring({\n is_enabled: true,\n session_numbers: [\"1001\", \"1002\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.SetSessionOngoingMonitoring(ctx, didit.BusinessesSetSessionOngoingMonitoringParams{\n\tIsEnabled: true,\n\tSessionNumbers: didit.Some([]string{\"1001\", \"1002\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BusinessesSetSessionOngoingMonitoringParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().setSessionOngoingMonitoring(BusinessesSetSessionOngoingMonitoringParams.builder()\n .isEnabled(true)\n .sessionNumbers(List.of(\"1001\", \"1002\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->setSessionOngoingMonitoring([\n 'is_enabled' => true,\n 'session_numbers' => ['1001', '1002'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.set_session_ongoing_monitoring(\n is_enabled: true,\n session_numbers: [\"1001\", \"1002\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.SetSessionOngoingMonitoringAsync(new BusinessesSetSessionOngoingMonitoringParams\n{\n IsEnabled = true,\n SessionNumbers = new string[] { \"1001\", \"1002\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/{job_id}/": { "get": { "summary": "Recupera un job di monitoraggio AML continuo", "description": "Avanzamento e contatori per esito di un job di commutazione del monitoraggio. Esegui il polling ogni paio di secondi mentre lo stato è PENDING o PROCESSING.", "operationId": "get_business_sessions_ongoing_monitoring_job", "x-didit-sdk": { "resource": "businesses", "method": "retrieve_session_ongoing_monitoring_job", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID del job di monitoraggio restituito dall'endpoint di attivazione/disattivazione." } ], "responses": { "200": { "description": "Il job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "404": { "description": "Job sconosciuto per questa applicazione." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.retrieve_session_ongoing_monitoring_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.retrieveSessionOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.RetrieveSessionOngoingMonitoringJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().retrieveSessionOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->retrieveSessionOngoingMonitoringJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.retrieve_session_ongoing_monitoring_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.RetrieveSessionOngoingMonitoringJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/": { "get": { "summary": "Elenca i casi", "description": "Elenca i casi per l'applicazione, dal più recente. Supporta filtri, ricerca e ordinamento; vedi i parametri di query. Paginato con `limit`/`offset`.", "operationId": "list_cases", "x-didit-sdk": { "resource": "cases", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Dimensione della pagina. Il valore predefinito è 50." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset in base zero del primo record." }, { "name": "status__in", "in": "query", "schema": { "type": "string" }, "description": "Stati separati da virgole da includere, ad es. OPEN,AWAITING_USER." }, { "name": "priority", "in": "query", "schema": { "type": "string" }, "description": "Priorità separate da virgole da includere." }, { "name": "source__in", "in": "query", "schema": { "type": "string" }, "description": "Origini separate da virgole da includere." }, { "name": "blueprint", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filtra per casi su questo blueprint." }, { "name": "assigned_to", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filtra per casi assegnati a questo utente." }, { "name": "unassigned", "in": "query", "schema": { "type": "boolean" }, "description": "true per i casi non assegnati, false per i casi assegnati." }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "Filtra per casi associati a questo esatto tag." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Trova corrispondenze per title, case_number, tag, nome/UUID/ID esterno del soggetto, UUID della sessione collegata o UUID della transazione collegata." }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Limite inferiore per la data di creazione (incluso)." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Limite superiore per la data di creazione (incluso)." }, { "name": "due_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Limite superiore di due_at." }, { "name": "overdue", "in": "query", "schema": { "type": "boolean" }, "description": "true per restituire solo i casi aperti/in attesa dell'utente scaduti." }, { "name": "ordering", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "due_at", "-due_at" ], "default": "-created_at" }, "description": "Ordinamento. due_at ordina i valori nulli per ultimi." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/?status__in=OPEN,AWAITING_USER&ordering=-due_at' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.ListAutoPaging(ctx, didit.CasesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Elenco impaginato dei casi.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero di righe corrispondenti. Esatto fino a 100, limitato a 100 oltre tale soglia per motivi di prestazioni. Fai affidamento sul fatto che `next` sia null per rilevare l'ultima pagina." }, "next": { "type": "string", "nullable": true, "description": "URL assoluto della pagina successiva, o null." }, "previous": { "type": "string", "nullable": true, "description": "URL assoluto della pagina precedente, o null." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseListItem" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea caso", "description": "Crea un caso associato esattamente a un soggetto (un utente o un'azienda), direttamente o ricavando il soggetto da un link di sessione/transazione allegato. L'origine è sempre `MANUAL` per i casi creati via API.", "operationId": "create_case", "x-didit-sdk": { "resource": "cases", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID di CaseBlueprint. Ometti se non c'è alcun blueprint." }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "default": "MEDIUM" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "object", "description": "Obbligatorio a meno che non venga fornito links; l'unico soggetto del caso.", "properties": { "type": { "type": "string", "enum": [ "user", "business" ] }, "uuid": { "type": "string", "format": "uuid" } } }, "links": { "type": "array", "description": "Sessioni/sessioni aziendali/transazioni da associare al momento della creazione, ad es. [{\"entity_type\": \"transaction\", \"entity_uuid\": \"...\"}]. Quando subject viene omesso, il soggetto viene ricavato dal proprietario del primo collegamento.", "items": { "type": "object" } }, "assigned_to": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID dell'utente da assegnare immediatamente." }, "review_duplicates": { "type": "boolean", "default": false, "description": "Verifica nuovamente le indagini esistenti prima di creare il caso. Se impostato su true, un soggetto con casi esistenti richiede un valore non vuoto per separate_incident_reason. La console abilita sempre questa protezione. L'omissione mantiene il comportamento esistente dell'API." }, "separate_incident_reason": { "type": "string", "maxLength": 1000 }, "source_context": { "$ref": "#/components/schemas/CaseDuplicateCaseFraudSourceContextRequest" } } }, "example": { "title": "Manual - Jane Doe", "blueprint": "b1de0000-0000-4000-8000-000000000002", "priority": "HIGH", "subject": { "type": "user", "uuid": "5b9a0000-0000-4000-8000-00000000f00d" }, "tags": [ "review" ] } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Manual - Jane Doe\", \"blueprint\": \"b1de0000-0000-4000-8000-000000000002\", \"priority\": \"HIGH\", \"subject\": {\"type\": \"user\", \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\"}, \"tags\": [\"review\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.create(\n title=\"Manual - Jane Doe\",\n blueprint=\"b1de0000-0000-4000-8000-000000000002\",\n priority=\"HIGH\",\n tags=[\"review\"],\n subject={\n \"type\": \"user\",\n \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.create({\n title: \"Manual - Jane Doe\",\n blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n priority: \"HIGH\",\n tags: [\"review\"],\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Create(ctx, didit.CasesCreateParams{\n\tTitle: \"Manual - Jane Doe\",\n\tBlueprint: didit.String(\"b1de0000-0000-4000-8000-000000000002\"),\n\tPriority: didit.Some(didit.CasesCreateParamsPriority(\"HIGH\")),\n\tTags: didit.Some([]string{\"review\"}),\n\tSubject: didit.Some(didit.CasesCreateParamsSubject{\n\t\tType: didit.Some(didit.CasesCreateParamsSubjectType(\"user\")),\n\t\tUUID: didit.String(\"5b9a0000-0000-4000-8000-00000000f00d\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().create(CasesCreateParams.builder()\n .title(\"Manual - Jane Doe\")\n .blueprint(\"b1de0000-0000-4000-8000-000000000002\")\n .priority(CasesCreateParams.Priority.of(\"HIGH\"))\n .tags(List.of(\"review\"))\n .subject(CasesCreateParams.Subject.builder()\n .type(CasesCreateParams.Subject.Type.of(\"user\"))\n .uuid(\"5b9a0000-0000-4000-8000-00000000f00d\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->create([\n 'title' => 'Manual - Jane Doe',\n 'blueprint' => 'b1de0000-0000-4000-8000-000000000002',\n 'priority' => 'HIGH',\n 'tags' => ['review'],\n 'subject' => [\n 'type' => 'user',\n 'uuid' => '5b9a0000-0000-4000-8000-00000000f00d',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.create(\n title: \"Manual - Jane Doe\",\n blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n priority: \"HIGH\",\n tags: [\"review\"],\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.CreateAsync(new CasesCreateParams\n{\n Title = \"Manual - Jane Doe\",\n Blueprint = \"b1de0000-0000-4000-8000-000000000002\",\n Priority = new CasesCreateParamsPriority(\"HIGH\"),\n Tags = new string[] { \"review\" },\n Subject = new CasesCreateParamsSubject\n {\n Type = new CasesCreateParamsSubjectType(\"user\"),\n Uuid = \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Caso creato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "400": { "description": "Né subject né links forniti, oppure subject/blueprint/assignee non sono stati trovati.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "La revisione dei duplicati è abilitata ed è stato trovato un caso esistente senza un motivo per un incidente separato. Non è stato creato alcun caso." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/": { "get": { "summary": "Recupera caso", "description": "Recupera un caso con il relativo soggetto, blueprint, note, eventi, collegamenti e checklist.", "operationId": "get_case", "x-didit-sdk": { "resource": "cases", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.retrieve(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.retrieve(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Retrieve(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().retrieve(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->retrieve('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.retrieve(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RetrieveAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Dettaglio del caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "404": { "description": "Caso (o risorsa nidificata) non trovato in questa applicazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna il caso", "description": "Aggiorna il titolo, la priorità, la data di scadenza, i tag o il team di revisione assegnatario del caso. Invia solo i campi che desideri modificare; i campi omessi mantengono il loro valore. `tags` sostituisce l'intero elenco di tag. `team` accetta lo uuid di un team di revisione attivo di questa applicazione (elencali con `GET .../cases/teams/`), oppure null per rimuovere il team. Richiede una chiave API con accesso completo o `write:cases` per un membro della console: una chiave con accesso limitato riceve 403. Registra gli eventi PRIORITY_CHANGED, DUE_DATE_CHANGED, TAG_ADDED, TAG_REMOVED e TEAM_CHANGED a seconda dei casi; una modifica del titolo viene salvata senza un evento nella cronologia. Restituisce il caso aggiornato.", "operationId": "update_case", "x-didit-sdk": { "resource": "cases", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Nuovo titolo del caso." }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "due_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Nuova scadenza. Invia null per rimuoverla." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "L'elenco completo dei tag. Sostituisce i tag attuali." }, "team": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID del team di revisione assegnatario del caso. Deve essere un team attivo di questa applicazione. Invia null per rimuovere l'assegnazione del team." } } }, "examples": { "Change priority and deadline": { "value": { "priority": "HIGH", "due_at": "2026-11-01T00:00:00Z" } }, "Move the case to a team": { "value": { "team": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "Clear the team": { "value": { "team": null } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"priority\": \"HIGH\", \"due_at\": \"2026-08-01T00:00:00Z\"}'" }, { "lang": "curl", "label": "curl (change team)", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"team\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.update(\n \"c1a5e000-0000-4000-8000-000000000001\",\n priority=\"HIGH\",\n due_at=\"2026-11-01T00:00:00Z\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.update(\"c1a5e000-0000-4000-8000-000000000001\", {\n priority: \"HIGH\",\n due_at: \"2026-11-01T00:00:00Z\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Update(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesUpdateParams{\n\tPriority: didit.Some(didit.CasesUpdateParamsPriority(\"HIGH\")),\n\tDueAt: didit.Time(time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC)),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport me.didit.Didit;\nimport me.didit.types.CasesUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().update(\"c1a5e000-0000-4000-8000-000000000001\", CasesUpdateParams.builder()\n .priority(CasesUpdateParams.Priority.of(\"HIGH\"))\n .dueAt(OffsetDateTime.parse(\"2026-11-01T00:00:00Z\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->update('c1a5e000-0000-4000-8000-000000000001', [\n 'priority' => 'HIGH',\n 'due_at' => '2026-11-01T00:00:00Z',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.update(\n \"c1a5e000-0000-4000-8000-000000000001\",\n priority: \"HIGH\",\n due_at: \"2026-11-01T00:00:00Z\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.UpdateAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesUpdateParams\n{\n Priority = new CasesUpdateParamsPriority(\"HIGH\"),\n DueAt = DateTimeOffset.Parse(\"2026-11-01T00:00:00Z\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Caso aggiornato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "400": { "description": "La validazione di un campo non è riuscita. Il body è indicizzato per nome del campo. `team` viene rifiutato se non è un team di revisione attivo di questa applicazione.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Team not active in this application": { "value": { "team": [ "Choose an active team of this application." ] } }, "Invalid priority": { "value": { "priority": [ "\"URGENT\" is not a valid choice." ] } } } } } }, "403": { "description": "La chiave API appartiene a un'altra applicazione, oppure è una chiave con accesso limitato: gli endpoint Cases richiedono una chiave con accesso completo. Un token di un membro della console richiede `write:cases`.", "content": { "application/json": { "examples": { "Restricted API Key": { "summary": "Chiave API con accesso limitato", "value": { "detail": "This API key has no access to this endpoint." } }, "Missing Privilege": { "summary": "Membro della console senza write:cases, o chiave di un'altra applicazione", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Caso non trovato in questa applicazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No Case matches the given query." } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Elimina caso", "description": "Elimina definitivamente un caso. Le relative bozze di report normativi vengono eliminate con esso. Le verifiche collegate, le persone, le aziende e le transazioni non vengono eliminate. Non esiste alcun endpoint per annullare l'eliminazione.\n\nSe il caso contiene un report normativo finalizzato, l'intera richiesta viene rifiutata con `409` e non viene eliminato nulla. Il corpo utilizza `code: in_filed_report` e specifica ciascun report con `uuid`, `report_number`, `report_type` e `case_uuid`. Elimina i report, quindi ripeti la richiesta.", "operationId": "delete_case", "x-didit-sdk": { "resource": "cases", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.delete(\"c1a5e000-0000-4000-8000-000000000001\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Delete(ctx, \"c1a5e000-0000-4000-8000-000000000001\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().delete(\"c1a5e000-0000-4000-8000-000000000001\");" }, { "lang": "php", "label": "PHP", "source": "cases->delete('c1a5e000-0000-4000-8000-000000000001');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.delete(\"c1a5e000-0000-4000-8000-000000000001\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.DeleteAsync(\"c1a5e000-0000-4000-8000-000000000001\");" } ], "responses": { "204": { "description": "Caso eliminato." }, "403": { "description": "La chiave non può eliminare i casi. Richiede una chiave ad accesso completo con `write:cases`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "404": { "description": "Il caso non esiste in questa applicazione o è già stato eliminato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "409": { "description": "Il caso presenta un report regolamentare finalizzato. Non viene eliminato nulla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/assign/": { "post": { "summary": "Assegna o revoca l'assegnazione del caso", "description": "Assegna il caso a un utente oppure revocane l'assegnazione inviando assignee_user_id: null. assignee_email/assignee_name creano automaticamente una riga User quando l'assegnatario non esiste ancora.", "operationId": "assign_case", "x-didit-sdk": { "resource": "cases", "method": "assign", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assignee_user_id" ], "properties": { "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "null per annullare l'assegnazione." }, "assignee_email": { "type": "string", "format": "email", "nullable": true }, "assignee_name": { "type": "string", "nullable": true } } }, "example": { "assignee_user_id": "9a000000-0000-4000-8000-0000000000aa" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/assign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"assignee_user_id\": \"9a000000-0000-4000-8000-0000000000aa\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.assign(\n \"c1a5e000-0000-4000-8000-000000000001\",\n assignee_user_id=\"9a000000-0000-4000-8000-0000000000aa\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.assign(\"c1a5e000-0000-4000-8000-000000000001\", {\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Assign(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesAssignParams{\n\tAssigneeUserID: didit.String(\"9a000000-0000-4000-8000-0000000000aa\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesAssignParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().assign(\"c1a5e000-0000-4000-8000-000000000001\", CasesAssignParams.builder()\n .assigneeUserId(\"9a000000-0000-4000-8000-0000000000aa\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->assign('c1a5e000-0000-4000-8000-000000000001', [\n 'assignee_user_id' => '9a000000-0000-4000-8000-0000000000aa',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.assign(\n \"c1a5e000-0000-4000-8000-000000000001\",\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.AssignAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesAssignParams\n{\n AssigneeUserId = \"9a000000-0000-4000-8000-0000000000aa\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Caso assegnato/non assegnato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/resolve/": { "post": { "summary": "Risolvi il caso", "description": "Risolvi il caso con una delle cinque risoluzioni: FALSE_POSITIVE (nessuna criticità rilevata), VALID_THREAT (criticità confermata), INCONCLUSIVE, REQUIREMENTS_NOT_MET o REQUIREMENTS_SATISFIED. Bloccato con 400 se la checklist del blueprint non è facoltativa e rimangono elementi incompleti, oppure se il blueprint richiede una nota di risoluzione e non ne viene fornita alcuna. Quando il blueprint del caso prevede un passaggio di controllo a quattro occhi (four_eyes_checker_blueprint), la risoluzione viene impostata come provvisoria (case.pending_resolution) e il caso passa al blueprint del verificatore anziché risolversi immediatamente; un responsabile diverso deve chiamare approve o reject-approval. Invia una risoluzione a quattro occhi come membro della console: una risoluzione inviata da una chiave API non ha un maker registrato, quindi approve e reject-approval restituiscono 403 per qualsiasi chiamante. In un blueprint a quattro occhi puoi indicare il membro che deve approvare con `checker`: in tal caso solo quel membro può approvare o rifiutare la risoluzione, e il campo `checker` della risposta ne riporta il nome. Senza `checker`, la risoluzione attende nella coda del blueprint del verificatore. L'invio di `checker` per un blueprint privo di un passaggio di controllo restituisce 400.", "operationId": "resolve_case", "x-didit-sdk": { "resource": "cases", "method": "resolve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resolution" ], "properties": { "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ] }, "note": { "type": "string", "nullable": true, "description": "Obbligatorio quando il blueprint imposta require_resolution_note." }, "checker": { "type": "string", "format": "uuid", "nullable": true, "description": "Solo modelli a quattro occhi. L'uuid utente del membro che deve approvare questa risoluzione (lo stesso id di `assigned_to.uuid` su un caso, o `members[].user_id` su un team di revisione). Il membro deve avere accesso ai casi per questa applicazione e non può essere il responsabile che invia la risoluzione. Omettilo o invia null per lasciare la risoluzione alla coda del controllore." } } }, "examples": { "Resolve": { "value": { "resolution": "FALSE_POSITIVE", "note": "Confirmed legitimate activity after reviewing documents." } }, "Four-eyes blueprint with a named checker": { "value": { "resolution": "VALID_THREAT", "note": "Document tampering confirmed.", "checker": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/resolve/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"resolution\": \"FALSE_POSITIVE\", \"note\": \"Confirmed legitimate activity after reviewing documents.\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.resolve(\n \"c1a5e000-0000-4000-8000-000000000001\",\n resolution=\"FALSE_POSITIVE\",\n note=\"Confirmed legitimate activity after reviewing documents.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.resolve(\"c1a5e000-0000-4000-8000-000000000001\", {\n resolution: \"FALSE_POSITIVE\",\n note: \"Confirmed legitimate activity after reviewing documents.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Resolve(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesResolveParams{\n\tResolution: \"FALSE_POSITIVE\",\n\tNote: didit.String(\"Confirmed legitimate activity after reviewing documents.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesResolveParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().resolve(\"c1a5e000-0000-4000-8000-000000000001\", CasesResolveParams.builder()\n .resolution(CasesResolveParams.Resolution.of(\"FALSE_POSITIVE\"))\n .note(\"Confirmed legitimate activity after reviewing documents.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->resolve('c1a5e000-0000-4000-8000-000000000001', [\n 'resolution' => 'FALSE_POSITIVE',\n 'note' => 'Confirmed legitimate activity after reviewing documents.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.resolve(\n \"c1a5e000-0000-4000-8000-000000000001\",\n resolution: \"FALSE_POSITIVE\",\n note: \"Confirmed legitimate activity after reviewing documents.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ResolveAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesResolveParams\n{\n Resolution = \"FALSE_POSITIVE\",\n Note = \"Confirmed legitimate activity after reviewing documents.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Risolto o in attesa di approvazione a 4 occhi.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "400": { "description": "La risoluzione è stata rifiutata. Gli errori non legati a campi specifici vengono restituiti come elenco di stringhe: una checklist incompleta, una nota obbligatoria mancante o un `checker` che non è stato possibile verificare o che non è un revisore attivo con accesso ai casi per questa applicazione. Gli errori relativi a `checker` sono indicizzati in base al campo: il membro indicato è il responsabile che invia la risoluzione, oppure il modello del caso non prevede un passaggio di verifica (checker).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } ] }, "examples": { "Incomplete checklist": { "value": [ "Case has incomplete checklist items: Verify source of funds" ] }, "Resolution note required": { "value": [ "A resolution note is required to resolve this case." ] }, "Reviewer access could not be verified": { "value": [ "Reviewer access could not be verified. Try again." ] }, "Checker is not an active reviewer": { "value": [ "Choose an active reviewer with case access to this application." ] }, "Checker is the submitting officer": { "value": { "checker": [ "The officer who submitted the resolution cannot be its checker." ] } }, "Policy has no checker step": { "value": { "checker": [ "This review policy has no checker step, so the case resolves directly." ] } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/reopen/": { "post": { "summary": "Riapri il caso", "description": "Riporta un caso in attesa dell'utente o risolto allo stato aperto, azzerando resolution, resolution_notes, resolved_at e resolved_by_email.", "operationId": "reopen_case", "x-didit-sdk": { "resource": "cases", "method": "reopen", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/reopen/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.reopen(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.reopen(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Reopen(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().reopen(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->reopen('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.reopen(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ReopenAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Riapri il caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/request-info/": { "post": { "summary": "Richiedi informazioni (in attesa dell'utente)", "description": "Sposta un caso aperto ad awaiting_user mentre vengono raccolte ulteriori informazioni dall'utente verificato. Restituisce 400 se una risoluzione è attualmente in attesa di approvazione a quattro occhi.", "operationId": "request_case_info", "x-didit-sdk": { "resource": "cases", "method": "request_info", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/request-info/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.request_info(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requestInfo(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RequestInfo(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requestInfo(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requestInfo('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.request_info(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RequestInfoAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Richiedi informazioni (in attesa dell'utente).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/escalate/": { "post": { "summary": "Escala il caso", "description": "Sposta il caso all'escalation_blueprint configurato del suo blueprint. Richiede che il blueprint corrente abbia escalation_enabled e un escalation_blueprint impostato, altrimenti 400.", "operationId": "escalate_case", "x-didit-sdk": { "resource": "cases", "method": "escalate", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/escalate/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.escalate(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.escalate(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Escalate(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().escalate(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->escalate('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.escalate(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.EscalateAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Escala il caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/transfer/": { "post": { "summary": "Trasferisci caso", "description": "Sposta il caso a un blueprint attivo diverso della stessa applicazione. Richiede che il blueprint corrente abbia transfer_enabled, altrimenti 400.", "operationId": "transfer_case", "x-didit-sdk": { "resource": "cases", "method": "transfer", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_blueprint" ], "properties": { "target_blueprint": { "type": "string", "format": "uuid" } } }, "example": { "target_blueprint": "b1de0000-0000-4000-8000-000000000002" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/transfer/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"target_blueprint\": \"b1de0000-0000-4000-8000-000000000002\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.transfer(\n \"c1a5e000-0000-4000-8000-000000000001\",\n target_blueprint=\"b1de0000-0000-4000-8000-000000000002\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.transfer(\"c1a5e000-0000-4000-8000-000000000001\", {\n target_blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Transfer(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesTransferParams{\n\tTargetBlueprint: \"b1de0000-0000-4000-8000-000000000002\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesTransferParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().transfer(\"c1a5e000-0000-4000-8000-000000000001\", CasesTransferParams.builder()\n .targetBlueprint(\"b1de0000-0000-4000-8000-000000000002\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->transfer('c1a5e000-0000-4000-8000-000000000001', [\n 'target_blueprint' => 'b1de0000-0000-4000-8000-000000000002',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.transfer(\n \"c1a5e000-0000-4000-8000-000000000001\",\n target_blueprint: \"b1de0000-0000-4000-8000-000000000002\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.TransferAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesTransferParams\n{\n TargetBlueprint = \"b1de0000-0000-4000-8000-000000000002\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Caso trasferito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/approve/": { "post": { "summary": "Approva la risoluzione predisposta (a 4 occhi)", "description": "Applica una risoluzione predisposta da resolve su un modello a quattro occhi. Il chiamante deve essere un funzionario diverso da quello che l'ha presentata, altrimenti viene restituito 403. Quando la risoluzione indica un verificatore (il `checker` del caso), solo quel membro può approvarla: qualsiasi altro chiamante, inclusa una chiave API, riceve 403.", "operationId": "approve_case_resolution", "x-didit-sdk": { "resource": "cases", "method": "approve_resolution", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/approve/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.approve_resolution(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.approveResolution(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ApproveResolution(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().approveResolution(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->approveResolution('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.approve_resolution(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ApproveResolutionAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Risoluzione applicata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "409": { "description": "Il caso non ha alcuna risoluzione in attesa di approvazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "403": { "description": "Il chiamante non può approvare questa risoluzione: l'ha inviata, il caso non ha un maker registrato o la risoluzione indica un checker diverso. Una chiave API riceve sempre questo 403 quando viene indicato un checker.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Caller submitted the resolution": { "value": { "detail": "The officer who submitted the resolution cannot approve it." } }, "No recorded maker": { "value": { "detail": "Case has no recorded maker for this pending resolution; approve is not permitted." } }, "Caller is not the named checker": { "value": { "detail": "Only the named checker can approve this resolution." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/reject-approval/": { "post": { "summary": "Rifiuta la risoluzione predisposta (doppio controllo)", "description": "Rifiuta una risoluzione predisposta tramite resolve e riporta il caso al blueprint del relativo maker. Il chiamante deve essere un responsabile differente rispetto a chi l'ha inviata, altrimenti 403. Quando la risoluzione specifica un revisore (il `checker` del caso), solo quel membro può rifiutarla: qualsiasi altro chiamante, inclusa una chiave API, riceve 403.", "operationId": "reject_case_resolution", "x-didit-sdk": { "resource": "cases", "method": "reject_resolution", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "nullable": true } } }, "example": { "notes": "Needs a clearer rationale before this can be approved." } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/reject-approval/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"notes\": \"Needs a clearer rationale before this can be approved.\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.reject_resolution(\n \"c1a5e000-0000-4000-8000-000000000001\",\n notes=\"Needs a clearer rationale before this can be approved.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.rejectResolution(\"c1a5e000-0000-4000-8000-000000000001\", {\n notes: \"Needs a clearer rationale before this can be approved.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RejectResolution(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesRejectResolutionParams{\n\tNotes: didit.String(\"Needs a clearer rationale before this can be approved.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesRejectResolutionParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().rejectResolution(\"c1a5e000-0000-4000-8000-000000000001\", CasesRejectResolutionParams.builder()\n .notes(\"Needs a clearer rationale before this can be approved.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->rejectResolution('c1a5e000-0000-4000-8000-000000000001', [\n 'notes' => 'Needs a clearer rationale before this can be approved.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.reject_resolution(\n \"c1a5e000-0000-4000-8000-000000000001\",\n notes: \"Needs a clearer rationale before this can be approved.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RejectResolutionAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesRejectResolutionParams\n{\n Notes = \"Needs a clearer rationale before this can be approved.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Risoluzione rifiutata, caso restituito al blueprint del creatore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "409": { "description": "Il caso non ha alcuna risoluzione in attesa di approvazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "403": { "description": "Il chiamante non può rifiutare questa risoluzione: l'ha inviata, il caso non ha un maker registrato o la risoluzione indica un checker diverso. Una chiave API riceve sempre questo 403 quando viene indicato un checker.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Caller submitted the resolution": { "value": { "detail": "The officer who submitted the resolution cannot reject it." } }, "No recorded maker": { "value": { "detail": "Case has no recorded maker for this pending resolution; reject is not permitted." } }, "Caller is not the named checker": { "value": { "detail": "Only the named checker can reject this resolution." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/entity-actions/": { "post": { "operationId": "apply_case_entity_action", "x-didit-sdk": { "resource": "cases", "method": "apply_entity_action", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionRequest" }, "example": { "client_reference": "e1a00000-0000-4000-8000-000000000001", "action": "add_tags", "tags": [ "source-of-funds-reviewed" ] } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionResult" } } }, "description": "" }, "409": { "description": "Il riferimento appartiene al payload di un'azione diversa." } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Applica un'azione esplicita al soggetto del caso. Fornisci un client_reference univoco per ottenere una ricevuta dell'azione e rendere i nuovi tentativi idempotenti. Il riutilizzo di tale riferimento con un payload diverso restituisce 409. In presenza di un riferimento, esamina receipt.status anche quando lo stato HTTP è 200: FAILED indica che non è stata applicata alcuna azione. Ripetere una richiesta non riuscita non la esegue nuovamente a meno che retry non sia true. L'omissione di client_reference mantiene la risposta legacy.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.apply_entity_action(\n \"11111111-2222-3333-4444-555555555555\",\n client_reference=\"e1a00000-0000-4000-8000-000000000001\",\n action=\"add_tags\",\n tags=[\"source-of-funds-reviewed\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.applyEntityAction(\"11111111-2222-3333-4444-555555555555\", {\n client_reference: \"e1a00000-0000-4000-8000-000000000001\",\n action: \"add_tags\",\n tags: [\"source-of-funds-reviewed\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ApplyEntityAction(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseActionCaseEntityActionRequest{\n\tClientReference: didit.String(\"e1a00000-0000-4000-8000-000000000001\"),\n\tAction: didit.CaseActionActionEnum(\"add_tags\"),\n\tTags: didit.Some([]string{\"source-of-funds-reviewed\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseActionActionEnum;\nimport me.didit.types.CaseActionCaseEntityActionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().applyEntityAction(\"11111111-2222-3333-4444-555555555555\", CaseActionCaseEntityActionRequest.builder()\n .clientReference(\"e1a00000-0000-4000-8000-000000000001\")\n .action(CaseActionActionEnum.of(\"add_tags\"))\n .tags(List.of(\"source-of-funds-reviewed\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->applyEntityAction('11111111-2222-3333-4444-555555555555', [\n 'client_reference' => 'e1a00000-0000-4000-8000-000000000001',\n 'action' => 'add_tags',\n 'tags' => ['source-of-funds-reviewed'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.apply_entity_action(\n \"11111111-2222-3333-4444-555555555555\",\n client_reference: \"e1a00000-0000-4000-8000-000000000001\",\n action: \"add_tags\",\n tags: [\"source-of-funds-reviewed\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ApplyEntityActionAsync(\"11111111-2222-3333-4444-555555555555\", new CaseActionCaseEntityActionRequest\n{\n ClientReference = \"e1a00000-0000-4000-8000-000000000001\",\n Action = \"add_tags\",\n Tags = new string[] { \"source-of-funds-reviewed\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/print/": { "get": { "summary": "Stampa caso (PDF)", "description": "Genera il caso completo (riepilogo, soggetto, stato della checklist, note, sessioni/transazioni collegate, eventi, elenco dei report UIF) in formato PDF e restituisce un URL di download pre-firmato.", "operationId": "print_case", "x-didit-sdk": { "resource": "cases", "method": "print", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/print/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.print(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.print(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Print(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().print(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->print('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.print(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.PrintAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "URL del PDF prefirmato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/": { "get": { "operationId": "list_case_notes", "x-didit-sdk": { "resource": "cases.notes", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "Quale campo utilizzare per ordinare i risultati.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Numero di risultati da restituire per pagina.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "L'indice iniziale da cui restituire i risultati.", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPaginatedCaseNoteList" } } }, "description": "" }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." }, "404": { "description": "Il caso o la nota non sono disponibili per questo chiamante." } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.notes.list(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.notes.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Notes.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesNotesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().notes().list(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->notes->list('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.notes.list(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Notes.ListAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "operationId": "create_case_note", "x-didit-sdk": { "resource": "cases.notes", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNoteCreateRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNoteCreateRequest" }, "example": { "comment": "Proof of address matches the ID document." } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNoteCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } }, "description": "" }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } }, "description": "" }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." }, "404": { "description": "Il caso o la nota non sono disponibili per questo chiamante." }, "409": { "description": "Questo riferimento cliente è già stato utilizzato per un'altra nota o per una nota che è stata eliminata." } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "description": "Aggiungi una nota associata al caso. Un parametro client_reference opzionale fa sì che un nuovo tentativo senza modifiche restituisca la stessa nota senza duplicare attività o notifiche. reply_to deve identificare una nota attiva in questo caso. La risposta include un estratto limitato del genitore senza copiare tale estratto nella risposta salvata.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment=\"Proof of address matches the ID document.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.create(\"11111111-2222-3333-4444-555555555555\", {\n comment: \"Proof of address matches the ID document.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseCollaborationCaseNoteCreateRequest{\n\tComment: \"Proof of address matches the ID document.\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseCollaborationCaseNoteCreateRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().create(\"11111111-2222-3333-4444-555555555555\", CaseCollaborationCaseNoteCreateRequest.builder()\n .comment(\"Proof of address matches the ID document.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->create('11111111-2222-3333-4444-555555555555', [\n 'comment' => 'Proof of address matches the ID document.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment: \"Proof of address matches the ID document.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new CaseCollaborationCaseNoteCreateRequest\n{\n Comment = \"Proof of address matches the ID document.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/{note_uuid}/": { "patch": { "operationId": "root_partial_update", "x-didit-sdk": { "resource": "cases.notes", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "note_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPatchedCaseNoteUpdateRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPatchedCaseNoteUpdateRequest" }, "example": { "is_pinned": true } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPatchedCaseNoteUpdateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } }, "description": "" }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." }, "404": { "description": "Il caso o la nota non sono disponibili per questo chiamante." } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "description": "Fissa o sblocca una nota esistente. Le note fissate appaiono per prime. Le modifiche relative alle note fissate vengono registrate nell'attività del caso e non modificano le prove o le decisioni della fonte.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.update(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n is_pinned=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.update(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n {\n is_pinned: true,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.Update(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", didit.CaseCollaborationPatchedCaseNoteUpdateRequest{\n\tIsPinned: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseCollaborationPatchedCaseNoteUpdateRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().update(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", CaseCollaborationPatchedCaseNoteUpdateRequest.builder()\n .isPinned(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->update('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555', [\n 'is_pinned' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.update(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n is_pinned: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", new CaseCollaborationPatchedCaseNoteUpdateRequest\n{\n IsPinned = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "operationId": "delete_case_note", "x-didit-sdk": { "resource": "cases.notes", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "note_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "204": { "description": "La nota viene eliminata definitivamente. Le risposte rimangono, senza l'estratto del genitore eliminato. Gli allegati vengono eliminati a meno che un'altra nota non li utilizzi ancora." }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." }, "404": { "description": "Il caso o la nota non sono disponibili per questo chiamante." } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Notes.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().notes().delete(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "cases->notes->delete('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Notes.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/presign/": { "post": { "summary": "Carica l'allegato della nota", "description": "Carica un file (JPEG, PNG, WebP, PDF, testo normale o CSV; max 5 MB) da allegare a una nota. Restituisce il valore s3_key da passare nell'array attachments della nota.", "operationId": "upload_case_note_attachment", "x-didit-sdk": { "resource": "cases.notes", "method": "create_attachment_upload", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/notes/presign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'file=@evidence.pdf'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.create_attachment_upload(\n \"c1a5e000-0000-4000-8000-000000000001\",\n file=open(\"document.pdf\", \"rb\"),\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.createAttachmentUpload(\"c1a5e000-0000-4000-8000-000000000001\", {\n file: await fileFromPath(\"document.pdf\"),\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.CreateAttachmentUpload(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesNotesCreateAttachmentUploadParams{\n\tFile: didit.FileFromPath(\"document.pdf\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.CasesNotesCreateAttachmentUploadParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().createAttachmentUpload(\"c1a5e000-0000-4000-8000-000000000001\", CasesNotesCreateAttachmentUploadParams.builder()\n .file(Path.of(\"document.pdf\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->createAttachmentUpload('c1a5e000-0000-4000-8000-000000000001', [\n 'file' => File::fromPath('document.pdf'),\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.create_attachment_upload(\n \"c1a5e000-0000-4000-8000-000000000001\",\n file: Pathname(\"document.pdf\")\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.CreateAttachmentUploadAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesNotesCreateAttachmentUploadParams\n{\n File = FileUpload.FromPath(\"document.pdf\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "File caricato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "s3_key": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "file_size": { "type": "integer" } } } } } }, "400": { "description": "Nessun file, tipo di contenuto non supportato o file superiore a 5 MB.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "Recupera URL dell'allegato della nota", "description": "Genera un nuovo URL di download pre-firmato per un allegato già archiviato in una delle note del caso.", "operationId": "get_case_note_attachment_url", "x-didit-sdk": { "resource": "cases.notes", "method": "retrieve_attachment_url", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." }, { "name": "s3_key", "in": "query", "schema": { "type": "string" }, "description": "Il valore s3_key dell'allegato, come restituito dal caricamento o indicato nella nota.", "required": true } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/notes/presign/?s3_key=case-notes/c1a5e000-0000-4000-8000-000000000001/evidence.pdf' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.retrieve_attachment_url(\n \"c1a5e000-0000-4000-8000-000000000001\",\n s3_key=\"your-s3-key\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.retrieveAttachmentUrl(\"c1a5e000-0000-4000-8000-000000000001\", {\n s3_key: \"your-s3-key\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.RetrieveAttachmentURL(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesNotesRetrieveAttachmentURLParams{\n\tS3Key: \"your-s3-key\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesNotesRetrieveAttachmentUrlParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().retrieveAttachmentUrl(\"c1a5e000-0000-4000-8000-000000000001\", CasesNotesRetrieveAttachmentUrlParams.builder()\n .s3Key(\"your-s3-key\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->retrieveAttachmentUrl('c1a5e000-0000-4000-8000-000000000001', [\n 's3_key' => 'your-s3-key',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.retrieve_attachment_url(\n \"c1a5e000-0000-4000-8000-000000000001\",\n s3_key: \"your-s3-key\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.RetrieveAttachmentUrlAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesNotesRetrieveAttachmentUrlParams\n{\n S3Key = \"your-s3-key\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "URL prefirmato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "s3_key": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" } } } } } }, "404": { "description": "s3_key mancante o non appartenente a questo caso.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/links/": { "get": { "summary": "Elenca i link del caso", "description": "Elenca sessioni, sessioni aziendali e transazioni collegate al caso.", "operationId": "list_case_links", "x-didit-sdk": { "resource": "cases.links", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/links/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.links.list(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.links.list(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Links.List(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().links().list(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->links->list('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.links.list(\"c1a5e000-0000-4000-8000-000000000001\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Links.ListAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Link del caso.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CaseLink" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Aggiungi link al caso", "description": "Collega una sessione, una sessione aziendale o una transazione al caso. Rifiutata con 400 se l'entità appartiene a un soggetto diverso da quello del caso.", "operationId": "create_case_link", "x-didit-sdk": { "resource": "cases.links", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_type", "entity_uuid" ], "properties": { "entity_type": { "type": "string", "enum": [ "session", "business_session", "transaction" ] }, "entity_uuid": { "type": "string", "format": "uuid" } } }, "example": { "entity_type": "transaction", "entity_uuid": "77000000-0000-4000-8000-000000000077" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/links/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"entity_type\": \"transaction\", \"entity_uuid\": \"77000000-0000-4000-8000-000000000077\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.links.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n entity_type=\"transaction\",\n entity_uuid=\"77000000-0000-4000-8000-000000000077\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.links.create(\"c1a5e000-0000-4000-8000-000000000001\", {\n entity_type: \"transaction\",\n entity_uuid: \"77000000-0000-4000-8000-000000000077\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Links.Create(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesLinksCreateParams{\n\tEntityType: \"transaction\",\n\tEntityUUID: \"77000000-0000-4000-8000-000000000077\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesLinksCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().links().create(\"c1a5e000-0000-4000-8000-000000000001\", CasesLinksCreateParams.builder()\n .entityType(CasesLinksCreateParams.EntityType.of(\"transaction\"))\n .entityUuid(\"77000000-0000-4000-8000-000000000077\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->links->create('c1a5e000-0000-4000-8000-000000000001', [\n 'entity_type' => 'transaction',\n 'entity_uuid' => '77000000-0000-4000-8000-000000000077',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.links.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n entity_type: \"transaction\",\n entity_uuid: \"77000000-0000-4000-8000-000000000077\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Links.CreateAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesLinksCreateParams\n{\n EntityType = \"transaction\",\n EntityUuid = \"77000000-0000-4000-8000-000000000077\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Link creato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseLink" } } } }, "400": { "description": "L'entità appartiene a un profilo diverso rispetto al soggetto del caso.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/links/{link_uuid}/": { "delete": { "summary": "Rimuovi il collegamento al caso", "description": "Scollega una sessione, una sessione aziendale o una transazione collegata dal caso.", "operationId": "delete_case_link", "x-didit-sdk": { "resource": "cases.links", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." }, { "name": "link_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11000000-0000-4000-8000-000000000004" }, "description": "UUID del link." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/links/11000000-0000-4000-8000-000000000004/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.links.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"11000000-0000-4000-8000-000000000004\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.links.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"11000000-0000-4000-8000-000000000004\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Links.Delete(ctx, \"c1a5e000-0000-4000-8000-000000000001\", \"11000000-0000-4000-8000-000000000004\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().links().delete(\"c1a5e000-0000-4000-8000-000000000001\", \"11000000-0000-4000-8000-000000000004\");" }, { "lang": "php", "label": "PHP", "source": "cases->links->delete('c1a5e000-0000-4000-8000-000000000001', '11000000-0000-4000-8000-000000000004');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.links.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"11000000-0000-4000-8000-000000000004\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Links.DeleteAsync(\"c1a5e000-0000-4000-8000-000000000001\", \"11000000-0000-4000-8000-000000000004\");" } ], "responses": { "204": { "description": "Link rimosso." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/events/": { "get": { "summary": "Elenca gli eventi del caso", "description": "Cronologia di audit di sola lettura del caso (creazione, cambi di stato, assegnazione, risoluzione, escalation, trasferimenti, modifiche a tag/priorità/data di scadenza, azioni sulle entità e altro).", "operationId": "list_case_events", "x-didit-sdk": { "resource": "cases", "method": "list_events", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Dimensione della pagina." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset in base zero." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/events/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.list_events(\n \"c1a5e000-0000-4000-8000-000000000001\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.listEvents(\"c1a5e000-0000-4000-8000-000000000001\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.ListEventsAutoPaging(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesListEventsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().listEvents(\"c1a5e000-0000-4000-8000-000000000001\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->listEvents('c1a5e000-0000-4000-8000-000000000001') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.list_events(\"c1a5e000-0000-4000-8000-000000000001\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.ListEventsAsync(\"c1a5e000-0000-4000-8000-000000000001\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Eventi impaginati, in ordine dal più recente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero di righe corrispondenti. Esatto fino a 100, limitato a 100 oltre tale soglia per motivi di prestazioni. Fai affidamento sul fatto che `next` sia null per rilevare l'ultima pagina." }, "next": { "type": "string", "nullable": true, "description": "URL assoluto della pagina successiva, o null." }, "previous": { "type": "string", "nullable": true, "description": "URL assoluto della pagina precedente, o null." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseEvent" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/checklist/": { "get": { "summary": "Elenca la checklist del caso", "description": "Elenca gli elementi della checklist del caso, copiati da content_config.checklist.items del blueprint al momento della creazione, ordinati.", "operationId": "list_case_checklist", "x-didit-sdk": { "resource": "cases.checklist", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/checklist/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.checklist.list(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.checklist.list(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Checklist.List(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().checklist().list(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->checklist->list('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.checklist.list(\"c1a5e000-0000-4000-8000-000000000001\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Checklist.ListAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Elementi della checklist.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CaseChecklistItem" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/checklist/{item_uuid}/": { "patch": { "summary": "Attiva o disattiva l'elemento della checklist", "description": "Contrassegna una voce della checklist come completata o incompleta. La risoluzione è bloccata finché una qualsiasi voce rimane incompleta, a meno che il blueprint non contrassegni la checklist come facoltativa.", "operationId": "toggle_case_checklist_item", "x-didit-sdk": { "resource": "cases.checklist", "method": "toggle_item", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." }, { "name": "item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c4ec0000-0000-4000-8000-000000000005" }, "description": "UUID dell'elemento della checklist." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_completed" ], "properties": { "is_completed": { "type": "boolean" } } }, "example": { "is_completed": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/checklist/c4ec0000-0000-4000-8000-000000000005/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"is_completed\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.checklist.toggle_item(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"c4ec0000-0000-4000-8000-000000000005\",\n is_completed=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.checklist.toggleItem(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"c4ec0000-0000-4000-8000-000000000005\",\n {\n is_completed: true,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Checklist.ToggleItem(ctx, \"c1a5e000-0000-4000-8000-000000000001\", \"c4ec0000-0000-4000-8000-000000000005\", didit.CasesChecklistToggleItemParams{\n\tIsCompleted: true,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesChecklistToggleItemParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().checklist().toggleItem(\"c1a5e000-0000-4000-8000-000000000001\", \"c4ec0000-0000-4000-8000-000000000005\", CasesChecklistToggleItemParams.builder()\n .isCompleted(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->checklist->toggleItem('c1a5e000-0000-4000-8000-000000000001', 'c4ec0000-0000-4000-8000-000000000005', [\n 'is_completed' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.checklist.toggle_item(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"c4ec0000-0000-4000-8000-000000000005\",\n is_completed: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Checklist.ToggleItemAsync(\"c1a5e000-0000-4000-8000-000000000001\", \"c4ec0000-0000-4000-8000-000000000005\", new CasesChecklistToggleItemParams\n{\n IsCompleted = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Elemento della checklist aggiornato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseChecklistItem" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/aml/": { "get": { "summary": "Elenca gli hit AML del caso", "description": "Elenca le corrispondenze dello screening AML per il soggetto del caso. Stessa struttura delle corrispondenze restituite da POST /v3/aml/.", "operationId": "list_case_aml_hits", "x-didit-sdk": { "resource": "cases", "method": "list_aml_hits", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/aml/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.list_aml_hits(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.listAmlHits(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ListAMLHits(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().listAmlHits(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->listAmlHits('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.list_aml_hits(\"c1a5e000-0000-4000-8000-000000000001\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ListAmlHitsAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Riscontri AML.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AMLScreening" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/statistics/": { "get": { "summary": "Analisi dei casi", "description": "Analisi aggregate dei casi per l'intervallo di date (il valore predefinito è gli ultimi 30 giorni; massimo 731 giorni). Grafici, tabelle, totali, eventi di assegnazione e conteggi attuali delle code utilizzano gli stessi filtri limitati all'applicazione. I filtri utilizzano i valori correnti dei casi. Le date si applicano a ogni evento di metrica, quindi i casi meno recenti assegnati o risolti durante il periodo rimangono inclusi. La profondità della coda è indipendente dall'intervallo di date. I filtri non validi restituiscono 400; un blueprint o un assegnatario sconosciuto restituisce un risultato vuoto.", "operationId": "get_case_analytics", "x-didit-sdk": { "resource": "cases", "method": "retrieve_statistics", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inizio dell'intervallo (incluso). Il valore predefinito è 30 giorni fa." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Fine dell'intervallo (inclusa). Il valore predefinito è oggi." }, { "name": "blueprint", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filtra in base all'UUID del blueprint corrente." }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filtra in base all'UUID dell'utente revisore attualmente assegnato." }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "description": "Filtra per priorità attuale del caso." }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "description": "Filtra per sorgente di creazione del caso." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "description": "Filtra per stato attuale del caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/statistics/?date_from=2026-06-01&date_to=2026-06-30' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.retrieve_statistics()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.retrieveStatistics();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RetrieveStatistics(ctx, didit.CasesRetrieveStatisticsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().retrieveStatistics();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->retrieveStatistics();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.retrieve_statistics\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RetrieveStatisticsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Payload di analisi.", "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "created": { "type": "integer" }, "reviewed": { "type": "integer" } } } }, "tables": { "type": "object", "properties": { "officer": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Valore della dimensione: email dell'ufficiale, \"blueprint_name:uuid\", origine o stato. \"unassigned\"/\"none\" per le dimensioni mancanti." }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } }, "blueprint": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Valore della dimensione: email dell'ufficiale, \"blueprint_name:uuid\", origine o stato. \"unassigned\"/\"none\" per le dimensioni mancanti." }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } }, "source": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Valore della dimensione: email dell'ufficiale, \"blueprint_name:uuid\", origine o stato. \"unassigned\"/\"none\" per le dimensioni mancanti." }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } }, "status": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Valore della dimensione: email dell'ufficiale, \"blueprint_name:uuid\", origine o stato. \"unassigned\"/\"none\" per le dimensioni mancanti." }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } } } }, "totals": { "type": "object", "properties": { "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } }, "queue": { "type": "object", "description": "Istantanea in tempo reale, non limitata all'intervallo di date.", "properties": { "open": { "type": "integer" }, "overdue": { "type": "integer" } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/bulk/status/": { "post": { "summary": "Aggiornamento massivo dello stato dei casi", "description": "Applica la stessa transizione di stato a più casi in un'unica chiamata: OPEN riapre, AWAITING_USER richiede informazioni, RESOLVED risolve (risoluzione obbligatoria). Ciascun caso viene valutato in modo indipendente; gli errori di gate (checklist incompleta, nota obbligatoria mancante) vengono segnalati per singolo caso senza interrompere il batch.", "operationId": "bulk_update_case_status", "x-didit-sdk": { "resource": "cases", "method": "bulk_update_status", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "case_uuids", "status" ], "properties": { "case_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ], "description": "Obbligatorio quando lo status è RESOLVED." }, "note": { "type": "string", "nullable": true } } }, "example": { "case_uuids": [ "c1a5e000-0000-4000-8000-000000000001" ], "status": "RESOLVED", "resolution": "FALSE_POSITIVE" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/bulk/status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"case_uuids\": [\"c1a5e000-0000-4000-8000-000000000001\"], \"status\": \"RESOLVED\", \"resolution\": \"FALSE_POSITIVE\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.bulk_update_status(\n case_uuids=[\"c1a5e000-0000-4000-8000-000000000001\"],\n status=\"RESOLVED\",\n resolution=\"FALSE_POSITIVE\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.bulkUpdateStatus({\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n status: \"RESOLVED\",\n resolution: \"FALSE_POSITIVE\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.BulkUpdateStatus(ctx, didit.CasesBulkUpdateStatusParams{\n\tCaseUUIDs: []string{\"c1a5e000-0000-4000-8000-000000000001\"},\n\tStatus: \"RESOLVED\",\n\tResolution: didit.Some(didit.CasesBulkUpdateStatusParamsResolution(\"FALSE_POSITIVE\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesBulkUpdateStatusParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().bulkUpdateStatus(CasesBulkUpdateStatusParams.builder()\n .caseUuids(List.of(\"c1a5e000-0000-4000-8000-000000000001\"))\n .status(CasesBulkUpdateStatusParams.Status.of(\"RESOLVED\"))\n .resolution(CasesBulkUpdateStatusParams.Resolution.of(\"FALSE_POSITIVE\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->bulkUpdateStatus([\n 'case_uuids' => ['c1a5e000-0000-4000-8000-000000000001'],\n 'status' => 'RESOLVED',\n 'resolution' => 'FALSE_POSITIVE',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.bulk_update_status(\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n status: \"RESOLVED\",\n resolution: \"FALSE_POSITIVE\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.BulkUpdateStatusAsync(new CasesBulkUpdateStatusParams\n{\n CaseUuids = new string[] { \"c1a5e000-0000-4000-8000-000000000001\" },\n Status = \"RESOLVED\",\n Resolution = new CasesBulkUpdateStatusParamsResolution(\"FALSE_POSITIVE\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Risultati per singolo caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBulkUpdateResult" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/bulk/assign/": { "post": { "summary": "Assegna casi in blocco", "description": "Assegna (o revoca l'assegnazione, con assignee_user_id: null) più casi contemporaneamente. Tutti i casi devono condividere lo stesso blueprint; le discrepanze vengono segnalate per singolo caso senza interrompere il batch.", "operationId": "bulk_assign_cases", "x-didit-sdk": { "resource": "cases", "method": "bulk_assign", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "case_uuids", "assignee_user_id" ], "properties": { "case_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true }, "assignee_email": { "type": "string", "format": "email", "nullable": true }, "assignee_name": { "type": "string", "nullable": true } } }, "example": { "case_uuids": [ "c1a5e000-0000-4000-8000-000000000001" ], "assignee_user_id": "9a000000-0000-4000-8000-0000000000aa" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/bulk/assign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"case_uuids\": [\"c1a5e000-0000-4000-8000-000000000001\"], \"assignee_user_id\": \"9a000000-0000-4000-8000-0000000000aa\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.bulk_assign(\n case_uuids=[\"c1a5e000-0000-4000-8000-000000000001\"],\n assignee_user_id=\"9a000000-0000-4000-8000-0000000000aa\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.bulkAssign({\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.BulkAssign(ctx, didit.CasesBulkAssignParams{\n\tCaseUUIDs: []string{\"c1a5e000-0000-4000-8000-000000000001\"},\n\tAssigneeUserID: didit.String(\"9a000000-0000-4000-8000-0000000000aa\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesBulkAssignParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().bulkAssign(CasesBulkAssignParams.builder()\n .caseUuids(List.of(\"c1a5e000-0000-4000-8000-000000000001\"))\n .assigneeUserId(\"9a000000-0000-4000-8000-0000000000aa\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->bulkAssign([\n 'case_uuids' => ['c1a5e000-0000-4000-8000-000000000001'],\n 'assignee_user_id' => '9a000000-0000-4000-8000-0000000000aa',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.bulk_assign(\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.BulkAssignAsync(new CasesBulkAssignParams\n{\n CaseUuids = new string[] { \"c1a5e000-0000-4000-8000-000000000001\" },\n AssigneeUserId = \"9a000000-0000-4000-8000-0000000000aa\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Risultati per singolo caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBulkUpdateResult" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/": { "get": { "summary": "Elenca i blueprint", "description": "Elenca i blueprint di caso per l'applicazione.", "operationId": "list_case_blueprints", "x-didit-sdk": { "resource": "cases.blueprints", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Dimensione della pagina." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset in base zero." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.blueprints.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.blueprints.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Blueprints.ListAutoPaging(ctx, didit.CasesBlueprintsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().blueprints().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Blueprints.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Elenco impaginato dei blueprint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero di righe corrispondenti, con limite massimo di 100 per motivi di prestazioni." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseBlueprintListItem" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea blueprint", "description": "Crea un blueprint per i casi: impostazioni generali (assegnazione, escalation, trasferimento, principio dei quattro occhi) più content_config, le sei sezioni che compongono la pagina del caso. Imposta publish=false per creare una bozza non pubblicata; la pubblicazione crea la sua prima versione attiva. L'eliminazione di una bozza mai pubblicata la cancella definitivamente.", "operationId": "create_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "assignee_pool" ], "properties": { "name": { "type": "string", "maxLength": 24, "description": "Massimo 24 caratteri, ad es. \"AML investigation\"." }, "description": { "type": "string", "nullable": true }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Elenco di UUID degli utenti. Gli array vuoti vengono rifiutati con \"Seleziona almeno un assegnatario\"." }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ], "default": "MANUAL" }, "max_active_cases": { "type": "integer", "nullable": true, "minimum": 1, "description": "Soglia della modalità automatica: \"meno di N casi di questo modello assegnati\"." }, "escalation_enabled": { "type": "boolean", "default": false }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID del blueprint di destinazione. Non verificato al momento del salvataggio, ma l'azione di escalation fallisce con 400 finché non vengono impostati sia escalation_enabled che escalation_blueprint." }, "transfer_enabled": { "type": "boolean", "default": false }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "L'impostazione di questo campo abilita la revisione a quattro occhi: le risoluzioni su questo blueprint vengono messe in attesa nella coda del blueprint del checker." }, "require_resolution_note": { "type": "boolean", "default": false }, "content_config": { "$ref": "#/components/schemas/CaseContentConfig" }, "is_active": { "type": "boolean", "default": true }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760, "description": "Scadenza predefinita per i casi appena aperti. Le scadenze dei casi esistenti rimangono invariate." }, "publish": { "type": "boolean", "writeOnly": true, "default": true, "description": "Imposta su false per salvare una bozza mai pubblicata. Il record rimane inattivo alla versione 0 fino a quando la bozza non viene esplicitamente pubblicata. L'omissione di questo campo mantiene la creazione immediata per le integrazioni esistenti." } } }, "example": { "name": "AML investigation", "assignee_pool": [ "9a000000-0000-4000-8000-0000000000aa" ], "assignment_method": "AUTOMATIC", "max_active_cases": 15, "require_resolution_note": true, "content_config": { "aml_control": { "enabled": true, "financial": true, "identity": false } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"AML investigation\", \"assignee_pool\": [\"9a000000-0000-4000-8000-0000000000aa\"], \"assignment_method\": \"AUTOMATIC\", \"max_active_cases\": 15, \"require_resolution_note\": true, \"content_config\": {\"aml_control\": {\"enabled\": true, \"financial\": true, \"identity\": false}}}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.create(\n name=\"AML investigation\",\n assignee_pool=[\"9a000000-0000-4000-8000-0000000000aa\"],\n assignment_method=\"AUTOMATIC\",\n max_active_cases=15,\n require_resolution_note=True,\n content_config={\n \"aml_control\": {\n \"enabled\": True,\n \"financial\": True,\n \"identity\": False,\n },\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.create({\n name: \"AML investigation\",\n assignee_pool: [\"9a000000-0000-4000-8000-0000000000aa\"],\n assignment_method: \"AUTOMATIC\",\n max_active_cases: 15,\n require_resolution_note: true,\n content_config: {\n aml_control: {\n enabled: true,\n financial: true,\n identity: false,\n },\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Create(ctx, didit.CasesBlueprintsCreateParams{\n\tName: \"AML investigation\",\n\tAssigneePool: []string{\"9a000000-0000-4000-8000-0000000000aa\"},\n\tAssignmentMethod: didit.Some(didit.CasesBlueprintsCreateParamsAssignmentMethod(\"AUTOMATIC\")),\n\tMaxActiveCases: didit.Int(15),\n\tRequireResolutionNote: didit.Bool(true),\n\tContentConfig: didit.Some(didit.CaseContentConfigParam{\n\t\tAMLControl: didit.Some(didit.CaseContentConfigParamAMLControl{\n\t\t\tEnabled: didit.Bool(true),\n\t\t\tFinancial: didit.Bool(true),\n\t\t\tIdentity: didit.Bool(false),\n\t\t}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseContentConfig;\nimport me.didit.types.CasesBlueprintsCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().create(CasesBlueprintsCreateParams.builder()\n .name(\"AML investigation\")\n .assigneePool(List.of(\"9a000000-0000-4000-8000-0000000000aa\"))\n .assignmentMethod(CasesBlueprintsCreateParams.AssignmentMethod.of(\"AUTOMATIC\"))\n .maxActiveCases(15L)\n .requireResolutionNote(true)\n .contentConfig(CaseContentConfig.builder()\n .amlControl(CaseContentConfig.AmlControl.builder()\n .enabled(true)\n .financial(true)\n .identity(false)\n .build())\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->create([\n 'name' => 'AML investigation',\n 'assignee_pool' => ['9a000000-0000-4000-8000-0000000000aa'],\n 'assignment_method' => 'AUTOMATIC',\n 'max_active_cases' => 15,\n 'require_resolution_note' => true,\n 'content_config' => [\n 'aml_control' => [\n 'enabled' => true,\n 'financial' => true,\n 'identity' => false,\n ],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.create(\n name: \"AML investigation\",\n assignee_pool: [\"9a000000-0000-4000-8000-0000000000aa\"],\n assignment_method: \"AUTOMATIC\",\n max_active_cases: 15,\n require_resolution_note: true,\n content_config: {\n aml_control: {\n enabled: true,\n financial: true,\n identity: false,\n },\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.CreateAsync(new CasesBlueprintsCreateParams\n{\n Name = \"AML investigation\",\n AssigneePool = new string[] { \"9a000000-0000-4000-8000-0000000000aa\" },\n AssignmentMethod = new CasesBlueprintsCreateParamsAssignmentMethod(\"AUTOMATIC\"),\n MaxActiveCases = 15,\n RequireResolutionNote = true,\n ContentConfig = new CaseContentConfig\n {\n AmlControl = new CaseContentConfigAmlControl\n {\n Enabled = true,\n Financial = true,\n Identity = false,\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Blueprint creato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintDetail" } } } }, "400": { "description": "Nome superiore a 24 caratteri, assignee_pool vuoto o blueprint con riferimento incrociato (escalation/checker) non trovato.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/": { "get": { "summary": "Recupera progetto", "description": "Recupera un blueprint, incluse le origini di creazione collegate (configurazione AML, regole sulle transazioni, nodi del workflow) e i blueprint che inoltrano a esso.", "operationId": "get_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "blueprint_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b1de0000-0000-4000-8000-000000000002" }, "description": "UUID del blueprint." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/b1de0000-0000-4000-8000-000000000002/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.retrieve(\n \"b1de0000-0000-4000-8000-000000000002\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.retrieve(\"b1de0000-0000-4000-8000-000000000002\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Retrieve(ctx, \"b1de0000-0000-4000-8000-000000000002\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().retrieve(\"b1de0000-0000-4000-8000-000000000002\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->retrieve('b1de0000-0000-4000-8000-000000000002');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.retrieve(\"b1de0000-0000-4000-8000-000000000002\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.RetrieveAsync(\"b1de0000-0000-4000-8000-000000000002\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Dettaglio del blueprint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna il blueprint", "description": "Aggiorna parzialmente le impostazioni generali o content_config di un blueprint.", "operationId": "update_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "blueprint_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b1de0000-0000-4000-8000-000000000002" }, "description": "UUID del blueprint." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 24, "description": "Massimo 24 caratteri, ad es. \"AML investigation\"." }, "description": { "type": "string", "nullable": true }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Elenco di UUID degli utenti. Gli array vuoti vengono rifiutati con \"Seleziona almeno un assegnatario\"." }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "max_active_cases": { "type": "integer", "nullable": true, "minimum": 1, "description": "Soglia della modalità automatica: \"meno di N casi di questo modello assegnati\"." }, "escalation_enabled": { "type": "boolean" }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID del blueprint di destinazione. Non verificato al momento del salvataggio, ma l'azione di escalation fallisce con 400 finché non vengono impostati sia escalation_enabled che escalation_blueprint." }, "transfer_enabled": { "type": "boolean" }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "L'impostazione di questo campo abilita la revisione a quattro occhi: le risoluzioni su questo blueprint vengono messe in attesa nella coda del blueprint del checker." }, "require_resolution_note": { "type": "boolean" }, "content_config": { "$ref": "#/components/schemas/CaseContentConfig" }, "is_active": { "type": "boolean" }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760, "description": "Scadenza predefinita per i casi appena aperti. Le scadenze dei casi esistenti rimangono invariate." }, "expected_version": { "type": "integer", "minimum": 1, "description": "La versione aperta dall'editor. Una versione non aggiornata restituisce 409 senza modificare la policy di revisione." } } }, "example": { "transfer_enabled": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/b1de0000-0000-4000-8000-000000000002/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"transfer_enabled\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.update(\n \"b1de0000-0000-4000-8000-000000000002\",\n transfer_enabled=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.update(\"b1de0000-0000-4000-8000-000000000002\", {\n transfer_enabled: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Update(ctx, \"b1de0000-0000-4000-8000-000000000002\", didit.CasesBlueprintsUpdateParams{\n\tTransferEnabled: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesBlueprintsUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().update(\"b1de0000-0000-4000-8000-000000000002\", CasesBlueprintsUpdateParams.builder()\n .transferEnabled(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->update('b1de0000-0000-4000-8000-000000000002', [\n 'transfer_enabled' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.update(\n \"b1de0000-0000-4000-8000-000000000002\",\n transfer_enabled: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.UpdateAsync(\"b1de0000-0000-4000-8000-000000000002\", new CasesBlueprintsUpdateParams\n{\n TransferEnabled = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Blueprint aggiornato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintDetail" } } } }, "409": { "description": "La policy di revisione è cambiata rispetto a expected_version. Esamina la versione più recente prima di riprovare." } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Elimina il blueprint", "description": "Elimina un blueprint. L'eliminazione ha sempre esito positivo e non tocca i casi del blueprint: i casi esistenti mantengono il riferimento al blueprint e le relative impostazioni continuano ad applicarsi a essi. Un blueprint eliminato non compare più negli elenchi dei blueprint e non può più essere scelto come destinazione di trasferimento; se un blueprint maker viene eliminato mentre una risoluzione è in attesa dell'approvazione 4-eyes, una risoluzione rifiutata lascia il caso sul blueprint checker.", "operationId": "delete_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "blueprint_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b1de0000-0000-4000-8000-000000000002" }, "description": "UUID del blueprint." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/b1de0000-0000-4000-8000-000000000002/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.blueprints.delete(\n \"b1de0000-0000-4000-8000-000000000002\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.blueprints.delete(\"b1de0000-0000-4000-8000-000000000002\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Blueprints.Delete(ctx, \"b1de0000-0000-4000-8000-000000000002\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().blueprints().delete(\"b1de0000-0000-4000-8000-000000000002\");" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->delete('b1de0000-0000-4000-8000-000000000002');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.delete(\"b1de0000-0000-4000-8000-000000000002\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Blueprints.DeleteAsync(\"b1de0000-0000-4000-8000-000000000002\");" } ], "responses": { "204": { "description": "Blueprint eliminato." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/presets/": { "get": { "summary": "Elenca i preset di blueprint", "description": "Elenca i quattro preset integrati (Screening hit, AML investigation, Suspicious activity, KYC review) con la loro content_config e se ciascuno è già installato in questa applicazione.", "operationId": "list_case_blueprint_presets", "x-didit-sdk": { "resource": "cases.blueprints", "method": "list_presets", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/presets/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.list_presets()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.listPresets();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.ListPresets(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().listPresets();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->listPresets();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.list_presets\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.ListPresetsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Catalogo predefinito.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "preset_key": { "type": "string", "enum": [ "screening_hit", "aml_investigation", "suspicious_activity", "kyc" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "content_config": { "$ref": "#/components/schemas/CaseContentConfig" }, "installed": { "type": "boolean" } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/presets/install/": { "post": { "summary": "Installa preset del blueprint", "description": "Copia uno o più preset nell'applicazione come blueprint modificabili. Idempotente per preset_key; ometti preset_keys per installare tutti i preset non ancora installati.", "operationId": "install_case_blueprint_presets", "x-didit-sdk": { "resource": "cases.blueprints", "method": "install_presets", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "preset_keys": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Sottoinsieme di screening_hit, aml_investigation, suspicious_activity, kyc. Ometti per installarli tutti." } } }, "example": { "preset_keys": [ "aml_investigation", "kyc" ] } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/presets/install/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"preset_keys\": [\"aml_investigation\", \"kyc\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.install_presets(\n preset_keys=[\"aml_investigation\", \"kyc\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.installPresets({\n preset_keys: [\"aml_investigation\", \"kyc\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.InstallPresets(ctx, didit.CasesBlueprintsInstallPresetsParams{\n\tPresetKeys: didit.Some([]string{\"aml_investigation\", \"kyc\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesBlueprintsInstallPresetsParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().installPresets(CasesBlueprintsInstallPresetsParams.builder()\n .presetKeys(List.of(\"aml_investigation\", \"kyc\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->installPresets([\n 'preset_keys' => ['aml_investigation', 'kyc'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.install_presets(preset_keys: [\"aml_investigation\", \"kyc\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.InstallPresetsAsync(new CasesBlueprintsInstallPresetsParams\n{\n PresetKeys = new string[] { \"aml_investigation\", \"kyc\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Uno o più preset installati.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintPresetInstallResult" } } } }, "200": { "description": "Nessuna nuova preimpostazione da installare (tutte le preimpostazioni richieste esistono già).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintPresetInstallResult" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/report-templates/": { "get": { "summary": "Elenca i modelli di report", "description": "Elenca i modelli di report FIU per l'applicazione.", "operationId": "list_report_templates", "x-didit-sdk": { "resource": "report_templates", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Dimensione della pagina." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset in base zero." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.report_templates.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.reportTemplates.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.ReportTemplates.ListAutoPaging(ctx, didit.ReportTemplatesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.reportTemplates().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.report_templates.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.ReportTemplates.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Modelli impaginati.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero di righe corrispondenti, con limite massimo di 100 per motivi di prestazioni." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea modello di report", "description": "Crea un modello di intestazione goAML riutilizzabile per giurisdizione e per tipo di report. Rifiutato con 400 se uno qualsiasi dei campi obbligatori a livello di modello (rentity_id, submission_code, currency_code_local) manca da field_config; un modello non valido non può essere salvato né utilizzato per creare un report. I campi di intestazione specifici del deposito (action, submission_date, transactions) vengono invece verificati al momento della convalida/finalizzazione del report.", "operationId": "create_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "jurisdiction", "report_type" ], "properties": { "name": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Codice paese ISO 3166-1 alpha-2, convertito in maiuscolo al momento del salvataggio." }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "field_config": { "type": "object", "description": "Impostazioni predefinite riutilizzabili per l'intestazione goAML. Campi obbligatori a livello di modello: rentity_id, submission_code e currency_code_local (3 lettere). Facoltativi: enabled_fields (quali blocchi di report opzionali includere) oltre ai valori predefiniti per reporting_person, location, reason e action. I campi di intestazione specifici per ogni invio (action, submission_date, transactions, jurisdiction) vengono verificati al momento della validazione o della finalizzazione del report, non sul modello." } } }, "example": { "name": "US SAR default", "jurisdiction": "US", "report_type": "SAR", "field_config": { "rentity_id": "FIU-US-00123", "submission_code": "E", "currency_code_local": "USD" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"US SAR default\", \"jurisdiction\": \"US\", \"report_type\": \"SAR\", \"field_config\": {\"rentity_id\": \"FIU-US-00123\", \"submission_code\": \"E\", \"currency_code_local\": \"USD\"}}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.report_templates.create(\n name=\"US SAR default\",\n jurisdiction=\"US\",\n report_type=\"SAR\",\n field_config={\"rentity_id\": \"FIU-US-00123\", \"submission_code\": \"E\", \"currency_code_local\": \"USD\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.reportTemplates.create({\n name: \"US SAR default\",\n jurisdiction: \"US\",\n report_type: \"SAR\",\n field_config: { rentity_id: \"FIU-US-00123\", submission_code: \"E\", currency_code_local: \"USD\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.ReportTemplates.Create(ctx, didit.ReportTemplatesCreateParams{\n\tName: \"US SAR default\",\n\tJurisdiction: \"US\",\n\tReportType: \"SAR\",\n\tFieldConfig: didit.Some(map[string]any{\"rentity_id\": \"FIU-US-00123\", \"submission_code\": \"E\", \"currency_code_local\": \"USD\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.ReportTemplatesCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.reportTemplates().create(ReportTemplatesCreateParams.builder()\n .name(\"US SAR default\")\n .jurisdiction(\"US\")\n .reportType(ReportTemplatesCreateParams.ReportType.of(\"SAR\"))\n .fieldConfig(Map.of(\"rentity_id\", \"FIU-US-00123\", \"submission_code\", \"E\", \"currency_code_local\", \"USD\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->create([\n 'name' => 'US SAR default',\n 'jurisdiction' => 'US',\n 'report_type' => 'SAR',\n 'field_config' => ['rentity_id' => 'FIU-US-00123', 'submission_code' => 'E', 'currency_code_local' => 'USD'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.report_templates.create(\n name: \"US SAR default\",\n jurisdiction: \"US\",\n report_type: \"SAR\",\n field_config: { rentity_id: \"FIU-US-00123\", submission_code: \"E\", currency_code_local: \"USD\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.ReportTemplates.CreateAsync(new ReportTemplatesCreateParams\n{\n Name = \"US SAR default\",\n Jurisdiction = \"US\",\n ReportType = \"SAR\",\n FieldConfig = new Dictionary { [\"rentity_id\"] = \"FIU-US-00123\", [\"submission_code\"] = \"E\", [\"currency_code_local\"] = \"USD\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Modello creato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } }, "400": { "description": "Giurisdizione non riconosciuta, oppure field_config non supera la validazione dei campi obbligatori.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/report-templates/{template_uuid}/": { "get": { "summary": "Recupera modello di report", "description": "Recupera un modello di report.", "operationId": "get_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "template_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7ec00000-0000-4000-8000-000000000006" }, "description": "UUID del modello di report." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/7ec00000-0000-4000-8000-000000000006/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.report_templates.retrieve(\n \"7ec00000-0000-4000-8000-000000000006\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.reportTemplates.retrieve(\"7ec00000-0000-4000-8000-000000000006\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.ReportTemplates.Retrieve(ctx, \"7ec00000-0000-4000-8000-000000000006\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.reportTemplates().retrieve(\"7ec00000-0000-4000-8000-000000000006\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->retrieve('7ec00000-0000-4000-8000-000000000006');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.report_templates.retrieve(\"7ec00000-0000-4000-8000-000000000006\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.ReportTemplates.RetrieveAsync(\"7ec00000-0000-4000-8000-000000000006\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Dettaglio del modello.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna il modello di report", "description": "Aggiorna parzialmente un modello di report. Convalida nuovamente i campi goAML obbligatori al salvataggio.", "operationId": "update_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "template_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7ec00000-0000-4000-8000-000000000006" }, "description": "UUID del modello di report." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Codice paese ISO 3166-1 alpha-2, convertito in maiuscolo al momento del salvataggio." }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "field_config": { "type": "object", "description": "Impostazioni predefinite riutilizzabili per l'intestazione goAML. Campi obbligatori a livello di modello: rentity_id, submission_code e currency_code_local (3 lettere). Facoltativi: enabled_fields (quali blocchi di report opzionali includere) oltre ai valori predefiniti per reporting_person, location, reason e action. I campi di intestazione specifici per ogni invio (action, submission_date, transactions, jurisdiction) vengono verificati al momento della validazione o della finalizzazione del report, non sul modello." } } }, "example": { "field_config": { "rentity_id": "FIU-US-00124" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/7ec00000-0000-4000-8000-000000000006/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"field_config\": {\"rentity_id\": \"FIU-US-00124\"}}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.report_templates.update(\n \"7ec00000-0000-4000-8000-000000000006\",\n field_config={\"rentity_id\": \"FIU-US-00124\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.reportTemplates.update(\"7ec00000-0000-4000-8000-000000000006\", {\n field_config: { rentity_id: \"FIU-US-00124\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.ReportTemplates.Update(ctx, \"7ec00000-0000-4000-8000-000000000006\", didit.ReportTemplatesUpdateParams{\n\tFieldConfig: didit.Some(map[string]any{\"rentity_id\": \"FIU-US-00124\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.ReportTemplatesUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.reportTemplates().update(\"7ec00000-0000-4000-8000-000000000006\", ReportTemplatesUpdateParams.builder()\n .fieldConfig(Map.of(\"rentity_id\", \"FIU-US-00124\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->update('7ec00000-0000-4000-8000-000000000006', [\n 'field_config' => ['rentity_id' => 'FIU-US-00124'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.report_templates.update(\n \"7ec00000-0000-4000-8000-000000000006\",\n field_config: { rentity_id: \"FIU-US-00124\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.ReportTemplates.UpdateAsync(\"7ec00000-0000-4000-8000-000000000006\", new ReportTemplatesUpdateParams\n{\n FieldConfig = new Dictionary { [\"rentity_id\"] = \"FIU-US-00124\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Modello aggiornato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Elimina modello di report", "description": "Elimina un modello di report. I report già creati a partire da esso rimangono invariati.", "operationId": "delete_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "template_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7ec00000-0000-4000-8000-000000000006" }, "description": "UUID del modello di report." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/7ec00000-0000-4000-8000-000000000006/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.report_templates.delete(\n \"7ec00000-0000-4000-8000-000000000006\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.reportTemplates.delete(\"7ec00000-0000-4000-8000-000000000006\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.ReportTemplates.Delete(ctx, \"7ec00000-0000-4000-8000-000000000006\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.reportTemplates().delete(\"7ec00000-0000-4000-8000-000000000006\");" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->delete('7ec00000-0000-4000-8000-000000000006');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.report_templates.delete(\"7ec00000-0000-4000-8000-000000000006\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.ReportTemplates.DeleteAsync(\"7ec00000-0000-4000-8000-000000000006\");" } ], "responses": { "204": { "description": "Modello eliminato." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/regulatory-reports/": { "get": { "summary": "Elenca i report per un caso", "description": "Elenca i report FIU generati per il caso.", "operationId": "list_case_regulatory_reports", "x-didit-sdk": { "resource": "cases.regulatory_reports", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Dimensione della pagina." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset in base zero." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.regulatory_reports.list(\n \"c1a5e000-0000-4000-8000-000000000001\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.regulatoryReports.list(\"c1a5e000-0000-4000-8000-000000000001\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.RegulatoryReports.ListAutoPaging(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesRegulatoryReportsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().regulatoryReports().list(\"c1a5e000-0000-4000-8000-000000000001\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->regulatoryReports->list('c1a5e000-0000-4000-8000-000000000001') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.regulatory_reports.list(\"c1a5e000-0000-4000-8000-000000000001\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.RegulatoryReports.ListAsync(\"c1a5e000-0000-4000-8000-000000000001\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Report impaginati per il caso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportList" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea report da caso", "description": "Crea una bozza di report FIU per il caso: stato DRAFT, precompilata automaticamente a partire dal modello opzionale e dal soggetto del caso, dalle transazioni collegate e dalla narrazione. Convalida e poi finalizza per generare l'XML goAML e il PDF.", "operationId": "create_case_regulatory_report", "x-didit-sdk": { "resource": "cases.regulatory_reports", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "UUID del caso." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ], "description": "Obbligatorio a meno che non sia fornito un modello; in tal caso, viene utilizzato il report_type del modello." }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Obbligatorio a meno che non sia fornito un modello." }, "template": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID del modello di report; il suo field_config inizializza la bozza prima che vengano uniti i dati derivati dal caso." }, "transactions": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true, "description": "Transazioni da associare; per impostazione predefinita coincide con le transazioni collegate al caso." }, "rentity_id": { "type": "string", "nullable": true }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ], "default": "E" }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "template": "7ec00000-0000-4000-8000-000000000006" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"template\": \"7ec00000-0000-4000-8000-000000000006\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.regulatory_reports.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n template=\"7ec00000-0000-4000-8000-000000000006\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.regulatoryReports.create(\"c1a5e000-0000-4000-8000-000000000001\", {\n template: \"7ec00000-0000-4000-8000-000000000006\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RegulatoryReports.Create(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesRegulatoryReportsCreateParams{\n\tTemplate: didit.String(\"7ec00000-0000-4000-8000-000000000006\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesRegulatoryReportsCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().regulatoryReports().create(\"c1a5e000-0000-4000-8000-000000000001\", CasesRegulatoryReportsCreateParams.builder()\n .template(\"7ec00000-0000-4000-8000-000000000006\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->regulatoryReports->create('c1a5e000-0000-4000-8000-000000000001', [\n 'template' => '7ec00000-0000-4000-8000-000000000006',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.regulatory_reports.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n template: \"7ec00000-0000-4000-8000-000000000006\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RegulatoryReports.CreateAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesRegulatoryReportsCreateParams\n{\n Template = \"7ec00000-0000-4000-8000-000000000006\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Bozza di report creata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "400": { "description": "Il modello di riferimento non è stato trovato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/": { "get": { "summary": "Elenca i report", "description": "Elenco dei report UIF/FIU a livello di applicazione, opzionalmente filtrato per status, report_type o case.", "operationId": "list_regulatory_reports", "x-didit-sdk": { "resource": "regulatory_reports", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "Dimensione della pagina." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset in base zero." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "DRAFT", "VALIDATED", "FINALIZED" ] }, "description": "Filtra per stato." }, { "name": "report_type", "in": "query", "schema": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "description": "Filtra per tipo di report." }, { "name": "case", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filtra per report su questo caso." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.regulatory_reports.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.regulatoryReports.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.RegulatoryReports.ListAutoPaging(ctx, didit.RegulatoryReportsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.regulatoryReports().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.regulatory_reports.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.RegulatoryReports.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Report impaginati nell'intera applicazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportList" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea report autonomo", "description": "Crea una bozza di report FIU dalla pagina autonoma Report: sia il caso sia il modello sono obbligatori (a differenza della creazione con ambito caso, in cui il modello può essere omesso).", "operationId": "create_standalone_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "case", "template" ], "properties": { "case": { "type": "string", "format": "uuid" }, "template": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ], "description": "Obbligatorio a meno che non sia fornito un modello; in tal caso, viene utilizzato il report_type del modello." }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Obbligatorio a meno che non sia fornito un modello." }, "transactions": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true, "description": "Transazioni da associare; per impostazione predefinita coincide con le transazioni collegate al caso." }, "rentity_id": { "type": "string", "nullable": true }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ], "default": "E" }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "case": "c1a5e000-0000-4000-8000-000000000001", "template": "7ec00000-0000-4000-8000-000000000006" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"case\": \"c1a5e000-0000-4000-8000-000000000001\", \"template\": \"7ec00000-0000-4000-8000-000000000006\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.create(\n case=\"c1a5e000-0000-4000-8000-000000000001\",\n template=\"7ec00000-0000-4000-8000-000000000006\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.create({\n case: \"c1a5e000-0000-4000-8000-000000000001\",\n template: \"7ec00000-0000-4000-8000-000000000006\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Create(ctx, didit.RegulatoryReportsCreateParams{\n\tCase: \"c1a5e000-0000-4000-8000-000000000001\",\n\tTemplate: \"7ec00000-0000-4000-8000-000000000006\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RegulatoryReportsCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().create(RegulatoryReportsCreateParams.builder()\n .case_(\"c1a5e000-0000-4000-8000-000000000001\")\n .template(\"7ec00000-0000-4000-8000-000000000006\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->create([\n 'case' => 'c1a5e000-0000-4000-8000-000000000001',\n 'template' => '7ec00000-0000-4000-8000-000000000006',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.create(\n case: \"c1a5e000-0000-4000-8000-000000000001\",\n template: \"7ec00000-0000-4000-8000-000000000006\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.CreateAsync(new RegulatoryReportsCreateParams\n{\n Case = \"c1a5e000-0000-4000-8000-000000000001\",\n Template = \"7ec00000-0000-4000-8000-000000000006\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Bozza di report creata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "400": { "description": "Il modello di riferimento non è stato trovato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/": { "get": { "summary": "Recupera report", "description": "Recupera un report normativo.", "operationId": "get_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID del report." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.retrieve(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.retrieve(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Retrieve(ctx, \"5ec00000-0000-4000-8000-000000000007\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().retrieve(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->retrieve('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.retrieve(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.RetrieveAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Dettaglio del report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna il report", "description": "Modifica i campi di un report in bozza o validato. I report finalizzati non possono essere modificati (409).", "operationId": "update_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID del report." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2 }, "rentity_id": { "type": "string", "nullable": true }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ], "default": "E" }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "rentity_id": "FIU-US-00123", "currency_code_local": "USD" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"rentity_id\": \"FIU-US-00123\", \"currency_code_local\": \"USD\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.update(\n \"5ec00000-0000-4000-8000-000000000007\",\n rentity_id=\"FIU-US-00123\",\n currency_code_local=\"USD\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.update(\"5ec00000-0000-4000-8000-000000000007\", {\n rentity_id: \"FIU-US-00123\",\n currency_code_local: \"USD\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Update(ctx, \"5ec00000-0000-4000-8000-000000000007\", didit.RegulatoryReportsUpdateParams{\n\tRentityID: didit.String(\"FIU-US-00123\"),\n\tCurrencyCodeLocal: didit.String(\"USD\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RegulatoryReportsUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().update(\"5ec00000-0000-4000-8000-000000000007\", RegulatoryReportsUpdateParams.builder()\n .rentityId(\"FIU-US-00123\")\n .currencyCodeLocal(\"USD\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->update('5ec00000-0000-4000-8000-000000000007', [\n 'rentity_id' => 'FIU-US-00123',\n 'currency_code_local' => 'USD',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.update(\n \"5ec00000-0000-4000-8000-000000000007\",\n rentity_id: \"FIU-US-00123\",\n currency_code_local: \"USD\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.UpdateAsync(\"5ec00000-0000-4000-8000-000000000007\", new RegulatoryReportsUpdateParams\n{\n RentityId = \"FIU-US-00123\",\n CurrencyCodeLocal = \"USD\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Report aggiornato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "409": { "description": "Il report è già finalizzato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Elimina report", "description": "Elimina definitivamente un report normativo. Il report, la descrizione e le motivazioni copiate, i collegamenti alle transazioni e i file goAML XML e PDF generati vengono cancellati, inclusa ogni versione memorizzata di tali file. Il report scompare dagli elenchi e gli URL di download smettono di funzionare. Gli altri record, inclusi il caso, le transazioni, le persone e le aziende, non vengono eliminati. L'operazione non può essere annullata.\n\nUn report in bozza o convalidato può essere eliminato senza un corpo della richiesta. L'eliminazione di un report finalizzato richiede `confirm_delete: true` nel corpo della richiesta. Se il report non esiste, la richiesta restituisce `404`; se viene inviato un report finalizzato senza conferma, restituisce `400` e non viene eliminato nulla.", "operationId": "delete_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID del report." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl (draft report)", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "curl", "label": "curl (finalized report)", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"confirm_delete\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.regulatory_reports.delete(\n \"5ec00000-0000-4000-8000-000000000007\",\n confirm_delete=True,\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.regulatoryReports.delete(\"5ec00000-0000-4000-8000-000000000007\", {\n confirm_delete: true,\n});" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RegulatoryReportsDeleteParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.regulatoryReports().delete(\"5ec00000-0000-4000-8000-000000000007\", RegulatoryReportsDeleteParams.builder()\n .confirmDelete(true)\n .build());" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->delete('5ec00000-0000-4000-8000-000000000007', [\n 'confirm_delete' => true,\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.regulatory_reports.delete(\n \"5ec00000-0000-4000-8000-000000000007\",\n confirm_delete: true\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.RegulatoryReports.DeleteAsync(\"5ec00000-0000-4000-8000-000000000007\", new RegulatoryReportsDeleteParams\n{\n ConfirmDelete = true,\n});" } ], "responses": { "204": { "description": "Report eliminato, inclusi i relativi file generati." }, "400": { "description": "È stato inviato un report finalizzato senza `confirm_delete: true`. Non è stato eliminato nulla.", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_delete": { "type": "array", "items": { "type": "string" } } } }, "example": { "confirm_delete": [ "This field is required to delete a finalized report." ] } } } }, "403": { "description": "La chiave API non può eliminare report. L'endpoint richiede `write:cases`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "404": { "description": "Report non trovato in questa applicazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "409": { "description": "Il report è già in fase di eliminazione. Ripeti la richiesta per completare la cancellazione dei relativi file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } }, "example": { "detail": "This report is being deleted. Retry deleting it to finish erasing its files.", "code": "report_deletion_pending" } } } }, "503": { "description": "Impossibile cancellare i file del report in questo momento. Il report è ancora presente. Ripeti la richiesta.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } }, "example": { "detail": "The report files could not be erased. Please retry deleting the report.", "code": "report_storage_unavailable" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "description": "Obbligatorio solo per un report finalizzato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_delete": { "type": "boolean", "description": "Imposta su true per confermare che un report finalizzato e i file generati vengano eliminati definitivamente." } }, "example": { "confirm_delete": true } }, "example": { "confirm_delete": true } } } } } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/validate/": { "post": { "summary": "Valida report", "description": "Controlla il report rispetto ai campi di intestazione goAML obbligatori (reporting entity ID, submission code, local currency, action taken, submission date), più almeno una transazione allegata e una giurisdizione a 2 lettere, senza generare alcun file. Salva inoltre il risultato nel report: validation_errors e validated_at vengono aggiornati e lo stato di un report non finalizzato passa a VALIDATED (nessun errore) o torna a DRAFT (errori).", "operationId": "validate_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "validate", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID del report." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/validate/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.validate(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.validate(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Validate(ctx, \"5ec00000-0000-4000-8000-000000000007\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().validate(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->validate('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.validate(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.ValidateAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Risultato della validazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "DRAFT", "VALIDATED", "FINALIZED" ] }, "is_valid": { "type": "boolean" }, "errors": { "type": "array", "description": "Vuoto se valido.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/finalize/": { "post": { "summary": "Finalizza il report", "description": "Convalida di nuovo, quindi esegui il rendering di XML e PDF goAML e carica entrambi su S3. Nei report SAR/STR/TFR, questa operazione sposta anche gli alert sulle transazioni del caso da Pending SAR a SAR filed.", "operationId": "finalize_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "finalize", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID del report." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/finalize/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.finalize(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.finalize(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Finalize(ctx, \"5ec00000-0000-4000-8000-000000000007\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().finalize_(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->finalize('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.finalize(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.FinalizeAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Report finalizzato; xml_s3_key e pdf_s3_key sono impostati.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "400": { "description": "Validazione del report non riuscita.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "409": { "description": "Il report non si trova in uno stato finalizzabile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/download-url/": { "get": { "summary": "Recupera URL di download del report", "description": "Genera un URL pre-firmato per l'XML goAML o il PDF di un report finalizzato.", "operationId": "get_regulatory_report_download_url", "x-didit-sdk": { "resource": "regulatory_reports", "method": "retrieve_download_url", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "UUID del report." }, { "name": "file", "in": "query", "schema": { "type": "string", "enum": [ "pdf", "xml" ], "default": "pdf" }, "description": "Quale file scaricare." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/download-url/?file=xml' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.retrieve_download_url(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.retrieveDownloadUrl(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.RetrieveDownloadURL(ctx, \"5ec00000-0000-4000-8000-000000000007\", didit.RegulatoryReportsRetrieveDownloadURLParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().retrieveDownloadUrl(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->retrieveDownloadUrl('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.retrieve_download_url(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.RetrieveDownloadUrlAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "URL di download prefirmato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri" }, "file": { "type": "string", "enum": [ "pdf", "xml" ] } } } } } }, "409": { "description": "Il report non è ancora finalizzato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "status": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/rules/": { "get": { "summary": "Elenca regole", "description": "Elenca le regole di monitoraggio delle transazioni dell'applicazione: le tue regole personalizzate più i preset della libreria che hai installato. Filtra per origine, categoria, modalità, bundle o ricerca a testo libero; ordina con `ordering` (run_count, approved_pct, reviewed_pct, declined_pct, latest_triggered_at, title, created_at, source, ciascuno con un prefisso `-` opzionale).", "operationId": "listTransactionRules", "x-didit-sdk": { "resource": "transactions.rules", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PRESET", "CUSTOM" ] }, "description": "PRESET o CUSTOM" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra per categoria di regola" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ] }, "description": "ACTIVE, DISABLED o TEST" }, { "name": "bundle", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra i preset per bundle" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Corrispondenza senza distinzione tra maiuscole e minuscole rispetto a titolo e descrizione" }, { "name": "ordering", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Campi di ordinamento separati da virgole, predefinito source,-run_count" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Dimensione della pagina" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Offset di pagina" } ], "responses": { "200": { "description": "Regole impaginate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/rules/?source=CUSTOM&ordering=-run_count' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.rules.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.rules.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Rules.ListAutoPaging(ctx, didit.TransactionsRulesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().rules().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.rules.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.Rules.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Crea regola", "description": "Crea una regola di monitoraggio delle transazioni di tipo CUSTOM. I titoli sono univoci per applicazione (duplicato -> 400). Un'azione `change_status` che ha come destinazione `AWAITING_USER` deve contenere `workflow_id`. Le regole create in modalità ACTIVE si applicano immediatamente alle nuove transazioni: il flusso di lavoro consigliato consiste nel creare in modalità TEST, effettuare il backtest e poi passare alla modalità ACTIVE. Per modificare una regola della libreria, creala come copia: invia la definizione della regola della libreria con `metadata.based_on` (la sua chiave di libreria) e `metadata.based_on_rule_uuid`.", "operationId": "createTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleCreateRequest" }, "example": { "title": "Structuring - inbound (custom)", "description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days", "category": "finance", "mode": "TEST", "evaluation_mode": "ALL", "scope": { "transaction_types": [ "finance" ], "directions": [ "INBOUND" ] }, "conditions": [ { "field": "currency", "operator": "eq", "value": "EUR" }, { "field": "amount", "operator": "lt", "value": 10000 } ], "aggregation": [ { "metric": "count", "operator": "gte", "value": 20, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } }, { "metric": "max", "field": "amount", "operator": "lt", "value": 10000, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } } ], "actions": [ { "type": "add_score", "value": 35 } ] } } } }, "responses": { "201": { "description": "La regola creata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } }, "400": { "description": "Errore di validazione - titolo duplicato, operatore/metrica sconosciuti, intervallo non valido, direzione dell'ambito non valida o AWAITING_USER senza workflow_id.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "title": [ "A rule with this name already exists." ] } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/rules/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Structuring - inbound (custom)\", \"description\": \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\", \"category\": \"finance\", \"mode\": \"TEST\", \"evaluation_mode\": \"ALL\", \"scope\": {\"transaction_types\": [\"finance\"], \"directions\": [\"INBOUND\"]}, \"conditions\": [{\"field\": \"currency\", \"operator\": \"eq\", \"value\": \"EUR\"}, {\"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000}], \"aggregation\": [{\"metric\": \"count\", \"operator\": \"gte\", \"value\": 20, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}, {\"metric\": \"max\", \"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}], \"actions\": [{\"type\": \"add_score\", \"value\": 35}]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.create(\n title=\"Structuring - inbound (custom)\",\n description=\"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n category=\"finance\",\n mode=\"TEST\",\n evaluation_mode=\"ALL\",\n scope={\n \"transaction_types\": [\"finance\"],\n \"directions\": [\"INBOUND\"],\n },\n conditions=[{\n \"field\": \"currency\",\n \"operator\": \"eq\",\n \"value\": \"EUR\",\n }, {\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000,\n }],\n aggregation=[{\n \"metric\": \"count\",\n \"operator\": \"gte\",\n \"value\": 20.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }, {\n \"metric\": \"max\",\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }],\n actions=[{\n \"type\": \"add_score\",\n \"value\": 35,\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.create({\n title: \"Structuring - inbound (custom)\",\n description: \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n category: \"finance\",\n mode: \"TEST\",\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n actions: [{\n type: \"add_score\",\n value: 35,\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Create(ctx, didit.TransactionRuleCreateRequest{\n\tTitle: \"Structuring - inbound (custom)\",\n\tDescription: didit.String(\"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\"),\n\tCategory: \"finance\",\n\tMode: \"TEST\",\n\tEvaluationMode: didit.Some(didit.TransactionRuleCreateRequestEvaluationMode(\"ALL\")),\n\tScope: didit.Some(didit.TransactionRuleScopeParam{\n\t\tTransactionTypes: didit.Some([]string{\"finance\"}),\n\t\tDirections: didit.Some([]didit.TransactionRuleScopeDirections{\"INBOUND\"}),\n\t}),\n\tConditions: didit.Some([]didit.TransactionRuleConditionParam{{\n\t\tField: \"currency\",\n\t\tOperator: \"eq\",\n\t\tValue: didit.Some[any](\"EUR\"),\n\t}, {\n\t\tField: \"amount\",\n\t\tOperator: \"lt\",\n\t\tValue: didit.Some[any](10000),\n\t}}),\n\tAggregation: didit.Some([]didit.TransactionRuleAggregationParam{{\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"count\")),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"gte\")),\n\t\tValue: 20.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}, {\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"max\")),\n\t\tField: didit.String(\"amount\"),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"lt\")),\n\t\tValue: 10000.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}}),\n\tActions: didit.Some([]didit.TransactionRuleActionParam{{\n\t\tType: \"add_score\",\n\t\tValue: didit.Some[any](35),\n\t}}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.TransactionRuleAction;\nimport me.didit.types.TransactionRuleActionAddScore;\nimport me.didit.types.TransactionRuleAggregation;\nimport me.didit.types.TransactionRuleCondition;\nimport me.didit.types.TransactionRuleCreateRequest;\nimport me.didit.types.TransactionRuleScope;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().create(TransactionRuleCreateRequest.builder()\n .title(\"Structuring - inbound (custom)\")\n .description(\"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\")\n .category(\"finance\")\n .mode(TransactionRuleCreateRequest.Mode.of(\"TEST\"))\n .evaluationMode(TransactionRuleCreateRequest.EvaluationMode.of(\"ALL\"))\n .scope(TransactionRuleScope.builder()\n .transactionTypes(List.of(\"finance\"))\n .directions(List.of(TransactionRuleScope.Directions.of(\"INBOUND\")))\n .build())\n .conditions(List.of(\n TransactionRuleCondition.builder()\n .field(\"currency\")\n .operator(TransactionRuleCondition.Operator.of(\"eq\"))\n .value(\"EUR\")\n .build(),\n TransactionRuleCondition.builder()\n .field(\"amount\")\n .operator(TransactionRuleCondition.Operator.of(\"lt\"))\n .value(10000)\n .build()))\n .aggregation(List.of(\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"count\"))\n .operator(TransactionRuleAggregation.Operator.of(\"gte\"))\n .value(20.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build(),\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"max\"))\n .field(\"amount\")\n .operator(TransactionRuleAggregation.Operator.of(\"lt\"))\n .value(10000.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build()))\n .actions(List.of(TransactionRuleAction.ofAddScore(TransactionRuleActionAddScore.builder()\n .type(TransactionRuleActionAddScore.Type.of(\"add_score\"))\n .value(35L)\n .build())))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->create([\n 'title' => 'Structuring - inbound (custom)',\n 'description' => '20+ inbound EUR transfers, all under 10,000 EUR, 30 days',\n 'category' => 'finance',\n 'mode' => 'TEST',\n 'evaluation_mode' => 'ALL',\n 'scope' => [\n 'transaction_types' => ['finance'],\n 'directions' => ['INBOUND'],\n ],\n 'conditions' => [[\n 'field' => 'currency',\n 'operator' => 'eq',\n 'value' => 'EUR',\n ], [\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000,\n ]],\n 'aggregation' => [[\n 'metric' => 'count',\n 'operator' => 'gte',\n 'value' => 20.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ], [\n 'metric' => 'max',\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ]],\n 'actions' => [[\n 'type' => 'add_score',\n 'value' => 35,\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.create(\n title: \"Structuring - inbound (custom)\",\n description: \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n category: \"finance\",\n mode: \"TEST\",\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n actions: [{\n type: \"add_score\",\n value: 35,\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.CreateAsync(new TransactionRuleCreateRequest\n{\n Title = \"Structuring - inbound (custom)\",\n Description = \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n Category = \"finance\",\n Mode = \"TEST\",\n EvaluationMode = new TransactionRuleCreateRequestEvaluationMode(\"ALL\"),\n Scope = new TransactionRuleScope\n {\n TransactionTypes = new string[] { \"finance\" },\n Directions = new TransactionRuleScopeDirections[] { \"INBOUND\" },\n },\n Conditions = new TransactionRuleCondition[]\n {\n new()\n {\n Field = \"currency\",\n Operator = \"eq\",\n Value = \"EUR\",\n },\n new()\n {\n Field = \"amount\",\n Operator = \"lt\",\n Value = 10000,\n },\n },\n Aggregation = new TransactionRuleAggregation[]\n {\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"count\"),\n Operator = new TransactionRuleAggregationOperator(\"gte\"),\n Value = 20.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"max\"),\n Field = \"amount\",\n Operator = new TransactionRuleAggregationOperator(\"lt\"),\n Value = 10000.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n },\n Actions = new TransactionRuleAction[]\n {\n new()\n {\n Type = new TransactionRuleActionType(\"add_score\"),\n Value = 35,\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/transactions/rules/{rule_uuid}/": { "parameters": [ { "name": "rule_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "L'UUID della regola restituito dalle operazioni di elenco o creazione." } ], "get": { "summary": "Recupera regola", "description": "Recupera una regola con la sua configurazione completa e i contatori di esecuzione.", "operationId": "getTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "La regola.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } }, "404": { "description": "Nessuna regola del genere in questa applicazione.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Aggiorna la regola", "description": "Aggiorna parzialmente una regola. Le regole personalizzate accettano ogni campo di configurazione. Le regole della libreria (PRESET) accettano solo `mode`: usalo per attivare, disattivare o impostare un preset su TEST; qualsiasi altro campo restituisce 400, poiché Didit gestisce le regole della libreria e applica i relativi aggiornamenti automaticamente. Per modificare le condizioni di una regola della libreria, crea una copia personalizzata con `POST /v3/transactions/rules/` utilizzando la definizione della regola della libreria e `metadata.based_on` (la chiave della libreria) e `metadata.based_on_rule_uuid`, quindi disattiva la regola della libreria con `mode: DISABLED` in modo che una transazione non generi un alert due volte. Una copia installata di una regola della libreria non disponibile è disattivata: impostare il relativo `mode` su qualsiasi valore diverso da `DISABLED` restituisce 400 (\"This library rule cannot run yet: its conditions read data the rules engine cannot evaluate.\").", "operationId": "updateTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleUpdateRequest" }, "example": { "mode": "ACTIVE" } } } }, "responses": { "200": { "description": "La regola aggiornata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } }, "400": { "description": "Errore di validazione, un campo diverso da mode su una regola di libreria, oppure una modalità diversa da DISABLED su una regola di libreria sospesa.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"mode\": \"ACTIVE\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n mode=\"ACTIVE\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.update(\"11111111-2222-3333-4444-555555555555\", {\n mode: \"ACTIVE\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TransactionRuleUpdateRequest{\n\tMode: didit.Some(didit.TransactionRuleUpdateRequestMode(\"ACTIVE\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionRuleUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().update(\"11111111-2222-3333-4444-555555555555\", TransactionRuleUpdateRequest.builder()\n .mode(TransactionRuleUpdateRequest.Mode.of(\"ACTIVE\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->update('11111111-2222-3333-4444-555555555555', [\n 'mode' => 'ACTIVE',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n mode: \"ACTIVE\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new TransactionRuleUpdateRequest\n{\n Mode = new TransactionRuleUpdateRequestMode(\"ACTIVE\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Elimina regola", "description": "Elimina una regola CUSTOM. L'eliminazione è immediata e definitiva: la regola smette di essere valutata per le nuove transazioni e scompare dagli elenchi, mentre le esecuzioni passate della regola su transazioni già valutate mantengono i risultati registrati. Le regole della libreria non possono essere eliminate: disinstallale invece tramite l'endpoint di installazione (possono essere sempre reinstallate dalla libreria).", "operationId": "deleteTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "Eliminato." }, "400": { "description": "La regola è un preset della libreria: disinstallala invece.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "detail": "Library rules cannot be deleted. Uninstall them via the rules install endpoint instead." } } } }, "404": { "description": "Nessuna regola del genere in questa applicazione.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.transactions.rules.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.transactions.rules.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Transactions.Rules.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.transactions().rules().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.rules.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Transactions.Rules.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/transactions/rules/backtest/": { "post": { "summary": "Configurazione della regola di backtest", "description": "Valuta una configurazione ipotetica di una regola rispetto alle tue transazioni recenti (dalla più recente, fino al limite massimo di backtest) senza creare una regola né modificare alcuna transazione. Utilizzala prima di attivare una regola per verificare con quale frequenza avrebbe trovato corrispondenze e quanti soggetti avrebbe interessato.", "operationId": "backtestTransactionRules", "x-didit-sdk": { "resource": "transactions.rules", "method": "backtest", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleBacktestRequest" }, "example": { "conditions": [ { "field": "currency", "operator": "eq", "value": "EUR" }, { "field": "amount", "operator": "lt", "value": 10000 } ], "aggregation": [ { "metric": "count", "operator": "gte", "value": 20, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } }, { "metric": "max", "field": "amount", "operator": "lt", "value": 10000, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } } ], "evaluation_mode": "ALL", "scope": { "transaction_types": [ "finance" ], "directions": [ "INBOUND" ] }, "period_days": 90 } } } }, "responses": { "200": { "description": "Statistiche di backtest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleBacktestResult" }, "example": { "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/rules/backtest/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"conditions\": [{\"field\": \"currency\", \"operator\": \"eq\", \"value\": \"EUR\"}, {\"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000}], \"aggregation\": [{\"metric\": \"count\", \"operator\": \"gte\", \"value\": 20, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}, {\"metric\": \"max\", \"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}], \"evaluation_mode\": \"ALL\", \"scope\": {\"transaction_types\": [\"finance\"], \"directions\": [\"INBOUND\"]}, \"period_days\": 90}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.backtest(\n conditions=[{\n \"field\": \"currency\",\n \"operator\": \"eq\",\n \"value\": \"EUR\",\n }, {\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000,\n }],\n aggregation=[{\n \"metric\": \"count\",\n \"operator\": \"gte\",\n \"value\": 20.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }, {\n \"metric\": \"max\",\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }],\n evaluation_mode=\"ALL\",\n scope={\n \"transaction_types\": [\"finance\"],\n \"directions\": [\"INBOUND\"],\n },\n period_days=90,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.backtest({\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n period_days: 90,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Backtest(ctx, didit.TransactionRuleBacktestRequest{\n\tConditions: didit.Some([]didit.TransactionRuleConditionParam{{\n\t\tField: \"currency\",\n\t\tOperator: \"eq\",\n\t\tValue: didit.Some[any](\"EUR\"),\n\t}, {\n\t\tField: \"amount\",\n\t\tOperator: \"lt\",\n\t\tValue: didit.Some[any](10000),\n\t}}),\n\tAggregation: didit.Some([]didit.TransactionRuleAggregationParam{{\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"count\")),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"gte\")),\n\t\tValue: 20.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}, {\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"max\")),\n\t\tField: didit.String(\"amount\"),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"lt\")),\n\t\tValue: 10000.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}}),\n\tEvaluationMode: didit.Some(didit.TransactionRuleBacktestRequestEvaluationMode(\"ALL\")),\n\tScope: didit.Some(didit.TransactionRuleScopeParam{\n\t\tTransactionTypes: didit.Some([]string{\"finance\"}),\n\t\tDirections: didit.Some([]didit.TransactionRuleScopeDirections{\"INBOUND\"}),\n\t}),\n\tPeriodDays: didit.Int(90),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.TransactionRuleAggregation;\nimport me.didit.types.TransactionRuleBacktestRequest;\nimport me.didit.types.TransactionRuleCondition;\nimport me.didit.types.TransactionRuleScope;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().backtest(TransactionRuleBacktestRequest.builder()\n .conditions(List.of(\n TransactionRuleCondition.builder()\n .field(\"currency\")\n .operator(TransactionRuleCondition.Operator.of(\"eq\"))\n .value(\"EUR\")\n .build(),\n TransactionRuleCondition.builder()\n .field(\"amount\")\n .operator(TransactionRuleCondition.Operator.of(\"lt\"))\n .value(10000)\n .build()))\n .aggregation(List.of(\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"count\"))\n .operator(TransactionRuleAggregation.Operator.of(\"gte\"))\n .value(20.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build(),\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"max\"))\n .field(\"amount\")\n .operator(TransactionRuleAggregation.Operator.of(\"lt\"))\n .value(10000.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build()))\n .evaluationMode(TransactionRuleBacktestRequest.EvaluationMode.of(\"ALL\"))\n .scope(TransactionRuleScope.builder()\n .transactionTypes(List.of(\"finance\"))\n .directions(List.of(TransactionRuleScope.Directions.of(\"INBOUND\")))\n .build())\n .periodDays(90L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->backtest([\n 'conditions' => [[\n 'field' => 'currency',\n 'operator' => 'eq',\n 'value' => 'EUR',\n ], [\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000,\n ]],\n 'aggregation' => [[\n 'metric' => 'count',\n 'operator' => 'gte',\n 'value' => 20.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ], [\n 'metric' => 'max',\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ]],\n 'evaluation_mode' => 'ALL',\n 'scope' => [\n 'transaction_types' => ['finance'],\n 'directions' => ['INBOUND'],\n ],\n 'period_days' => 90,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.backtest(\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n period_days: 90\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.BacktestAsync(new TransactionRuleBacktestRequest\n{\n Conditions = new TransactionRuleCondition[]\n {\n new()\n {\n Field = \"currency\",\n Operator = \"eq\",\n Value = \"EUR\",\n },\n new()\n {\n Field = \"amount\",\n Operator = \"lt\",\n Value = 10000,\n },\n },\n Aggregation = new TransactionRuleAggregation[]\n {\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"count\"),\n Operator = new TransactionRuleAggregationOperator(\"gte\"),\n Value = 20.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"max\"),\n Field = \"amount\",\n Operator = new TransactionRuleAggregationOperator(\"lt\"),\n Value = 10000.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n },\n EvaluationMode = new TransactionRuleBacktestRequestEvaluationMode(\"ALL\"),\n Scope = new TransactionRuleScope\n {\n TransactionTypes = new string[] { \"finance\" },\n Directions = new TransactionRuleScopeDirections[] { \"INBOUND\" },\n },\n PeriodDays = 90,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/transactions/rules/library/": { "get": { "summary": "Elenca la libreria delle regole", "description": "Esplora l'intera libreria di regole predefinite (150+ regole) con la configurazione completa di ciascuna voce e un flag `is_installed` per questa applicazione. Filtra per bundle, categoria o ricerca a testo libero. Una regola della libreria le cui condizioni leggono dati che il motore delle regole non è ancora in grado di valutare viene trattenuta finché non può essere eseguita. Le regole trattenute non sono elencate.", "operationId": "listTransactionRuleLibrary", "x-didit-sdk": { "resource": "transactions.rules", "method": "list_library", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "bundle", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra per bundle, ad es. finance, aml_ctf, crypto_monitoring, travel_rule" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra per categoria" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Corrispondenza senza distinzione tra maiuscole e minuscole rispetto a titolo e descrizione" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Dimensione della pagina" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Offset di pagina" } ], "responses": { "200": { "description": "Voci della libreria impaginate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleLibraryEntry" } } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/rules/library/?bundle=finance' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.rules.list_library():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.rules.listLibrary()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Rules.ListLibraryAutoPaging(ctx, didit.TransactionsRulesListLibraryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().rules().listLibrary()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->listLibrary() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.rules.list_library.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.Rules.ListLibraryAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/transactions/rules/install/": { "post": { "summary": "Installa regole di libreria", "description": "Installa uno o più preset nell'applicazione, tramite `library_keys` o un intero `bundle`. Un preset installato è subito attivo se il monitoraggio delle transazioni è abilitato, altrimenti resta disabilitato; le chiavi già installate vengono ignorate. Una regola di libreria le cui condizioni leggono dati che il motore delle regole non può ancora valutare viene sospesa finché non può essere eseguita. Una richiesta che ne specifica una in `library_keys` risponde con 400 e non installa nulla (\"These library rules cannot run yet: their conditions read data the rules engine cannot evaluate.\" seguito dalle chiavi), mentre l'installazione di un `bundle` la ignora. Una regola sospesa si riattiva autonomamente non appena le sue condizioni possono essere valutate. Una voce in `library_keys` che non è presente nella libreria viene ignorata, non rifiutata.", "operationId": "installTransactionRuleLibrary", "x-didit-sdk": { "resource": "transactions.rules", "method": "install_library", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallRequest" }, "example": { "library_keys": [ "structuring-inbound", "structuring-outbound" ] } } } }, "responses": { "200": { "description": "Cosa è stato installato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallResult" }, "example": { "installed_library_keys": [ "structuring-inbound", "structuring-outbound" ], "installed_count": 2 } } } }, "400": { "description": "Né library_keys né bundle forniti, `library_keys` non è un elenco, oppure una voce di `library_keys` è trattenuta. Una voce sconosciuta viene ignorata e risponde 200 senza di essa.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/rules/install/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"library_keys\": [\"structuring-inbound\", \"structuring-outbound\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.install_library(\n library_keys=[\"structuring-inbound\", \"structuring-outbound\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.installLibrary({\n library_keys: [\"structuring-inbound\", \"structuring-outbound\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.InstallLibrary(ctx, didit.TransactionRuleInstallRequest{\n\tLibraryKeys: didit.Some([]string{\"structuring-inbound\", \"structuring-outbound\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TransactionRuleInstallRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().installLibrary(TransactionRuleInstallRequest.builder()\n .libraryKeys(List.of(\"structuring-inbound\", \"structuring-outbound\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->installLibrary([\n 'library_keys' => ['structuring-inbound', 'structuring-outbound'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.install_library(library_keys: [\"structuring-inbound\", \"structuring-outbound\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.InstallLibraryAsync(new TransactionRuleInstallRequest\n{\n LibraryKeys = new string[] { \"structuring-inbound\", \"structuring-outbound\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Disinstalla regole della libreria", "description": "Rimuovi i preset installati dall'applicazione, tramite `library_keys` o un intero `bundle`. I preset disinstallati smettono immediatamente di essere valutati e possono essere reinstallati dalla libreria in qualsiasi momento.", "operationId": "uninstallTransactionRuleLibrary", "x-didit-sdk": { "resource": "transactions.rules", "method": "uninstall_library", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallRequest" }, "example": { "bundle": "responsible_gaming" } } } }, "responses": { "200": { "description": "Quanti preset sono stati rimossi.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallResult" }, "example": { "uninstalled_count": 5 } } } }, "400": { "description": "Né library_keys né bundle forniti.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/transactions/rules/install/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"bundle\": \"responsible_gaming\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.uninstall_library(\n bundle=\"responsible_gaming\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.uninstallLibrary({\n bundle: \"responsible_gaming\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.UninstallLibrary(ctx, didit.TransactionRuleInstallRequest{\n\tBundle: didit.String(\"responsible_gaming\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionRuleInstallRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().uninstallLibrary(TransactionRuleInstallRequest.builder()\n .bundle(\"responsible_gaming\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->uninstallLibrary([\n 'bundle' => 'responsible_gaming',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.uninstall_library(bundle: \"responsible_gaming\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.UninstallLibraryAsync(new TransactionRuleInstallRequest\n{\n Bundle = \"responsible_gaming\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/": { "get": { "summary": "Elenca le reti", "description": "Elenca le reti di frode rilevate all'interno dell'organizzazione di questa applicazione, con il rischio più elevato per primo come impostazione predefinita. Per impostazione predefinita le reti ignorate sono escluse; passa status per includerle. Le applicazioni sandbox non hanno mai reti: il clustering esclude completamente i dati sandbox. Ogni risposta include lo `sharing_mode` dell'organizzazione e se i segnali tra organizzazioni diverse si applicano ad essa (`cross_org_available`, `cross_org_unavailable_reason`). `kpis` aggrega le reti che corrispondono ai tuoi filtri e `counts` aggrega ogni rete che l'applicazione può vedere; passa `summary=false` per saltare entrambi quando ti serve solo la pagina. Richiede una chiave API ad accesso completo, o `list:networks` per un membro della console.", "operationId": "list_networks", "x-didit-sdk": { "resource": "networks", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Stati separati da virgole da includere: active,in_review,resolved,dismissed. Omettere per escludere dismissed." }, { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "identity", "transactions" ] }, "description": "`transactions` mantiene le reti i cui membri sono tutti parti della transazione; `identity` mantiene tutte le altre reti. Ometti per entrambe. Restringe anche `counts.views` e `counts.facets`. Qualsiasi altro valore restituisce 400." }, { "name": "signal_type", "in": "query", "schema": { "type": "string" }, "description": "Tipi di segnale separati da virgole: ip_address,device,face,document_number,phone,email,address." }, { "name": "pattern_type", "in": "query", "schema": { "type": "string" }, "description": "Tipi di pattern separati da virgole, ad es. exact_same_device,same_email." }, { "name": "risk_band", "in": "query", "schema": { "type": "string" }, "description": "Fasce separate da virgole: low,medium,high." }, { "name": "min_size", "in": "query", "schema": { "type": "integer" }, "description": "Numero minimo di membri." }, { "name": "max_size", "in": "query", "schema": { "type": "integer" }, "description": "Numero massimo di membri." }, { "name": "assignee", "in": "query", "schema": { "type": "string" }, "description": "Assegnatari separati da virgole: `unassigned`, email dei membri (confronto senza distinzione tra maiuscole e minuscole) o `me` per il membro della console chiamante. Una rete corrisponde a qualsiasi valore. `me` richiede un token di un membro della console: una chiave API riceve 400 `{\"assignee\": [\"\\\"me\\\" needs a user token; an API key has no assignee identity.\"]}`." }, { "name": "priority", "in": "query", "schema": { "type": "string" }, "description": "Priorità separate da virgole: `low`, `medium`, `high` o `none` per le reti senza una priorità. Qualsiasi altro valore restituisce 400 `{\"priority\": \"Unknown priority: .\"}`." }, { "name": "risk_min", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "description": "Punteggio di rischio minimo, un numero intero da 0 a 100. Un valore che non è un numero intero restituisce 400 `{\"risk_min\": \"Use a whole number from 0 to 100.\"}`." }, { "name": "has_case", "in": "query", "schema": { "type": "boolean" }, "description": "`true` mantiene le reti per cui la tua applicazione ha aperto un caso, `false` le altre. Qualsiasi altro valore viene ignorato." }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Limite inferiore su last_activity_at (data o data e ora ISO 8601)." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Limite superiore per first_activity_at (data o datetime ISO 8601)." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Ricerca a testo libero su nome della rete, nomi dei membri, network_id (N-0001) e token esatti di pattern_type." }, { "name": "ordering", "in": "query", "schema": { "type": "string" }, "description": "Uno tra risk_score, -risk_score, last_activity_at, -last_activity_at, first_activity_at, -first_activity_at, network_number, -network_number. Il valore predefinito è -risk_score,-last_activity_at." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "Dimensione della pagina, 1-500. Il valore predefinito è 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Offset in base zero del primo record." }, { "name": "summary", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "`false` restituisce solo la pagina e il relativo `count`, senza `kpis` e `counts`. Il valore predefinito è `true`. Qualsiasi valore diverso da `true` o `false` restituisce 400." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/?status=active,in_review&ordering=-risk_score' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.networks.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.networks.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Networks.ListAutoPaging(ctx, didit.NetworksListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.networks().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "networks->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.networks.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Networks.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Elenco impaginato delle reti, con la modalità di condivisione dell'organizzazione e la disponibilità tra organizzazioni, oltre a `kpis` e `counts` a meno che `summary=false`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "integer", "nullable": true, "description": "Offset della pagina successiva, oppure null nell'ultima pagina." }, "previous": { "type": "integer", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkListItem" } }, "kpis": { "type": "object", "description": "Ogni chiave contiene {value, delta} per i risultati corrispondenti ai filtri correnti. Omesso quando `summary=false`.", "properties": { "active": { "type": "object" }, "in_review": { "type": "object" }, "applicants_involved": { "type": "object" }, "detected_this_period": { "type": "object" }, "false_positive_rate": { "type": "object" } } }, "counts": { "$ref": "#/components/schemas/NetworkListCounts" }, "sharing_mode": { "type": "string", "enum": [ "off", "private", "global" ], "description": "La modalità di condivisione tra organizzazioni dell'organizzazione. Solo `global` confronta le reti tra organizzazioni; `private` e `off` le limitano alla cronologia interna dell'organizzazione.", "example": "global" }, "cross_org_available": { "type": "boolean", "description": "Indica se i segnali tra organizzazioni si applicano a questa organizzazione. Richiedono sia il piano Enterprise sia la modalità di condivisione `global`.", "example": true }, "cross_org_unavailable_reason": { "type": "string", "enum": [ "plan", "sharing_mode" ], "nullable": true, "description": "Il motivo per cui i segnali inter-organizzazione non sono applicabili, verificati in questo ordine. `plan`: il piano dell'organizzazione non include la rete antifrode inter-organizzazione (richiede il piano Enterprise), indipendentemente dalla modalità di condivisione. `sharing_mode`: il piano la include, ma la modalità di condivisione è `private` o `off`. Null quando `cross_org_available` è `true`.", "example": null } }, "required": [ "count", "next", "previous", "results", "sharing_mode", "cross_org_available", "cross_org_unavailable_reason" ] } } } }, "400": { "description": "Un valore non valido per filtro, ordinamento, paginazione o `summary`.", "content": { "application/json": { "examples": { "Invalid summary": { "summary": "Riepilogo non valido", "value": { "summary": [ "Must be \"true\" or \"false\"." ] } }, "Invalid scope": { "summary": "Ambito non valido", "value": { "scope": [ "Use identity or transactions." ] } }, "Unsupported ordering": { "summary": "Ordinamento non supportato", "value": [ "Unsupported ordering." ] } } } } }, "401": { "description": "Credenziali mancanti o non valide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenziali mancanti o non valide", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "La chiave API appartiene a un'altra applicazione, oppure è una chiave con accesso limitato: gli endpoint Networks richiedono una chiave con accesso completo. Un token di un membro della console richiede `list:networks`. Viene restituito anche con `code: networks_not_entitled` quando Networks non è abilitato per l'organizzazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Reti non abilitate", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chiave API con restrizioni", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Nessuna autorizzazione", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/": { "get": { "summary": "Recupera rete", "description": "Recupera i dettagli completi di una singola rete: statistiche, tag di frode e segnali di rischio, oltre a `sharing_mode` e alla disponibilità tra organizzazioni per l'organizzazione, i `tags` della tua applicazione sulla rete, gli esiti (`outcomes`) dei membri e i punteggi dei pattern (`patterns`). Richiede una chiave API con accesso completo, oppure `read:networks` per un membro della console.", "operationId": "get_network", "x-didit-sdk": { "resource": "networks", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID della rete." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieve(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.Retrieve(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieve(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieve('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Dettaglio della rete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [ { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "SUSPICIOUS", "color": "#6366F1", "source": "custom", "added_by": null, "added_at": "2026-10-13T08:15:00Z" } ], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "404": { "description": "Rete non trovata (o non visibile per questa applicazione).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "401": { "description": "Credenziali mancanti o non valide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenziali mancanti o non valide", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "La chiave API appartiene a un'altra applicazione, oppure è una chiave con accesso limitato: gli endpoint Networks richiedono una chiave con accesso completo. Un token di un membro della console richiede `read:networks`. Viene restituito anche con `code: networks_not_entitled` quando Networks non è abilitato per l'organizzazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Reti non abilitate", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chiave API con restrizioni", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Nessuna autorizzazione", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/graph/": { "get": { "summary": "Recupera grafo della rete", "description": "Recupera la rete come grafo di nodi dei soggetti (utenti del fornitore, aziende del fornitore, parti della transazione) e nodi dei segnali (i valori condivisi di dispositivo/IP/volto/documento/telefono/email/indirizzo che li collegano), con archi che rappresentano le appartenenze.", "operationId": "get_network_graph", "x-didit-sdk": { "resource": "networks", "method": "retrieve_graph", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID della rete." }, { "name": "depth", "in": "query", "schema": { "type": "string", "enum": [ "1", "2", "3", "all" ] }, "description": "Salti dal soggetto di riferimento da includere. Il valore predefinito include tutti i salti (illimitato)." }, { "name": "focus_kind", "in": "query", "schema": { "type": "string", "enum": [ "vendor_user", "vendor_business", "transaction_party" ] }, "description": "Tipo di soggetto su cui centrare il grafo. Deve essere fornito insieme a focus_id; se la profondità è limitata e nessuno dei due è fornito, il valore predefinito è un membro arbitrario." }, { "name": "focus_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "UUID del soggetto su cui centrare il grafo." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/graph/?depth=2' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve_graph(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieveGraph(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RetrieveGraph(ctx, \"n3a5e000-0000-4000-8000-000000000001\", didit.NetworksRetrieveGraphParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieveGraph(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieveGraph('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve_graph(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveGraphAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Grafo della rete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkGraph" } } } }, "404": { "description": "Rete non trovata (o non visibile per questa applicazione).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/members/": { "get": { "summary": "Elenca i membri della rete", "description": "Elenca i soggetti (utenti vendor, aziende vendor o parti della transazione) che appartengono a questa rete.", "operationId": "list_network_members", "x-didit-sdk": { "resource": "networks", "method": "list_members", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID della rete." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/members/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.list_members(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.listMembers(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.ListMembers(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().listMembers(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->listMembers('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.list_members(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.ListMembersAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Membri della rete. Senza paginazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkMember" } } } } } } }, "404": { "description": "Rete non trovata (o non visibile per questa applicazione).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/signals/": { "get": { "summary": "Elenca i segnali della rete", "description": "Elenca i segnali (valori condivisi di dispositivo, IP, volto, numero di documento, telefono, email o indirizzo) che collegano i membri di questa rete.", "operationId": "list_network_signals", "x-didit-sdk": { "resource": "networks", "method": "list_signals", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID della rete." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/signals/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.list_signals(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.listSignals(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.ListSignals(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().listSignals(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->listSignals('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.list_signals(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.ListSignalsAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Segnali della rete. Senza paginazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkSignal" } } } } } } }, "404": { "description": "Rete non trovata (o non visibile per questa applicazione).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/timeline/": { "get": { "summary": "Recupera timeline della rete", "description": "Senza `contract`: gli eventi della rete stessa (rilevamento, l'osservazione più recente di ciascun segnale e la relativa revisione), dal più vecchio al più recente e non impaginati. `limit`, `cursor` e `event_type` vengono ignorati. Con `contract=2`: la cronologia tipizzata, dalla più recente alla più vecchia e impaginata tramite cursore. Aggiunge le azioni eseguite dagli account membri (tentativi di verifica, transazioni, accessi inviati tramite l'API eventi e le regole attive che hanno attivato) e i casi aperti per la rete. Gli eventi `note_added` vengono restituiti solo ai membri della console, mai a una chiave API. Richiede una chiave API con accesso completo o `read:networks` per un membro della console.", "operationId": "get_network_timeline", "x-didit-sdk": { "resource": "networks", "method": "retrieve_timeline", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID della rete." }, { "name": "contract", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "2" ] }, "description": "`2` restituisce la cronologia tipizzata. Omettilo per la cronologia predefinita. Qualsiasi altro valore restituisce 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "Solo cronologia con tipizzazione. Eventi per pagina, da 1 a 500. Il valore predefinito è 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Solo cronologia con tipizzazione. Il `next_cursor` della pagina precedente. Un cursore non valido o vuoto restituisce 400." }, { "name": "event_type", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "network_detected", "signal_observed", "network_active", "network_in_review", "network_resolved", "network_dismissed", "verification_attempt", "transaction", "login", "rule_hit", "case_linked", "note_added" ] } }, "description": "Solo cronologia con tipizzazione. Tipi di eventi da conservare, ripetuti o separati da virgola, massimo 20 valori. Il valore predefinito include tutti i tipi." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/timeline/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "curl", "label": "curl (typed timeline)", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/3fa85f64-5717-4562-b3fc-2c963f66afa6/timeline/?contract=2&limit=50&event_type=verification_attempt,login' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve_timeline(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieveTimeline(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RetrieveTimeline(ctx, \"n3a5e000-0000-4000-8000-000000000001\", didit.NetworksRetrieveTimelineParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieveTimeline(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieveTimeline('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve_timeline(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveTimelineAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Senza `contract`: `{results}`, i meno recenti per primi, non impaginati. Con `contract=2`: `{results, next_cursor}`, i più recenti per primi.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NetworkTimeline" }, { "$ref": "#/components/schemas/NetworkTimelinePage" } ] }, "examples": { "Default timeline": { "summary": "Senza contract", "value": { "results": [ { "event_type": "network_detected", "occurred_at": "2026-10-01T09:12:44Z", "label": "Network detected", "metadata": { "network_id": "N-0042" } }, { "event_type": "signal_observed", "occurred_at": "2026-10-12T16:03:10Z", "label": "device observed", "metadata": { "signal_type": "device", "subject_count": 3, "is_hub": false } }, { "event_type": "network_in_review", "occurred_at": "2026-10-12T16:30:00Z", "label": "Network in_review", "metadata": { "reason": "Shared device across three new accounts." } } ] } }, "Typed timeline": { "summary": "Con contract=2", "value": { "results": [ { "id": "monitoring_event:9b2f1c3e-4d5a-4b6c-8d7e-0f1a2b3c4d5e", "event_type": "login", "occurred_at": "2026-10-12T18:41:02Z", "ingested_at": "2026-10-12T18:41:03Z", "label": "Login", "metadata": {}, "account": { "node_id": "vendor_user:5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "node_type": "account", "uuid": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "vendor_data": "user-1042", "display_name": "Alex Example", "ownership": "owned", "route": { "kind": "user", "id": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "source_ref": { "kind": "monitoring_event", "id": "9b2f1c3e-4d5a-4b6c-8d7e-0f1a2b3c4d5e", "ownership": "owned" }, "verification_attempt": null, "transaction": null, "login": { "action": "auth.login", "succeeded": true, "status": "APPROVED", "ip": { "address": "203.0.113.24", "country_code": "ES", "city": "Madrid", "connection_type": null, "is_vpn_or_tor": false, "is_data_center": false }, "device": { "fingerprint": "fp_0a1b2c3d", "label": "Chrome · Android" }, "is_first_login": false, "is_new_device": true }, "rule_hit": null, "case_linked": null, "note_added": null }, { "id": "session:1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "event_type": "verification_attempt", "occurred_at": "2026-10-12T16:03:10Z", "ingested_at": "2026-10-12T16:03:10Z", "label": "Verification attempt 2 of 2", "metadata": {}, "account": { "node_id": "vendor_user:5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "node_type": "account", "uuid": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "vendor_data": "user-1042", "display_name": "Alex Example", "ownership": "owned", "route": { "kind": "user", "id": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "source_ref": { "kind": "session", "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "ownership": "owned", "route": { "kind": "session", "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "verification_attempt": { "session_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "session_number": 1287, "attempt": 2, "attempt_count": 2, "status": "Approved", "status_changed_at": "2026-10-12T16:05:41Z", "decline_reasons": [] }, "transaction": null, "login": null, "rule_hit": null, "case_linked": null, "note_added": null }, { "id": "signal_observed:8d7c6b5a-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "event_type": "signal_observed", "occurred_at": "2026-10-12T16:03:10Z", "ingested_at": "2026-10-01T09:12:44Z", "label": "device observed", "metadata": { "signal_type": "device", "subject_count": 3, "is_hub": false }, "account": null, "source_ref": null, "verification_attempt": null, "transaction": null, "login": null, "rule_hit": null, "case_linked": null, "note_added": null } ], "next_cursor": "eyJ0IjoiMjAyNi0xMC0xMlQxNjowMzoxMCswMDowMCIsImMiOiIyMDI2LTEwLTAxVDA5OjEyOjQ0KzAwOjAwIiwiciI6MSwidSI6IjhkN2M2YjVhLTRlM2YtNGEyYi05YzFkLTBlOWY4YTdiNmM1ZCJ9" } } } } } }, "400": { "description": "Con `contract` presente: un valore non valido per `contract`, `limit`, `cursor` o `event_type`.", "content": { "application/json": { "examples": { "Unsupported contract": { "summary": "Contratto non supportato", "value": { "contract": [ "\"3\" is not a valid choice." ] } }, "Invalid cursor": { "summary": "Cursore non valido", "value": { "cursor": [ "This cursor is not valid. Reload the feed." ] } }, "Limit too large": { "summary": "Limite troppo elevato", "value": { "limit": [ "Ensure this value is less than or equal to 500." ] } }, "Unknown event type": { "summary": "Tipo di evento sconosciuto", "value": { "event_type": { "0": [ "\"logout\" is not a valid choice." ] } } } } } } }, "401": { "description": "Credenziali mancanti o non valide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenziali mancanti o non valide", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "La chiave API appartiene a un'altra applicazione, oppure è una chiave con accesso limitato: gli endpoint Networks richiedono una chiave con accesso completo. Un token di un membro della console richiede `read:networks`. Viene restituito anche con `code: networks_not_entitled` quando Networks non è abilitato per l'organizzazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Reti non abilitate", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chiave API con restrizioni", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Nessuna autorizzazione", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Rete non trovata (o non visibile per questa applicazione).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/map/": { "get": { "summary": "Recupera mappa della rete", "description": "Punti geografici in cui convergono gli indirizzi/posizioni dei membri di questa rete, ricavati dalle sessioni, dalle sessioni aziendali e dalle transazioni a supporto delle relative appartenenze.", "operationId": "get_network_map", "x-didit-sdk": { "resource": "networks", "method": "retrieve_map", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "UUID della rete." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/map/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve_map(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieveMap(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RetrieveMap(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieveMap(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieveMap('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve_map(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveMapAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Mappa della rete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkMap" } } } }, "404": { "description": "Rete non trovata (o non visibile per questa applicazione).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/sessions/{session_id}/networks/": { "get": { "summary": "Elenca le reti per una sessione", "description": "Elenca le reti a cui appartiene l'utente del fornitore della sessione. La risoluzione avviene tramite l'utente collegato a vendor_data della sessione.", "operationId": "list_session_network_memberships", "x-didit-sdk": { "resource": "sessions", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID della sessione." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/sessions/aaaaaaaa-0000-4000-8000-000000000001/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.sessions.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.sessions().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Reti a cui appartiene questa entità. Senza paginazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entità non trovata in questa applicazione o priva di un soggetto collegato da ricercare.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/business-sessions/{business_session_id}/networks/": { "get": { "summary": "Elenca le reti per una sessione aziendale", "description": "Elenca le reti a cui appartiene l'azienda del fornitore della sessione aziendale.", "operationId": "list_business_session_network_memberships", "x-didit-sdk": { "resource": "business_sessions", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "business_session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID della sessione aziendale." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/business-sessions/aaaaaaaa-0000-4000-8000-000000000002/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.business_sessions.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businessSessions.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.BusinessSessions.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businessSessions().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businessSessions->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.business_sessions.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.BusinessSessions.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Reti a cui appartiene questa entità. Senza paginazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entità non trovata in questa applicazione o priva di un soggetto collegato da ricercare.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/users/{vendor_user_uuid}/networks/": { "get": { "summary": "Elenca le reti per un utente", "description": "Elenca le reti a cui appartiene un utente del fornitore.", "operationId": "list_user_network_memberships", "x-didit-sdk": { "resource": "users", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "vendor_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'utente vendor." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/users/aaaaaaaa-0000-4000-8000-000000000003/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Reti a cui appartiene questa entità. Senza paginazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entità non trovata in questa applicazione o priva di un soggetto collegato da ricercare.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/{vendor_business_uuid}/networks/": { "get": { "summary": "Elenca le reti per un'azienda", "description": "Elenca le reti a cui appartiene un'azienda del fornitore.", "operationId": "list_business_network_memberships", "x-didit-sdk": { "resource": "businesses", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "vendor_business_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'azienda vendor." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/businesses/aaaaaaaa-0000-4000-8000-000000000004/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Reti a cui appartiene questa entità. Senza paginazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entità non trovata in questa applicazione o priva di un soggetto collegato da ricercare.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/{transaction_uuid}/networks/": { "get": { "summary": "Elenca le reti per una transazione", "description": "Elenca le reti a cui appartiene il soggetto KYC/KYB sottostante alla transazione (risolto tramite la sessione o la sessione aziendale della transazione).", "operationId": "list_transaction_network_memberships", "x-didit-sdk": { "resource": "transactions", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "transaction_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID della transazione." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/aaaaaaaa-0000-4000-8000-000000000005/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.transactions.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.transactions.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.transactions().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.transactions.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Reti a cui appartiene questa entità. Senza paginazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entità non trovata in questa applicazione o priva di un soggetto collegato da ricercare.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/{transaction_uuid}/parties/{transaction_party_uuid}/networks/": { "get": { "summary": "Elenca le reti per una controparte della transazione", "description": "Elenca le reti a cui appartiene una parte della transazione (ordinante, beneficiario o controparte), risolta tramite la parte stessa anziché tramite la sessione sottostante della transazione.", "operationId": "list_transaction_party_network_memberships", "x-didit-sdk": { "resource": "transactions", "method": "list_party_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "transaction_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID della transazione." }, { "name": "transaction_party_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID della parte della transazione." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/aaaaaaaa-0000-4000-8000-000000000005/parties/bbbbbbbb-0000-4000-8000-000000000006/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.transactions.list_party_networks(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.transactions.listPartyNetworks(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.ListPartyNetworks(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.transactions().listPartyNetworks(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->listPartyNetworks('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.transactions.list_party_networks(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.ListPartyNetworksAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Reti a cui appartiene questa entità. Senza paginazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "Entità non trovata in questa applicazione o priva di un soggetto collegato da ricercare.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/biometric-templates/": { "get": { "summary": "Elenca i modelli biometrici conservati", "description": "Un'applicazione che ha aderito mantiene un modello biometrico facciale gestito separatamente e privo di immagini, ancorato all'utente quando una sessione viene eliminata (vedere `DELETE /v3/session/{sessionId}/delete/`). I modelli sono dati biometrici con un `expires_at` finito; non contengono mai immagini, dati di sessione o campi di identità e vengono eliminati definitivamente all'eliminazione dell'utente, alla cancellazione per motivi di privacy, alla scadenza o tramite un'eliminazione definitiva esplicita. Questi endpoint accettano solo chiavi API dell'applicazione (`x-api-key`); i token utente della Business Console vengono rifiutati con `403`.\n\nRestituisce un elenco impaginato dei modelli attualmente conservati dall'applicazione. I modelli eliminati definitivamente non sono elencati.", "operationId": "list_biometric_templates", "x-didit-sdk": { "resource": "biometric_templates", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "vendor_data", "required": false, "description": "Corrispondenza di sottostringhe senza distinzione tra maiuscole e minuscole sul `vendor_data` corrente dell'Utente proprietario.", "schema": { "type": "string" } }, { "in": "query", "name": "vendor_user_uuid", "required": false, "description": "Corrispondenza esatta sull'utente proprietario.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "required": false, "description": "Stato del ciclo di vita. I modelli eliminati definitivamente non vengono mai elencati.", "schema": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed" ] } }, { "in": "query", "name": "source_type", "required": false, "description": "Come è stato creato il modello.", "schema": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ] } }, { "in": "query", "name": "retained_from", "required": false, "description": "Modelli conservati a partire da questa data e ora o successivamente.", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "retained_to", "required": false, "description": "Modelli conservati entro questa data e ora o precedentemente. Non deve essere anteriore a `retained_from` (`400`).", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "ordering", "required": false, "description": "Ordinamento.", "schema": { "type": "string", "enum": [ "retained_at", "-retained_at", "expires_at", "-expires_at" ], "default": "-retained_at" } }, { "in": "query", "name": "limit", "required": false, "description": "Dimensione della pagina.", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "description": "Offset di paginazione.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Modelli impaginati.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID del modello. Generato casualmente; non derivato dalla sessione eliminata o dal relativo volto." }, "vendor_user_uuid": { "type": "string", "format": "uuid", "description": "L'Utente proprietario." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il `vendor_data` corrente dell'Utente, risolto al momento della lettura del modello (mai copiato)." }, "source_type": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ], "description": "Come è stato creato il modello: l'eliminazione di una sessione (API o Console), la finestra di conservazione dei dati automatica dell'applicazione o un backfill gestito da Didit su tua istruzione." }, "provenance_reference": { "type": "string", "format": "uuid", "description": "Riferimento opaco che collega il modello al suo registro di audit. Non è l'ID della sessione eliminata e non può essere ricondotto ad esso." }, "retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "La policy dell'applicazione al momento della conservazione dei dati." }, "retention_override": { "type": "boolean", "nullable": true, "description": "Il valore `retain_face_embeddings` inviato all'eliminazione, oppure `null` quando è stata applicata la policy." }, "retained_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando il modello scade e viene eliminato automaticamente. Sempre impostato." }, "retained_by": { "type": "string", "nullable": true, "description": "Soggetto che ha impartito l'istruzione: l'ID applicazione per le chiavi API, l'ID membro della Console per le azioni della Console, oppure un identificatore `service:` per la conservazione automatica. Mai un indirizzo email." }, "retained_by_type": { "type": "string", "enum": [ "API_KEY", "CONSOLE_USER", "SYSTEM" ] }, "instruction_class": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ] }, "instruction_source": { "type": "string", "enum": [ "api", "console", "automatic_retention", "backfill", "privacy_erasure", "explicit_template_purge", "vendor_user_delete", "expiry", "reconciliation", "migration", "system" ] }, "instruction_id": { "type": "string", "description": "L'`instruction_id` inviato all'eliminazione, oppure un id generato da Didit." }, "held_out_of_use": { "type": "boolean", "description": "`true` solo quando si applica un vincolo di conservazione legale. Un modello soggetto a tale vincolo è escluso da qualsiasi corrispondenza." }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed", "purged" ], "description": "Partecipano al confronto solo i modelli `active` che non sono sospesi, non hanno superato `expires_at` e il cui utente esiste ancora." }, "purged_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "examples": { "One active template": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "vendor_data": "user-42", "source_type": "session_delete", "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f", "retention_policy": "retain_until_user_deleted", "retention_override": null, "retained_at": "2026-08-28T10:15:42.318402Z", "expires_at": "2027-08-28T10:15:42.318402Z", "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e", "retained_by_type": "API_KEY", "instruction_class": "operational_session_delete", "instruction_source": "api", "instruction_id": "post-approval-cleanup-2026-08", "held_out_of_use": false, "status": "active", "purged_at": null } ] } } } } } }, "400": { "description": "Valore del filtro non valido o `retained_to` antecedente a `retained_from`. Errori di validazione indicizzati per campo.", "content": { "application/json": { "examples": { "Bad range": { "value": { "retained_to": [ "Must be on or after retained_from." ] } } } } } }, "403": { "description": "Token utente della Console, oppure la chiave API non è consentita. Questi endpoint accettano solo chiavi API dell'applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/biometric-templates/?vendor_data=user-42&status=active' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.biometric_templates.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.biometricTemplates.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.BiometricTemplates.ListAutoPaging(ctx, didit.BiometricTemplatesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.biometricTemplates().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.biometric_templates.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.BiometricTemplates.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/biometric-templates/count/": { "get": { "summary": "Conta i modelli biometrici conservati", "description": "Un'applicazione che ha aderito mantiene un modello biometrico facciale gestito separatamente e privo di immagini, ancorato all'utente quando una sessione viene eliminata (vedi `DELETE /v3/session/{sessionId}/delete/`). I modelli sono dati biometrici con un `expires_at` finito; non contengono mai immagini, dati di sessione o campi di identità e vengono eliminati definitivamente all'eliminazione dell'utente, alla cancellazione per motivi di privacy, alla scadenza o tramite un'eliminazione definitiva esplicita. Questi endpoint accettano solo chiavi API dell'applicazione (`x-api-key`); i token utente della Business Console vengono rifiutati con `403`.\n\nRestituisce il numero di modelli corrispondenti agli stessi filtri dell'endpoint di elenco. Usalo per verificare quali modelli verrebbero interessati da un'eliminazione definitiva massiva filtrata con `delete_all: true`.", "operationId": "count_biometric_templates", "x-didit-sdk": { "resource": "biometric_templates", "method": "count", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "vendor_data", "required": false, "description": "Corrispondenza di sottostringhe senza distinzione tra maiuscole e minuscole sul `vendor_data` corrente dell'Utente proprietario.", "schema": { "type": "string" } }, { "in": "query", "name": "vendor_user_uuid", "required": false, "description": "Corrispondenza esatta sull'utente proprietario.", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "required": false, "description": "Stato del ciclo di vita. I modelli eliminati definitivamente non vengono mai elencati.", "schema": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed" ] } }, { "in": "query", "name": "source_type", "required": false, "description": "Come è stato creato il modello.", "schema": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ] } }, { "in": "query", "name": "retained_from", "required": false, "description": "Modelli conservati a partire da questa data e ora o successivamente.", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "retained_to", "required": false, "description": "Modelli conservati entro questa data e ora o precedentemente. Non deve essere anteriore a `retained_from` (`400`).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Conteggio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } } }, "examples": { "Count": { "value": { "count": 128 } } } } } }, "400": { "description": "Valore del filtro non valido o `retained_to` antecedente a `retained_from`. Errori di validazione indicizzati per campo.", "content": { "application/json": { "examples": { "Bad range": { "value": { "retained_to": [ "Must be on or after retained_from." ] } } } } } }, "403": { "description": "Token utente della Console, oppure la chiave API non è consentita. Questi endpoint accettano solo chiavi API dell'applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/biometric-templates/count/?status=active' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.count()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.count();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.Count(ctx, didit.BiometricTemplatesCountParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().count();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->count();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.count\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.CountAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/biometric-templates/{template_uuid}/": { "get": { "summary": "Recupera un modello biometrico conservato", "description": "Un'applicazione che ha aderito mantiene un modello biometrico facciale gestito separatamente e privo di immagini, ancorato all'utente quando una sessione viene eliminata (vedere `DELETE /v3/session/{sessionId}/delete/`). I modelli sono dati biometrici con un `expires_at` finito; non contengono mai immagini, dati di sessione o campi di identità e vengono eliminati definitivamente all'eliminazione dell'utente, alla cancellazione per motivi di privacy, alla scadenza o tramite un'eliminazione definitiva esplicita. Questi endpoint accettano solo chiavi API dell'applicazione (`x-api-key`); i token utente della Business Console vengono rifiutati con `403`.\n\nRestituisce un singolo modello. La risposta non include mai un'immagine, un vettore, l'id della sessione eliminata o dati sull'identità.", "operationId": "get_biometric_template", "x-didit-sdk": { "resource": "biometric_templates", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "template_uuid", "required": true, "description": "ID del modello, restituito come `biometric_template_uuid` dagli endpoint di eliminazione della sessione, `biometric_template_id` in una corrispondenza di Ricerca facciale o dall'endpoint di elenco.", "schema": { "type": "string", "format": "uuid", "example": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b" } } ], "responses": { "200": { "description": "Il modello.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID del modello. Generato casualmente; non derivato dalla sessione eliminata o dal relativo volto." }, "vendor_user_uuid": { "type": "string", "format": "uuid", "description": "L'Utente proprietario." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il `vendor_data` corrente dell'Utente, risolto al momento della lettura del modello (mai copiato)." }, "source_type": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ], "description": "Come è stato creato il modello: l'eliminazione di una sessione (API o Console), la finestra di conservazione dei dati automatica dell'applicazione o un backfill gestito da Didit su tua istruzione." }, "provenance_reference": { "type": "string", "format": "uuid", "description": "Riferimento opaco che collega il modello al suo registro di audit. Non è l'ID della sessione eliminata e non può essere ricondotto ad esso." }, "retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "La policy dell'applicazione al momento della conservazione dei dati." }, "retention_override": { "type": "boolean", "nullable": true, "description": "Il valore `retain_face_embeddings` inviato all'eliminazione, oppure `null` quando è stata applicata la policy." }, "retained_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando il modello scade e viene eliminato automaticamente. Sempre impostato." }, "retained_by": { "type": "string", "nullable": true, "description": "Soggetto che ha impartito l'istruzione: l'ID applicazione per le chiavi API, l'ID membro della Console per le azioni della Console, oppure un identificatore `service:` per la conservazione automatica. Mai un indirizzo email." }, "retained_by_type": { "type": "string", "enum": [ "API_KEY", "CONSOLE_USER", "SYSTEM" ] }, "instruction_class": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ] }, "instruction_source": { "type": "string", "enum": [ "api", "console", "automatic_retention", "backfill", "privacy_erasure", "explicit_template_purge", "vendor_user_delete", "expiry", "reconciliation", "migration", "system" ] }, "instruction_id": { "type": "string", "description": "L'`instruction_id` inviato all'eliminazione, oppure un id generato da Didit." }, "held_out_of_use": { "type": "boolean", "description": "`true` solo quando si applica un vincolo di conservazione legale. Un modello soggetto a tale vincolo è escluso da qualsiasi corrispondenza." }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed", "purged" ], "description": "Partecipano al confronto solo i modelli `active` che non sono sospesi, non hanno superato `expires_at` e il cui utente esiste ancora." }, "purged_at": { "type": "string", "format": "date-time", "nullable": true } } }, "examples": { "Active template": { "value": { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "vendor_data": "user-42", "source_type": "session_delete", "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f", "retention_policy": "retain_until_user_deleted", "retention_override": null, "retained_at": "2026-08-28T10:15:42.318402Z", "expires_at": "2027-08-28T10:15:42.318402Z", "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e", "retained_by_type": "API_KEY", "instruction_class": "operational_session_delete", "instruction_source": "api", "instruction_id": "post-approval-cleanup-2026-08", "held_out_of_use": false, "status": "active", "purged_at": null } } } } } }, "403": { "description": "Token utente della Console, oppure la chiave API non è consentita. Questi endpoint accettano solo chiavi API dell'applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Modello sconosciuto, modello di un'altra applicazione o (su `GET`) modello rimosso definitivamente.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Biometric template not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/biometric-templates/9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.retrieve(\n \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.retrieve(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.Retrieve(ctx, \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().retrieve(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->retrieve('9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.retrieve(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.RetrieveAsync(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Elimina definitivamente un modello biometrico conservato", "description": "Un'applicazione che ha aderito mantiene un modello biometrico facciale gestito separatamente e privo di immagini, ancorato all'utente quando una sessione viene eliminata (vedere `DELETE /v3/session/{sessionId}/delete/`). I modelli sono dati biometrici con un `expires_at` finito; non contengono mai immagini, dati di sessione o campi di identità e vengono eliminati definitivamente all'eliminazione dell'utente, alla cancellazione per motivi di privacy, alla scadenza o tramite un'eliminazione definitiva esplicita. Questi endpoint accettano solo chiavi API dell'applicazione (`x-api-key`); i token utente della Business Console vengono rifiutati con `403`.\n\nElimina definitivamente un modello: viene rimosso da ogni tipo di confronto e il modello memorizzato viene cancellato. L'operazione è irreversibile e registrata nel registro di audit con il soggetto che l'ha eseguita.\n\n**Semantica dei nuovi tentativi:** Didit cancella prima il modello memorizzato e solo dopo lo contrassegna come eliminato definitivamente. Se uno store biometrico non è disponibile, la chiamata restituisce `503`, il modello passa a `status: purge_failed` ed è già escluso dai confronti; ripeti la stessa chiamata per completare. Ripetere l'eliminazione definitiva di un modello già eliminato restituisce `already_purged`.\n\nI modelli vengono eliminati definitivamente anche tramite `POST /v3/users/delete/` per l'utente proprietario, tramite qualsiasi eliminazione delle sessioni di quell'utente con `deletion_instruction: privacy_erasure`, e automaticamente a `expires_at`.", "operationId": "purge_biometric_template", "x-didit-sdk": { "resource": "biometric_templates", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "template_uuid", "required": true, "description": "ID del modello, restituito come `biometric_template_uuid` dagli endpoint di eliminazione della sessione, `biometric_template_id` in una corrispondenza di Ricerca facciale o dall'endpoint di elenco.", "schema": { "type": "string", "format": "uuid", "example": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b" } } ], "responses": { "200": { "description": "Esito dell'eliminazione definitiva.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "purged", "already_purged" ] } } }, "examples": { "Purged": { "value": { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "purged" } }, "Already purged": { "value": { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "already_purged" } } } } } }, "403": { "description": "Token utente della Console, oppure la chiave API non è consentita. Questi endpoint accettano solo chiavi API dell'applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Modello sconosciuto, modello di un'altra applicazione o (su `GET`) modello rimosso definitivamente.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Biometric template not found." } } } } } }, "503": { "description": "Un archivio biometrico non era disponibile durante la conservazione o l'eliminazione definitiva di un modello biometrico. Non è stato eliminato nulla; ripeti la stessa richiesta. I nuovi tentativi sono idempotenti e convergono su un unico modello.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Retryable": { "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/biometric-templates/9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.delete(\n \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.delete(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.Delete(ctx, \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().delete(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->delete('9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.delete(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.DeleteAsync(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/biometric-templates/delete/": { "post": { "summary": "Eliminazione massiva dei modelli biometrici conservati", "description": "Un'applicazione abilitata conserva un modello biometrico facciale gestito separatamente e privo di immagini, ancorato all'Utente quando una sessione viene eliminata (vedi `DELETE /v3/session/{sessionId}/delete/`). I modelli sono dati biometrici con una scadenza definita (`expires_at`); non contengono mai immagini, dati di sessione o campi di identità e vengono eliminati all'eliminazione dell'Utente, alla cancellazione per motivi di privacy, alla scadenza o a seguito di un'eliminazione esplicita. Questi endpoint accettano solo chiavi API dell'applicazione (`x-api-key`); i token utente della Business Console vengono rifiutati con `403`.\n\nElimina definitivamente molti modelli in un'unica chiamata, tramite un elenco esplicito di id o con `delete_all: true` opzionalmente ristretto dagli stessi filtri dell'endpoint di elenco. I modelli vengono eliminati uno a uno e ciascun risultato riporta `purged` o `already_purged`. Se un archivio biometrico non è disponibile, la chiamata restituisce `503` al primo modello non riuscito: i modelli eliminati in precedenza nella richiesta rimangono eliminati, quello non riuscito passa a `purge_failed` (già escluso dalla corrispondenza) e la ripetizione della richiesta completa l'operazione.\n\n**`delete_all: true` senza filtri elimina definitivamente ogni modello biometrico nell'applicazione e non può essere annullato.** Esegui prima l'endpoint di conteggio con gli stessi filtri.", "operationId": "bulk_purge_biometric_templates", "x-didit-sdk": { "resource": "biometric_templates", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "Modelli da eliminare definitivamente. Obbligatorio a meno che `delete_all` sia `true`. Gli ID già eliminati vengono segnalati come `already_purged`." }, "delete_all": { "type": "boolean", "default": false, "description": "Quando è `true`, elimina definitivamente ogni modello corrispondente ai filtri sottostanti (tutti i modelli dell'applicazione se non viene specificato alcun filtro). `template_uuids` viene ignorato. Azione irreversibile." }, "vendor_data": { "type": "string", "description": "Solo con `delete_all`: corrispondenza parziale senza distinzione tra maiuscole e minuscole su `vendor_data` dell'Utente proprietario." }, "vendor_user_uuid": { "type": "string", "format": "uuid", "description": "Solo con `delete_all`: corrispondenza esatta sull'Utente proprietario." }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed" ], "description": "Solo con `delete_all`." }, "source_type": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ], "description": "Solo con `delete_all`." }, "retained_from": { "type": "string", "format": "date-time", "description": "Solo con `delete_all`." }, "retained_to": { "type": "string", "format": "date-time", "description": "Solo con `delete_all`. Non deve essere antecedente a `retained_from`." } } }, "examples": { "By id": { "value": { "template_uuids": [ "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" ] } }, "Every template of one User": { "value": { "delete_all": true, "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f" } }, "Every template in the application": { "value": { "delete_all": true } } } } } }, "responses": { "200": { "description": "Esiti di eliminazione per modello.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "purged", "already_purged" ] } } } } } }, "examples": { "Mixed": { "value": { "results": [ { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "purged" }, { "uuid": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "outcome": "already_purged" } ] } } } } } }, "400": { "description": "Errore di validazione — nulla viene rimosso definitivamente.", "content": { "application/json": { "examples": { "Missing selector": { "value": { "template_uuids": [ "This field is required unless delete_all is true." ] } }, "Bad range": { "value": { "retained_to": [ "Must be on or after retained_from." ] } } } } } }, "403": { "description": "Token utente della Console, oppure la chiave API non è consentita. Questi endpoint accettano solo chiavi API dell'applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "503": { "description": "Un archivio biometrico non era disponibile durante la conservazione o l'eliminazione definitiva di un modello biometrico. Non è stato eliminato nulla; ripeti la stessa richiesta. I nuovi tentativi sono idempotenti e convergono su un unico modello.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Retryable": { "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/biometric-templates/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"delete_all\": true, \"vendor_user_uuid\": \"2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.batch_delete(\n template_uuids=[\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.batchDelete({\n template_uuids: [\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.BatchDelete(ctx, didit.BiometricTemplatesBatchDeleteParams{\n\tTemplateUUIDs: didit.Some([]string{\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BiometricTemplatesBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().batchDelete(BiometricTemplatesBatchDeleteParams.builder()\n .templateUuids(List.of(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->batchDelete([\n 'template_uuids' => ['9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b', '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.batch_delete(template_uuids: [\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.BatchDeleteAsync(new BiometricTemplatesBatchDeleteParams\n{\n TemplateUuids = new string[] { \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/kyb/shareholders/": { "post": { "summary": "Azienda nel registro KYB con azionisti (autonoma)", "operationId": "post_v3_kyb_shareholders", "x-didit-sdk": { "resource": "kyb", "method": "list_shareholders", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Recupera il profilo Lite **oltre agli azionisti diretti** (persone fisiche ed entità societarie, con le relative fasce di assetto proprietario) di un candidato restituito da `POST /v3/kyb/search/`.\n\n**Abbinamento alla ricerca.** Passa il `kyb_response_id` del candidato esattamente come restituito da una ricerca della stessa applicazione. Cerca al livello che intendi acquistare (`tier` su `POST /v3/kyb/search/`), poiché la ricerca viene eseguita sulla catena di registri che serve tale livello e una ricerca Lite vuota non è la prova che il registro delle imprese non contenga l'azienda. Quando i dati sull'assetto proprietario del paese si trovano in un altro registro, Didit ritrova l'azienda lì tramite il numero di registrazione, senza costi aggiuntivi.\n\n**Fatturazione.** Fatturato al prezzo Shareholders del paese - vedi [Prezzi dei registri KYB](/it/getting-started/kyb-registry-pricing). Quando il registro delle imprese non contiene record di azionisti per l'azienda (o il paese non offre affatto dati sull'assetto proprietario), viene invece consegnato e fatturato il profilo Lite: leggi `registry_tier_delivered` e `registry_ownership_status`. Il saldo viene verificato rispetto al prezzo Shareholders prima di qualsiasi chiamata al registro (`403` se insufficiente).\n\n**Disponibilità.** Solo v3. Ogni chiamata crea una sessione aziendale (il cui id è il `request_id`).\n\n**Report in sospeso.** Quando un report è ancora in fase di preparazione, o la sezione relativa all'assetto proprietario non è stata ancora recuperata dal registro delle imprese, l'endpoint restituisce 202 Accepted, kyb_registry.fetch_status=pending, kyb_registry.registry_ownership_status=pending e registry_tier_delivered=null. Conserva request_id e chiama GET /v3/session/{request_id}/decision/ finché registry_checks[0].company.fetch_status non viene risolto. Didit completa il report automaticamente e addebita il livello consegnato non appena è pronto. Non ripetere l'acquisto mentre è in sospeso; ogni nuova POST crea una richiesta separata.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistryCandidateRequest" }, "example": { "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/shareholders/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"kyb_response_id\": \"69aeeb95febb0f1704042259\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.list_shareholders(\n kyb_response_id=\"69aeeb95febb0f1704042259\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.listShareholders({\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.ListShareholders(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KYBRegistryCandidateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().listShareholders(KYBRegistryCandidateRequest.builder()\n .kybResponseId(\"69aeeb95febb0f1704042259\")\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->listShareholders([\n 'kyb_response_id' => '69aeeb95febb0f1704042259',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.list_shareholders(\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.ListShareholdersAsync(new KYBRegistryCandidateRequest\n{\n KybResponseId = \"69aeeb95febb0f1704042259\",\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Report aziendale restituito e fatturato al livello consegnato. I report sull'assetto proprietario ancora in fase di elaborazione possono restituire 202; conserva request_id per recuperare la decisione salvata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione aziendale creata per questo recupero. Il record memorizzato (visibile nella console) continua ad aggiornarsi se la ricerca nel registro viene completata dopo la risposta." }, "registry_tier_requested": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "Il livello venduto da questo endpoint: `basic` (Lite) per select, `shareholders`, `ubo`." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "Il livello effettivamente fornito e fatturato. Inferiore a quello richiesto quando i registri del paese non contengono dati sull'assetto proprietario, oppure il registro non ha record sull'assetto proprietario per questa azienda.", "nullable": true }, "kyb_registry": { "type": "object", "description": "Profilo aziendale completo del registro delle imprese.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID Didit per questo record aziendale." }, "node_id": { "type": "string", "example": "feature_kyb_registry" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review" ], "description": "Valutazione di Didit sulla verifica del registro delle imprese (ad es. `In Review` quando l'azienda non è attiva nel registro o non è stato possibile ricavare i dati sull'assetto proprietario)." }, "registry_status": { "type": "string", "nullable": true, "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off", null ], "description": "Stato aziendale normalizzato come riportato dal registro." }, "data_resolved": { "type": "boolean", "description": "`true` quando il registro ha restituito il profilo completo. `false` quando il registro era ancora in elaborazione dopo il polling — il record memorizzato viene completato automaticamente una volta che il registro ha completato l'elaborazione." }, "company_name": { "type": "string", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "example": "00445790" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2.", "example": "GB" }, "region": { "type": "string", "nullable": true, "description": "Codice della suddivisione quando il registro è regionale (ad es. `CA` per `US-CA`); altrimenti vuoto." }, "company_type": { "type": "string", "nullable": true, "example": "Public Limited Company" }, "incorporation_date": { "type": "string", "format": "date", "nullable": true, "example": "1947-11-27" }, "registered_address": { "type": "string", "nullable": true, "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA" }, "tax_number": { "type": "string", "nullable": true, "example": "GB412 8925 93" }, "risk_level": { "type": "string", "nullable": true, "description": "Livello di rischio riportato dal registro delle imprese, se disponibile." }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "Stato di verifica tra giurisdizioni: `verified` quando lo stato nel registro ne attesta la validità operativa (`active`), `failed` quando indica che l'azienda non è più operativa (ad esempio `dissolved`), altrimenti `unknown`. `null` per un'azienda che non proviene da un registro delle imprese e mentre una selezione è ancora `pending`." }, "is_from_registry": { "type": "boolean", "description": "Sempre `true` per questo endpoint — il profilo è stato recuperato da un registro ufficiale." }, "fetch_status": { "type": "string", "enum": [ "pending", "resolved" ], "description": "Ciclo di vita del recupero dal registro delle imprese. Riflesso da `data_resolved`." }, "alternative_names": { "type": "string", "nullable": true, "description": "Denominazioni aziendali alternative, commerciali, precedenti o nella lingua originale sotto forma di testo, se segnalate." }, "nature_of_business": { "type": "string", "nullable": true, "description": "Descrizione dell'attività o codice di classificazione, se segnalato." }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "Importo decimale sotto forma di stringa, se comunicato." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Codice ISO 4217, se indicato." }, "website": { "type": "string", "nullable": true, "example": "https://www.tesco.com/" }, "email": { "type": "string", "nullable": true, "example": "customer.service@tesco.co.uk" }, "phone": { "type": "string", "nullable": true, "example": "03301231688" }, "legal_entity_identifier": { "type": "string", "nullable": true, "description": "LEI, se segnalato." }, "location_of_registration": { "type": "string", "nullable": true, "description": "Registro delle imprese/giurisdizione presso cui l'azienda è registrata, se indicati." }, "vat_number": { "type": "string", "nullable": true, "description": "Partita IVA UE, se raccolta durante il passaggio del registro ospitato o modificata successivamente. Al momento della selezione in genere non è ancora impostata: la validazione della partita IVA e dell'identificativo fiscale viene eseguita quando l'utente finale invia il passaggio del registro nel flusso ospitato." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Risultato della validazione della partita IVA o, qualora non presente, del `tax_number`, al momento dell'invio al registro. `valid` / `invalid`: stabilito dal registro ufficiale del paese (VIES UE, Norvegia, Svizzera, Brasile, Colombia, Costa Rica, Ecuador, Paraguay; per la Polonia anche dal registro IVA nazionale). `format_valid` / `invalid_format`: stabilito dalle regole di formato e cifra di controllo del paese laddove non sia possibile interrogare alcun registro. `could_not_validate`: il registro non era disponibile. `not_applicable`: nessun numero, paese privo di registro o regole, oppure sessione sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "Il numero verificato, così come noto alla fonte (ad esempio la partita IVA derivata da un SIREN francese o un RSIN olandese). `null` quando non è stato eseguito alcun controllo." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "La fonte che ha stabilito `vat_validation_status`: un registro ufficiale, oppure `format_rules`. `null` se non è stato eseguito alcun controllo." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registrato presso la fonte che ha validato il numero, quando ne fornisce uno. Impostato solo quando lo stato è `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Indirizzo registrato presso la fonte che ha convalidato il numero, quando ne comunica uno. Impostato solo quando lo stato è `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp del controllo. `null` se non è stato eseguito alcun controllo." }, "financial_summary": { "type": "object", "nullable": true, "description": "Dettagli sulle azioni/sul capitale riportati dal registro delle imprese (valuta, azioni totali, categorie di azioni), se disponibili." }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MELISSA BETHELL" }, "designation": { "type": "string", "nullable": true, "description": "Denominazione del registro non elaborata (ad es. `Director`, `Secretary`)." }, "role": { "type": "string", "description": "Ruolo normalizzato derivato dalla qualifica. Set completo di 17 valori del modello; l'analisi del registro su questo endpoint genera tipicamente director, non_executive_director, secretary, chairman o company_officer.", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "company_officer", "settlor", "protector", "investor", "other" ] }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "description": "`false` quando il registro contrassegna l'incarico come terminato per dimissioni." }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ], "description": "Stato di una sessione KYC associata, se ne è stata avviata una per questo funzionario. `null` altrimenti." }, "kyc_session_url": { "type": "string", "nullable": true, "description": "URL di verifica della sessione KYC associata, se esistente." }, "first_name": { "type": "string", "nullable": true, "description": "Nome quando esplicitamente riportato dal registro; non dedotto dal nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Cognome quando esplicitamente riportato dal registro." }, "address": { "type": "string", "nullable": true, "description": "Indirizzo dell'amministratore riportato dal registro." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina dell'amministratore.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data di fine dell'incarico, quando indicata.", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa comunicata dal registro delle imprese. Null se sono noti solo l'anno o il mese di nascita.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Anno di nascita riportato dal registro delle imprese, anche quando la data completa non è disponibile." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mese di nascita riportato dal registro delle imprese. Null se è noto solo l'anno." } } }, "description": "Amministratori, segretari e altri dirigenti estratti dal registro." }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se il titolare è una persona fisica o un'entità aziendale." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Ruoli normalizzati (ad es. `ubo`, `shareholder`)." }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferiore della fascia di assetto proprietario riportata dal registro (ad es. `25%`)." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superiore della fascia di assetto proprietario riportata dal registro delle imprese." }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ] }, "kyc_session_url": { "type": "string", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "Percentuale di assetto proprietario analizzata (limite massimo, con fallback al limite minimo)." }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa, se indicata.", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina, se comunicata.", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } }, "description": "Titolari effettivi / persone con controllo significativo estratti dal registro. Può essere vuoto se il registro non espone l'assetto proprietario." }, "addresses": { "type": "array", "nullable": true, "description": "Ogni indirizzo indicato dal registro, in un formato canonico. Null se non ne indica alcuno.", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "Le attività con cui il registro classifica l'azienda, in formato canonico. Null quando non ne viene indicata alcuna.", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Date di deposito presso il registro delle imprese, se disponibili. Le dichiarazioni annuali e le assemblee generali utilizzano last_annual_return_date e last_agm_date; sono distinte dai bilanci di esercizio." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "description": "Sempre `null` su questo endpoint (utilizzato dal flusso KYB ospitato quando gli utenti finali modificano i dati del registro)." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Sempre `null` su questo endpoint." }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Impostato quando un revisore della console modifica il record in un secondo momento." }, "is_editable": { "type": "boolean", "description": "Indica se i dati provenienti dal registro delle imprese possono ancora essere modificati nel flusso ospitato o nella console." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "Corrisponde al valore di primo livello `registry_tier_delivered`.", "nullable": true }, "registry_ownership_status": { "type": "string", "nullable": true, "enum": [ "not_requested", "delivered", "not_held", "unavailable", "pending", null ], "description": "`delivered` quando i dati sull'assetto proprietario sono stati restituiti, `not_held` quando il registro delle imprese ha risposto e non elenca questa azienda (vedi `registry_data.ownership_error`), `unavailable` quando è stato richiesto un livello di assetto proprietario ma il registro non ne disponeva per questa azienda o non è stato possibile interrogarlo (vedi `registry_data.ownership_error`), `pending` quando la sezione sull'assetto proprietario non è stata ancora recuperata dal registro e Didit la sta ancora completando, `not_requested` per il livello Lite." }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "Il livello del registro ordinato dal workflow: `basic`, `shareholders` o `ubo`. Anche in `ownership.tier_requested`." }, "registry_monitoring": { "type": "object", "nullable": true, "description": "Il monitoraggio del registro più recente per l'azienda, o `null` quando non ne esiste alcuno.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "I campi aziendali che il monitor monitora." } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato." }, "metadata": { "type": "object", "nullable": true, "description": "Eco del `metadata` inviato." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved company": { "summary": "Profilo completo del registro delle imprese (elenco degli amministratori troncato per brevità)", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d", "node_id": "feature_kyb_registry", "status": "In Review", "registry_status": "active", "data_resolved": true, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": "", "company_type": "Public Limited Company", "incorporation_date": "1947-11-27", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "tax_number": "GB412 8925 93", "risk_level": "low risk", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": "https://www.tesco.com/", "email": "customer.service@tesco.co.uk", "phone": "03301231688", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": { "currency": "Pound (£)", "total_number_of_shares": "8174378721", "meta_detail": { "Class_Of_Share": "Ordinary" } }, "officers": [ { "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b", "name": "CHRISTOPHER JON TAYLOR", "designation": "Secretary", "role": "secretary", "nationality": null, "is_active": true, "kyc_status": null, "kyc_session_url": null }, { "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c", "name": "MELISSA BETHELL", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": null, "kyc_session_url": null } ], "beneficial_owners": [], "addresses": [ { "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "type": "legal_entity_registry_address", "description": "registered office address" } ], "industries": null, "accounts": { "last_account": "26 February 2025", "next_account": "26 February 2026", "due_by_date": "26 August 2026" }, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } } } } } }, "400": { "description": "Errore di validazione. I problemi a livello di campo utilizzano l'involucro standard di DRF.", "content": { "application/json": { "examples": { "Missing kyb_response_id": { "summary": "`kyb_response_id` è obbligatorio", "value": { "kyb_response_id": [ "This field is required." ] } }, "save_api_request=false rejected": { "summary": "Le selezioni vengono sempre salvate in modo persistente", "value": { "save_api_request": [ "KYB registry select must be saved so billing and retrieval can be tracked." ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi screening o chiamata al provider.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "202": { "description": "Report accettato e ancora in elaborazione. Quando un report è ancora in fase di preparazione, l'endpoint restituisce 202 Accepted, kyb_registry.fetch_status=pending e registry_tier_delivered=null. Conserva il request_id ed esegui GET /v3/session/{request_id}/decision/ finché registry_checks[0].company.fetch_status non è risolto. Didit completa il report automaticamente e addebita il livello consegnato non appena è pronto. Non ripetere l'acquisto mentre è in sospeso; ogni nuova POST crea una richiesta separata.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1kyb~1shareholders~1/post/responses/200/content/application~1json/schema" }, "examples": { "Pending (registry still resolving)": { "summary": "Il report sull'assetto proprietario è ancora in elaborazione; recupera la decisione salvata", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d", "node_id": "feature_kyb_registry", "status": "Not Finished", "registry_status": null, "data_resolved": false, "company_name": "Example Holdings Limited", "registration_number": "12345678", "country_code": "HK", "region": null, "company_type": null, "incorporation_date": null, "registered_address": null, "tax_number": null, "risk_level": null, "verification_status": null, "is_from_registry": true, "fetch_status": "pending", "alternative_names": null, "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": {}, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true, "registry_tier_delivered": null, "registry_ownership_status": "pending" }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00", "registry_tier_delivered": null, "registry_tier_requested": "shareholders" } } } } } } } } }, "/v3/kyb/ubo/": { "post": { "summary": "Azienda nel registro KYB con titolari effettivi (autonoma)", "operationId": "post_v3_kyb_ubo", "x-didit-sdk": { "resource": "kyb", "method": "list_ubos", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "Recupera il profilo Lite, gli azionisti diretti **e i titolari effettivi** individuati attraverso la catena dell'assetto proprietario (`registry_data.ubo_resolution` include la catena delle controllanti societarie) di un candidato restituito da `POST /v3/kyb/search/`.\n\n**Abbinamento alla ricerca.** Passa il `kyb_response_id` del candidato esattamente come restituito da una ricerca della stessa applicazione. Cerca al livello che intendi acquistare (`tier` su `POST /v3/kyb/search/`), poiché la ricerca viene eseguita sulla catena di registri che serve tale livello e una ricerca Lite vuota non è la prova che il registro delle imprese non contenga l'azienda. Quando i dati sull'assetto proprietario del paese si trovano in un altro registro, Didit ritrova l'azienda lì tramite il numero di registrazione, senza costi aggiuntivi.\n\n**Fatturazione.** Fatturato al prezzo UBO del paese - vedi [Prezzi dei registri KYB](/it/getting-started/kyb-registry-pricing). Il livello consegnato è il più alto che il paese e il registro delle imprese possano fornire: Shareholders quando il report elaborato non indica alcuna persona fisica come titolare effettivo, Lite quando non è presente alcun record relativo all'assetto proprietario; `registry_tier_delivered` indica quale livello è stato fatturato. Il saldo viene verificato rispetto al prezzo UBO prima di qualsiasi chiamata al registro (`403` se insufficiente).\n\n**Disponibilità.** Solo v3. Ogni chiamata crea una sessione aziendale (il cui id è il `request_id`).\n\n**Report in sospeso.** Quando un report è ancora in fase di preparazione, o la sezione relativa all'assetto proprietario non è stata ancora recuperata dal registro delle imprese, l'endpoint restituisce 202 Accepted, kyb_registry.fetch_status=pending, kyb_registry.registry_ownership_status=pending e registry_tier_delivered=null. Conserva request_id e chiama GET /v3/session/{request_id}/decision/ finché registry_checks[0].company.fetch_status non viene risolto. Didit completa il report automaticamente e addebita il livello consegnato non appena è pronto. Non ripetere l'acquisto mentre è in sospeso; ogni nuova POST crea una richiesta separata.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistryCandidateRequest" }, "example": { "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/ubo/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"kyb_response_id\": \"69aeeb95febb0f1704042259\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.list_ubos(\n kyb_response_id=\"69aeeb95febb0f1704042259\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.listUbos({\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.ListUBOs(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KYBRegistryCandidateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().listUbos(KYBRegistryCandidateRequest.builder()\n .kybResponseId(\"69aeeb95febb0f1704042259\")\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->listUbos([\n 'kyb_response_id' => '69aeeb95febb0f1704042259',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.list_ubos(\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.ListUbosAsync(new KYBRegistryCandidateRequest\n{\n KybResponseId = \"69aeeb95febb0f1704042259\",\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Report aziendale restituito e fatturato al livello consegnato. I report sull'assetto proprietario ancora in fase di elaborazione possono restituire 202; conserva request_id per recuperare la decisione salvata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione aziendale creata per questo recupero. Il record memorizzato (visibile nella console) continua ad aggiornarsi se la ricerca nel registro viene completata dopo la risposta." }, "registry_tier_requested": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "Il livello venduto da questo endpoint: `basic` (Lite) per select, `shareholders`, `ubo`." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "Il livello effettivamente fornito e fatturato. Inferiore a quello richiesto quando i registri del paese non contengono dati sull'assetto proprietario, quando il registro non ha record sull'assetto proprietario per questa azienda, oppure quando il report risultante da una richiesta `ubo` non indica alcuna persona fisica come titolare effettivo.", "nullable": true }, "kyb_registry": { "type": "object", "description": "Profilo aziendale completo del registro delle imprese.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID Didit per questo record aziendale." }, "node_id": { "type": "string", "example": "feature_kyb_registry" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review" ], "description": "Valutazione di Didit sulla verifica del registro delle imprese (ad es. `In Review` quando l'azienda non è attiva nel registro o non è stato possibile ricavare i dati sull'assetto proprietario)." }, "registry_status": { "type": "string", "nullable": true, "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off", null ], "description": "Stato aziendale normalizzato come riportato dal registro." }, "data_resolved": { "type": "boolean", "description": "`true` quando il registro ha restituito il profilo completo. `false` quando il registro era ancora in elaborazione dopo il polling — il record memorizzato viene completato automaticamente una volta che il registro ha completato l'elaborazione." }, "company_name": { "type": "string", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "example": "00445790" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2.", "example": "GB" }, "region": { "type": "string", "nullable": true, "description": "Codice della suddivisione quando il registro è regionale (ad es. `CA` per `US-CA`); altrimenti vuoto." }, "company_type": { "type": "string", "nullable": true, "example": "Public Limited Company" }, "incorporation_date": { "type": "string", "format": "date", "nullable": true, "example": "1947-11-27" }, "registered_address": { "type": "string", "nullable": true, "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA" }, "tax_number": { "type": "string", "nullable": true, "example": "GB412 8925 93" }, "risk_level": { "type": "string", "nullable": true, "description": "Livello di rischio riportato dal registro delle imprese, se disponibile." }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "Stato di verifica tra giurisdizioni: `verified` quando lo stato nel registro ne attesta la validità operativa (`active`), `failed` quando indica che l'azienda non è più operativa (ad esempio `dissolved`), altrimenti `unknown`. `null` per un'azienda che non proviene da un registro delle imprese e mentre una selezione è ancora `pending`." }, "is_from_registry": { "type": "boolean", "description": "Sempre `true` per questo endpoint — il profilo è stato recuperato da un registro ufficiale." }, "fetch_status": { "type": "string", "enum": [ "pending", "resolved" ], "description": "Ciclo di vita del recupero dal registro delle imprese. Riflesso da `data_resolved`." }, "alternative_names": { "type": "string", "nullable": true, "description": "Denominazioni aziendali alternative, commerciali, precedenti o nella lingua originale sotto forma di testo, se segnalate." }, "nature_of_business": { "type": "string", "nullable": true, "description": "Descrizione dell'attività o codice di classificazione, se segnalato." }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "Importo decimale sotto forma di stringa, se comunicato." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Codice ISO 4217, se indicato." }, "website": { "type": "string", "nullable": true, "example": "https://www.tesco.com/" }, "email": { "type": "string", "nullable": true, "example": "customer.service@tesco.co.uk" }, "phone": { "type": "string", "nullable": true, "example": "03301231688" }, "legal_entity_identifier": { "type": "string", "nullable": true, "description": "LEI, se segnalato." }, "location_of_registration": { "type": "string", "nullable": true, "description": "Registro delle imprese/giurisdizione presso cui l'azienda è registrata, se indicati." }, "vat_number": { "type": "string", "nullable": true, "description": "Partita IVA UE, se raccolta durante il passaggio del registro ospitato o modificata successivamente. Al momento della selezione in genere non è ancora impostata: la validazione della partita IVA e dell'identificativo fiscale viene eseguita quando l'utente finale invia il passaggio del registro nel flusso ospitato." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Risultato della validazione della partita IVA o, qualora non presente, del `tax_number`, al momento dell'invio al registro. `valid` / `invalid`: stabilito dal registro ufficiale del paese (VIES UE, Norvegia, Svizzera, Brasile, Colombia, Costa Rica, Ecuador, Paraguay; per la Polonia anche dal registro IVA nazionale). `format_valid` / `invalid_format`: stabilito dalle regole di formato e cifra di controllo del paese laddove non sia possibile interrogare alcun registro. `could_not_validate`: il registro non era disponibile. `not_applicable`: nessun numero, paese privo di registro o regole, oppure sessione sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "Il numero verificato, così come noto alla fonte (ad esempio la partita IVA derivata da un SIREN francese o un RSIN olandese). `null` quando non è stato eseguito alcun controllo." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "La fonte che ha stabilito `vat_validation_status`: un registro ufficiale, oppure `format_rules`. `null` se non è stato eseguito alcun controllo." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registrato presso la fonte che ha validato il numero, quando ne fornisce uno. Impostato solo quando lo stato è `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Indirizzo registrato presso la fonte che ha convalidato il numero, quando ne comunica uno. Impostato solo quando lo stato è `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp del controllo. `null` se non è stato eseguito alcun controllo." }, "financial_summary": { "type": "object", "nullable": true, "description": "Dettagli sulle azioni/sul capitale riportati dal registro delle imprese (valuta, azioni totali, categorie di azioni), se disponibili." }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MELISSA BETHELL" }, "designation": { "type": "string", "nullable": true, "description": "Denominazione del registro non elaborata (ad es. `Director`, `Secretary`)." }, "role": { "type": "string", "description": "Ruolo normalizzato derivato dalla qualifica. Set completo di 17 valori del modello; l'analisi del registro su questo endpoint genera tipicamente director, non_executive_director, secretary, chairman o company_officer.", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "company_officer", "settlor", "protector", "investor", "other" ] }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "description": "`false` quando il registro contrassegna l'incarico come terminato per dimissioni." }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ], "description": "Stato di una sessione KYC associata, se ne è stata avviata una per questo funzionario. `null` altrimenti." }, "kyc_session_url": { "type": "string", "nullable": true, "description": "URL di verifica della sessione KYC associata, se esistente." }, "first_name": { "type": "string", "nullable": true, "description": "Nome quando esplicitamente riportato dal registro; non dedotto dal nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Cognome quando esplicitamente riportato dal registro." }, "address": { "type": "string", "nullable": true, "description": "Indirizzo dell'amministratore riportato dal registro." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina dell'amministratore.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data di fine dell'incarico, quando indicata.", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa comunicata dal registro delle imprese. Null se sono noti solo l'anno o il mese di nascita.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Anno di nascita riportato dal registro delle imprese, anche quando la data completa non è disponibile." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mese di nascita riportato dal registro delle imprese. Null se è noto solo l'anno." } } }, "description": "Amministratori, segretari e altri dirigenti estratti dal registro." }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se il titolare è una persona fisica o un'entità aziendale." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Ruoli normalizzati (ad es. `ubo`, `shareholder`)." }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferiore della fascia di assetto proprietario riportata dal registro (ad es. `25%`)." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superiore della fascia di assetto proprietario riportata dal registro delle imprese." }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ] }, "kyc_session_url": { "type": "string", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "Percentuale di assetto proprietario analizzata (limite massimo, con fallback al limite minimo)." }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa, se indicata.", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina, se comunicata.", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } }, "description": "Titolari effettivi / persone con controllo significativo estratti dal registro. Può essere vuoto se il registro non espone l'assetto proprietario." }, "addresses": { "type": "array", "nullable": true, "description": "Ogni indirizzo indicato dal registro, in un formato canonico. Null se non ne indica alcuno.", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "Le attività con cui il registro classifica l'azienda, in formato canonico. Null quando non ne viene indicata alcuna.", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Date di deposito presso il registro delle imprese, se disponibili. Le dichiarazioni annuali e le assemblee generali utilizzano last_annual_return_date e last_agm_date; sono distinte dai bilanci di esercizio." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "description": "Sempre `null` su questo endpoint (utilizzato dal flusso KYB ospitato quando gli utenti finali modificano i dati del registro)." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Sempre `null` su questo endpoint." }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Impostato quando un revisore della console modifica il record in un secondo momento." }, "is_editable": { "type": "boolean", "description": "Indica se i dati provenienti dal registro delle imprese possono ancora essere modificati nel flusso ospitato o nella console." }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "Corrisponde al valore di primo livello `registry_tier_delivered`.", "nullable": true }, "registry_ownership_status": { "type": "string", "nullable": true, "enum": [ "not_requested", "delivered", "not_held", "unavailable", "pending", null ], "description": "`delivered` quando i dati sull'assetto proprietario sono stati restituiti, `not_held` quando il registro delle imprese ha risposto e non elenca questa azienda (vedi `registry_data.ownership_error`), `unavailable` quando è stato richiesto un livello di assetto proprietario ma il registro non ne disponeva per questa azienda o non è stato possibile interrogarlo (vedi `registry_data.ownership_error`), `pending` quando la sezione sull'assetto proprietario non è stata ancora recuperata dal registro e Didit la sta ancora completando, `not_requested` per il livello Lite." }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "Il livello del registro ordinato dal workflow: `basic`, `shareholders` o `ubo`. Anche in `ownership.tier_requested`." }, "registry_monitoring": { "type": "object", "nullable": true, "description": "Il monitoraggio del registro più recente per l'azienda, o `null` quando non ne esiste alcuno.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "I campi aziendali che il monitor monitora." } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato." }, "metadata": { "type": "object", "nullable": true, "description": "Eco del `metadata` inviato." }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved company": { "summary": "Profilo completo del registro delle imprese (elenco degli amministratori troncato per brevità)", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d", "node_id": "feature_kyb_registry", "status": "In Review", "registry_status": "active", "data_resolved": true, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": "", "company_type": "Public Limited Company", "incorporation_date": "1947-11-27", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "tax_number": "GB412 8925 93", "risk_level": "low risk", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": "https://www.tesco.com/", "email": "customer.service@tesco.co.uk", "phone": "03301231688", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": { "currency": "Pound (£)", "total_number_of_shares": "8174378721", "meta_detail": { "Class_Of_Share": "Ordinary" } }, "officers": [ { "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b", "name": "CHRISTOPHER JON TAYLOR", "designation": "Secretary", "role": "secretary", "nationality": null, "is_active": true, "kyc_status": null, "kyc_session_url": null }, { "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c", "name": "MELISSA BETHELL", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": null, "kyc_session_url": null } ], "beneficial_owners": [], "addresses": [ { "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "type": "legal_entity_registry_address", "description": "registered office address" } ], "industries": null, "accounts": { "last_account": "26 February 2025", "next_account": "26 February 2026", "due_by_date": "26 August 2026" }, "registry_data": { "ubo_resolution": { "parent_chain": [], "subsidiaries": [], "unresolved": [] } }, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } } } } } }, "400": { "description": "Errore di validazione. I problemi a livello di campo utilizzano l'involucro standard di DRF.", "content": { "application/json": { "examples": { "Missing kyb_response_id": { "summary": "`kyb_response_id` è obbligatorio", "value": { "kyb_response_id": [ "This field is required." ] } }, "save_api_request=false rejected": { "summary": "Le selezioni vengono sempre salvate in modo persistente", "value": { "save_api_request": [ "KYB registry select must be saved so billing and retrieval can be tracked." ] } } } } } }, "403": { "description": "Autorizzazione negata. Restituito quando l'intestazione `x-api-key` è mancante e anche quando il saldo dell'organizzazione chiamante non è sufficiente a coprire la chiamata; una chiave errata, revocata o scaduta restituisce `401`. Una chiave mancante restituisce `403` con `{\"detail\": ...}`; una chiave errata, revocata o scaduta restituisce `401`. Crediti insufficienti restituiscono `403` con `{\"error\": ...}` prima che avvenga qualsiasi screening o chiamata al provider.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida/revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire la chiamata", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "Limite di frequenza superato. Gli endpoint POST/PATCH/DELETE condividono un budget di 300 richieste di scrittura al minuto per chiave API (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600). La risposta contiene le intestazioni `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`.", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "Più di 300 richieste di scrittura nel minuto corrente", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "202": { "description": "Report accettato e ancora in elaborazione. Quando un report è ancora in fase di preparazione, l'endpoint restituisce 202 Accepted, kyb_registry.fetch_status=pending e registry_tier_delivered=null. Conserva il request_id ed esegui GET /v3/session/{request_id}/decision/ finché registry_checks[0].company.fetch_status non è risolto. Didit completa il report automaticamente e addebita il livello consegnato non appena è pronto. Non ripetere l'acquisto mentre è in sospeso; ogni nuova POST crea una richiesta separata.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1kyb~1ubo~1/post/responses/200/content/application~1json/schema" }, "examples": { "Pending (registry still resolving)": { "summary": "Il report sull'assetto proprietario è ancora in elaborazione; recupera la decisione salvata", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d", "node_id": "feature_kyb_registry", "status": "Not Finished", "registry_status": null, "data_resolved": false, "company_name": "Example Holdings Limited", "registration_number": "12345678", "country_code": "HK", "region": null, "company_type": null, "incorporation_date": null, "registered_address": null, "tax_number": null, "risk_level": null, "verification_status": null, "is_from_registry": true, "fetch_status": "pending", "alternative_names": null, "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": {}, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true, "registry_tier_delivered": null, "registry_ownership_status": "pending" }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00", "registry_tier_delivered": null, "registry_tier_requested": "ubo" } } } } } } } } }, "/v3/id-verification/wallets/": { "get": { "operationId": "list_wallets", "x-didit-sdk": { "resource": "id_wallets", "method": "list", "auth": "api_key", "server": true }, "description": "Ogni wallet Digital ID con il rispettivo endpoint di avvio, i paesi, i campi obbligatori e l'indicazione se questa applicazione può avviarlo ora in questo ambiente. Essere presente nell'elenco non significa essere attivo in produzione.", "summary": "Elenca i wallet di Digital ID", "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletCatalogResponse" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenziali mancanti (x-api-key o Authorization: Bearer)." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request GET \\\n --url https://verification.didit.me/v3/id-verification/wallets/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.list()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.list();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.List(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().list();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->list();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.list\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.ListAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/verifications/{request_id}/": { "get": { "operationId": "get_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "retrieve_verification", "auth": "api_key", "server": true }, "description": "Stato e risultato di una verifica del wallet: l'identità normalizzata e gli attributi propri del wallet una volta verificati, il codice di errore una volta rifiutata, l'azione successiva finché è in sospeso. Una verifica oltre expires_at ha esito timeout.", "summary": "Recupera una verifica del wallet", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "Il request_id restituito dall'endpoint di avvio.", "required": true } ], "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "ftn", "name": "Finnish Trust Network", "issuing_authority": "Finnish banks and mobile operators (FTN)" }, "country": "FIN", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenziali mancanti (x-api-key o Authorization: Bearer)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore not_found: nessuna verifica wallet di questa applicazione ha questo request_id." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request GET \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.retrieve_verification(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.retrieveVerification(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.RetrieveVerification(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().retrieveVerification(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->retrieveVerification('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.retrieve_verification(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.RetrieveVerificationAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/verifications/{request_id}/poll/": { "post": { "operationId": "poll_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "poll_verification", "auth": "api_key", "server": true }, "description": "Smart-ID e Mobile-ID: chiedi al provider se l'utente ha confermato, rifiutato o lasciato scadere la richiesta, e verifica l'identità firmata in caso di conferma. I wallet basati su reindirizzamento completano l'operazione tramite il browser dell'utente, quindi per essi questa chiamata si limita a leggere la verifica. Restituisce la verifica nello stato in cui si trova successivamente.", "summary": "Eseguire il polling di una verifica del wallet", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "Il request_id restituito dall'endpoint di avvio.", "required": true } ], "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "smart_id", "name": "Smart-ID", "issuing_authority": "SK ID Solutions" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "in_app", "simulated": true, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "confirm_in_app", "verification_code": "1234", "poll_interval_seconds": 2 }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenziali mancanti (x-api-key o Authorization: Bearer)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore not_found: nessuna verifica wallet di questa applicazione ha questo request_id." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/poll/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.poll_verification(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.pollVerification(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.PollVerification(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().pollVerification(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->pollVerification('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.poll_verification(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.PollVerificationAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/verifications/{request_id}/cancel/": { "post": { "operationId": "cancel_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "cancel_verification", "auth": "api_key", "server": true }, "description": "Revoca una verifica in sospeso: viene rifiutata come annullata e mai fatturata. Una verifica già decisa viene restituita invariata. Smart-ID e Mobile-ID: una cancellazione che arriva mentre un polling sta verificando l'accesso attende alcuni secondi per tale polling, quindi la rifiuta, oppure la restituisce verificata se l'utente aveva già confermato. Una verifica che l'utente sta completando in questo momento non può essere annullata (409 verification_in_progress con Retry-After): riprova dopo tale numero di secondi per leggerne l'esito.", "summary": "Annulla una verifica del wallet", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "Il request_id restituito dall'endpoint di avvio.", "required": true } ], "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "ftn", "name": "Finnish Trust Network", "issuing_authority": "Finnish banks and mobile operators (FTN)" }, "country": "FIN", "status": "Declined", "outcome": "cancelled", "error": "cancelled_by_customer", "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": null, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenziali mancanti (x-api-key o Authorization: Bearer)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore not_found: nessuna verifica wallet di questa applicazione ha questo request_id." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore verification_in_progress: l'utente sta completando questo accesso in questo momento. L'intestazione Retry-After indica quando riprovare; il nuovo tentativo restituisce la verifica decisa." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/cancel/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.cancel_verification(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.cancelVerification(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.CancelVerification(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().cancelVerification(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->cancelVerification('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.cancel_verification(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.CancelVerificationAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/mitid/": { "post": { "operationId": "start_mitid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_mitid", "auth": "api_key", "server": true }, "description": "Avvia un accesso MitID (Agenzia danese per il governo digitale; DNK) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=redirect con l'URL a cui inviare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ottengono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica MitID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartRequest" }, "example": { "country": "DNK", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "mitid", "name": "MitID", "issuing_authority": "Danish Agency for Digital Government" }, "country": "DNK", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/mitid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"DNK\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_mitid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"DNK\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startMitid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DNK\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartMitid(ctx, didit.IDWalletsStartMitidParams{\n\tBody: didit.DigitalIDWalletAPIMitidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIMitidWalletVerificationStartCountryEnum(\"DNK\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiMitidWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiMitidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startMitid(DigitalIdWalletApiMitidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiMitidWalletVerificationStartCountryEnum.of(\"DNK\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startMitid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'DNK',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_mitid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DNK\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartMitidAsync(new DigitalIdWalletApiMitidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiMitidWalletVerificationStartCountryEnum(\"DNK\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "mitid" } }, "/v3/id-verification/wallets/bankid-se/": { "post": { "operationId": "start_bankid_se_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_bankid_se", "auth": "api_key", "server": true }, "description": "Avvia un accesso BankID (SWE) (Finansiell ID-Teknik / consorzio bancario; SWE) senza alcun workflow. Addebitato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui indirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il fornitore.", "summary": "Avvia la verifica BankID (SWE)", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidSeWalletVerificationStartRequest" }, "example": { "country": "SWE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidSeWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidSeWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "bankid_se", "name": "BankID", "issuing_authority": "Finansiell ID-Teknik / bank consortium" }, "country": "SWE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/bankid-se/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"SWE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_bankid_se(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"SWE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBankidSe({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBankidSe(ctx, didit.IDWalletsStartBankidSeParams{\n\tBody: didit.DigitalIDWalletAPIBankidSeWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryEe9enum(\"SWE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBankidSeWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryEe9Enum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBankidSe(DigitalIdWalletApiBankidSeWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryEe9Enum.of(\"SWE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBankidSe([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'SWE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_bankid_se(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBankidSeAsync(new DigitalIdWalletApiBankidSeWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryEe9Enum(\"SWE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "bankid_se" } }, "/v3/id-verification/wallets/bankid-no/": { "post": { "operationId": "start_bankid_no_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_bankid_no", "auth": "api_key", "server": true }, "description": "Avvia un accesso BankID (NOR) (BankID BankAxept AS; NOR) senza alcun workflow. Addebitato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui indirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il fornitore.", "summary": "Avvia la verifica BankID (NOR)", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidNoWalletVerificationStartRequest" }, "example": { "country": "NOR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidNoWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidNoWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "bankid_no", "name": "BankID", "issuing_authority": "BankID BankAxept AS" }, "country": "NOR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/bankid-no/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NOR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_bankid_no(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NOR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBankidNo({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBankidNo(ctx, didit.IDWalletsStartBankidNoParams{\n\tBody: didit.DigitalIDWalletAPIBankidNoWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryAfcEnum(\"NOR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBankidNoWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryAfcEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBankidNo(DigitalIdWalletApiBankidNoWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryAfcEnum.of(\"NOR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBankidNo([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NOR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_bankid_no(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBankidNoAsync(new DigitalIdWalletApiBankidNoWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryAfcEnum(\"NOR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "bankid_no" } }, "/v3/id-verification/wallets/vipps/": { "post": { "operationId": "start_vipps_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_vipps", "auth": "api_key", "server": true }, "description": "Avvia un accesso Vipps (Vipps MobilePay / BankID NO; NOR) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui reindirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni in sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica Vipps", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiVippsWalletVerificationStartRequest" }, "example": { "country": "NOR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiVippsWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiVippsWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "vipps", "name": "Vipps", "issuing_authority": "Vipps MobilePay / BankID NO" }, "country": "NOR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/vipps/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NOR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_vipps(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NOR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startVipps({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartVipps(ctx, didit.IDWalletsStartVippsParams{\n\tBody: didit.DigitalIDWalletAPIVippsWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryAfcEnum(\"NOR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountryAfcEnum;\nimport me.didit.types.DigitalIdWalletApiVippsWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startVipps(DigitalIdWalletApiVippsWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryAfcEnum.of(\"NOR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startVipps([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NOR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_vipps(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartVippsAsync(new DigitalIdWalletApiVippsWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryAfcEnum(\"NOR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "vipps" } }, "/v3/id-verification/wallets/buypass/": { "post": { "operationId": "start_buypass_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_buypass", "auth": "api_key", "server": true }, "description": "Avvia un accesso Buypass ID (Buypass AS; NOR) senza alcun workflow. Addebitato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui indirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il fornitore.", "summary": "Avvia la verifica Buypass ID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBuypassWalletVerificationStartRequest" }, "example": { "country": "NOR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBuypassWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBuypassWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "buypass", "name": "Buypass ID", "issuing_authority": "Buypass AS" }, "country": "NOR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/buypass/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NOR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_buypass(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NOR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBuypass({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBuypass(ctx, didit.IDWalletsStartBuypassParams{\n\tBody: didit.DigitalIDWalletAPIBuypassWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryAfcEnum(\"NOR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBuypassWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryAfcEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBuypass(DigitalIdWalletApiBuypassWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryAfcEnum.of(\"NOR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBuypass([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NOR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_buypass(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBuypassAsync(new DigitalIdWalletApiBuypassWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryAfcEnum(\"NOR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "buypass" } }, "/v3/id-verification/wallets/itsme/": { "post": { "operationId": "start_itsme_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_itsme", "auth": "api_key", "server": true }, "description": "Avvia un accesso itsme (Belgian Mobile ID; BEL, LUX, NLD) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=redirect con l'URL a cui inviare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ottengono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia verifica itsme", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartRequest" }, "example": { "country": "BEL", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "itsme", "name": "itsme", "issuing_authority": "Belgian Mobile ID" }, "country": "BEL", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/itsme/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"BEL\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_itsme(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"BEL\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startItsme({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BEL\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartItsme(ctx, didit.IDWalletsStartItsmeParams{\n\tBody: didit.DigitalIDWalletAPIItsmeWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIItsmeWalletVerificationStartCountryEnum(\"BEL\"),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiItsmeWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startItsme(DigitalIdWalletApiItsmeWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum.of(\"BEL\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startItsme([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'BEL',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_itsme(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BEL\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartItsmeAsync(new DigitalIdWalletApiItsmeWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"BEL\",\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "itsme" } }, "/v3/id-verification/wallets/idin/": { "post": { "operationId": "start_idin_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_idin", "auth": "api_key", "server": true }, "description": "Avvia un accesso iDIN (banche olandesi (Currence iDIN); NLD) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=redirect con l'URL a cui inviare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ottengono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia verifica iDIN", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartRequest" }, "example": { "country": "NLD", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "idin", "name": "iDIN", "issuing_authority": "Dutch banks (Currence iDIN)" }, "country": "NLD", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/idin/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NLD\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_idin(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NLD\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startIdin({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NLD\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartIdin(ctx, didit.IDWalletsStartIdinParams{\n\tBody: didit.DigitalIDWalletAPIIdinWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIIdinWalletVerificationStartCountryEnum(\"NLD\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiIdinWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiIdinWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startIdin(DigitalIdWalletApiIdinWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiIdinWalletVerificationStartCountryEnum.of(\"NLD\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startIdin([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NLD',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_idin(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NLD\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartIdinAsync(new DigitalIdWalletApiIdinWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiIdinWalletVerificationStartCountryEnum(\"NLD\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "idin" } }, "/v3/id-verification/wallets/ftn/": { "post": { "operationId": "start_ftn_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_ftn", "auth": "api_key", "server": true }, "description": "Avvia un accesso Finnish Trust Network (banche e operatori mobili finlandesi (FTN); FIN) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=redirect con l'URL a cui inviare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ottengono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica Finnish Trust Network", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartRequest" }, "example": { "country": "FIN", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "ftn", "name": "Finnish Trust Network", "issuing_authority": "Finnish banks and mobile operators (FTN)" }, "country": "FIN", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"FIN\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_ftn(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"FIN\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startFtn({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FIN\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartFtn(ctx, didit.IDWalletsStartFtnParams{\n\tBody: didit.DigitalIDWalletAPIFtnWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIFtnWalletVerificationStartCountryEnum(\"FIN\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiFtnWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiFtnWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startFtn(DigitalIdWalletApiFtnWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiFtnWalletVerificationStartCountryEnum.of(\"FIN\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startFtn([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'FIN',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_ftn(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FIN\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartFtnAsync(new DigitalIdWalletApiFtnWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiFtnWalletVerificationStartCountryEnum(\"FIN\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "ftn" } }, "/v3/id-verification/wallets/personalausweis/": { "post": { "operationId": "start_personalausweis_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_personalausweis", "auth": "api_key", "server": true }, "description": "Avvia un accesso Personalausweis (Bundesministerium des Innern (eID); DEU) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui reindirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni in sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica Personalausweis", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest" }, "example": { "country": "DEU", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "personalausweis", "name": "Personalausweis", "issuing_authority": "Bundesministerium des Innern (eID)" }, "country": "DEU", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/personalausweis/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"DEU\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_personalausweis(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"DEU\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startPersonalausweis({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DEU\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartPersonalausweis(ctx, didit.IDWalletsStartPersonalausweisParams{\n\tBody: didit.DigitalIDWalletAPIPersonalausweisWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIPersonalausweisWalletVerificationStartCountryEnum(\"DEU\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startPersonalausweis(DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum.of(\"DEU\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startPersonalausweis([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'DEU',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_personalausweis(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DEU\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartPersonalausweisAsync(new DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum(\"DEU\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "personalausweis" } }, "/v3/id-verification/wallets/frejaid/": { "post": { "operationId": "start_frejaid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_frejaid", "auth": "api_key", "server": true }, "description": "Avvia un accesso Freja eID (Freja eID Group; SWE) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=redirect con l'URL a cui inviare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ottengono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica Freja eID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFrejaidWalletVerificationStartRequest" }, "example": { "country": "SWE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFrejaidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFrejaidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "frejaid", "name": "Freja eID", "issuing_authority": "Freja eID Group" }, "country": "SWE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/frejaid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"SWE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_frejaid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"SWE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startFrejaid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartFrejaid(ctx, didit.IDWalletsStartFrejaidParams{\n\tBody: didit.DigitalIDWalletAPIFrejaidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryEe9enum(\"SWE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountryEe9Enum;\nimport me.didit.types.DigitalIdWalletApiFrejaidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startFrejaid(DigitalIdWalletApiFrejaidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryEe9Enum.of(\"SWE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startFrejaid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'SWE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_frejaid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartFrejaidAsync(new DigitalIdWalletApiFrejaidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryEe9Enum(\"SWE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "frejaid" } }, "/v3/id-verification/wallets/uae-pass/": { "post": { "operationId": "start_uae_pass_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_uae_pass", "auth": "api_key", "server": true }, "description": "Avvia un accesso UAE PASS (UAE Digital Government Authority; ARE) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui reindirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni in sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica UAE PASS", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartRequest" }, "example": { "country": "ARE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "uae_pass", "name": "UAE PASS", "issuing_authority": "UAE Digital Government Authority" }, "country": "ARE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/uae-pass/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"ARE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_uae_pass(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"ARE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startUaePass({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ARE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartUaePass(ctx, didit.IDWalletsStartUaePassParams{\n\tBody: didit.DigitalIDWalletAPIUaePassWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIUaePassWalletVerificationStartCountryEnum(\"ARE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiUaePassWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startUaePass(DigitalIdWalletApiUaePassWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum.of(\"ARE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startUaePass([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'ARE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_uae_pass(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ARE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartUaePassAsync(new DigitalIdWalletApiUaePassWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum(\"ARE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "uae_pass" } }, "/v3/id-verification/wallets/govbr/": { "post": { "operationId": "start_govbr_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_govbr", "auth": "api_key", "server": true }, "description": "Avvia un accesso gov.br (Governo Federal do Brasil; BRA) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui reindirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni in sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia verifica gov.br", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartRequest" }, "example": { "country": "BRA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "govbr", "name": "gov.br", "issuing_authority": "Governo Federal do Brasil" }, "country": "BRA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/govbr/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"BRA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_govbr(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"BRA\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startGovbr({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BRA\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartGovbr(ctx, didit.IDWalletsStartGovbrParams{\n\tBody: didit.DigitalIDWalletAPIGovbrWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIGovbrWalletVerificationStartCountryEnum(\"BRA\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiGovbrWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startGovbr(DigitalIdWalletApiGovbrWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum.of(\"BRA\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startGovbr([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'BRA',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_govbr(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BRA\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartGovbrAsync(new DigitalIdWalletApiGovbrWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum(\"BRA\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "govbr" } }, "/v3/id-verification/wallets/oneid/": { "post": { "operationId": "start_oneid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_oneid", "auth": "api_key", "server": true }, "description": "Avvia un accesso OneID (OneID (identità verificata da banca britannica); GBR) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui reindirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni in sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica OneID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiOneidWalletVerificationStartRequest" }, "example": { "country": "GBR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiOneidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiOneidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "oneid", "name": "OneID", "issuing_authority": "OneID (UK bank-verified identity)" }, "country": "GBR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/oneid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"GBR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_oneid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"GBR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startOneid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartOneid(ctx, didit.IDWalletsStartOneidParams{\n\tBody: didit.DigitalIDWalletAPIOneidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountry520enum(\"GBR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountry520Enum;\nimport me.didit.types.DigitalIdWalletApiOneidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startOneid(DigitalIdWalletApiOneidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountry520Enum.of(\"GBR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startOneid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'GBR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_oneid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartOneidAsync(new DigitalIdWalletApiOneidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountry520Enum(\"GBR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "oneid" } }, "/v3/id-verification/wallets/govuk-wallet/": { "post": { "operationId": "start_govuk_wallet_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_govuk_wallet", "auth": "api_key", "server": true }, "description": "Avvia un accesso GOV.UK Wallet (UK Government Digital Service; GBR) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=redirect con l'URL a cui inviare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ottengono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica GOV.UK Wallet", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovukWalletWalletVerificationStartRequest" }, "example": { "country": "GBR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovukWalletWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovukWalletWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "govuk_wallet", "name": "GOV.UK Wallet", "issuing_authority": "UK Government Digital Service" }, "country": "GBR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/govuk-wallet/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"GBR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_govuk_wallet(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"GBR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startGovukWallet({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartGovukWallet(ctx, didit.IDWalletsStartGovukWalletParams{\n\tBody: didit.DigitalIDWalletAPIGovukWalletWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountry520enum(\"GBR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountry520Enum;\nimport me.didit.types.DigitalIdWalletApiGovukWalletWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startGovukWallet(DigitalIdWalletApiGovukWalletWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountry520Enum.of(\"GBR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startGovukWallet([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'GBR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_govuk_wallet(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartGovukWalletAsync(new DigitalIdWalletApiGovukWalletWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountry520Enum(\"GBR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "govuk_wallet" } }, "/v3/id-verification/wallets/smart-id/": { "post": { "operationId": "start_smart_id_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_smart_id", "auth": "api_key", "server": true }, "description": "Avvia un accesso Smart-ID (SK ID Solutions; EST, LVA, LTU, BEL) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=confirm_in_app con il codice di confronto da mostrare all'utente; l'utente lo conferma e inserisce il proprio PIN nell'app (non raccogliere mai il PIN). Esegui il polling chiamando POST /v3/id-verification/wallets/verifications/{request_id}/poll/ ogni poll_interval_seconds, oppure affidati al webhook: Didit esegue il polling anche in background. Le applicazioni in sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica Smart-ID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartRequest" }, "example": { "country": "EST", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "personal_code": "00000000000" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "smart_id", "name": "Smart-ID", "issuing_authority": "SK ID Solutions" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "in_app", "simulated": true, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "confirm_in_app", "verification_code": "1234", "poll_interval_seconds": 2 }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/smart-id/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"EST\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"personal_code\": \"00000000000\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_smart_id(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"EST\",\n personal_code=\"00000000000\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startSmartId({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartSmartID(ctx, didit.IDWalletsStartSmartIDParams{\n\tBody: didit.DigitalIDWalletAPISmartIDWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPISmartIDWalletVerificationStartCountryEnum(\"EST\"),\n\t\tPersonalCode: \"00000000000\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiSmartIdWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startSmartId(DigitalIdWalletApiSmartIdWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum.of(\"EST\"))\n .personalCode(\"00000000000\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startSmartId([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'EST',\n 'personal_code' => '00000000000',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_smart_id(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartSmartIdAsync(new DigitalIdWalletApiSmartIdWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"EST\",\n PersonalCode = \"00000000000\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "smart_id" } }, "/v3/id-verification/wallets/mobile-id/": { "post": { "operationId": "start_mobile_id_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_mobile_id", "auth": "api_key", "server": true }, "description": "Avvia un accesso Mobile-ID (SK ID Solutions con gli operatori mobili nazionali; EST, LTU) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=confirm_in_app con il codice di confronto da mostrare all'utente; l'utente lo conferma e inserisce il proprio PIN nell'app (non raccogliere mai il PIN). Esegui il polling con POST /v3/id-verification/wallets/verifications/{request_id}/poll/ ogni poll_interval_seconds, oppure affidati al webhook: Didit esegue il polling anche in background. Le applicazioni sandbox ottengono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica Mobile-ID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest" }, "example": { "country": "EST", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "personal_code": "00000000000", "phone_number": "+37200000000" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "mobile_id", "name": "Mobile-ID", "issuing_authority": "SK ID Solutions with the national mobile operators" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "in_app", "simulated": true, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "confirm_in_app", "verification_code": "1234", "poll_interval_seconds": 2 }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/mobile-id/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"EST\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"personal_code\": \"00000000000\",\n \"phone_number\": \"+37200000000\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_mobile_id(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"EST\",\n personal_code=\"00000000000\",\n phone_number=\"+37200000000\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startMobileId({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\",\n phone_number: \"+37200000000\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartMobileID(ctx, didit.IDWalletsStartMobileIDParams{\n\tBody: didit.DigitalIDWalletAPIMobileIDWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIMobileIDWalletVerificationStartCountryEnum(\"EST\"),\n\t\tPersonalCode: \"00000000000\",\n\t\tPhoneNumber: \"+37200000000\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiMobileIdWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startMobileId(DigitalIdWalletApiMobileIdWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum.of(\"EST\"))\n .personalCode(\"00000000000\")\n .phoneNumber(\"+37200000000\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startMobileId([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'EST',\n 'personal_code' => '00000000000',\n 'phone_number' => '+37200000000',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_mobile_id(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\",\n phone_number: \"+37200000000\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartMobileIdAsync(new DigitalIdWalletApiMobileIdWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"EST\",\n PersonalCode = \"00000000000\",\n PhoneNumber = \"+37200000000\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "mobile_id" } }, "/v3/id-verification/wallets/idcard-ee/": { "post": { "operationId": "start_idcard_ee_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_idcard_ee", "auth": "api_key", "server": true }, "description": "Avvia un accesso con carta d'identità estone (Police and Border Guard Board (Estonia); EST) senza alcun workflow. Addebitato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui indirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il fornitore.", "summary": "Avvia la verifica Estonian ID-card", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartRequest" }, "example": { "country": "EST", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "idcard_ee", "name": "Estonian ID-card", "issuing_authority": "Police and Border Guard Board (Estonia)" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/idcard-ee/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"EST\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_idcard_ee(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"EST\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startIdcardEe({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartIdcardEe(ctx, didit.IDWalletsStartIdcardEeParams{\n\tBody: didit.DigitalIDWalletAPIIdcardEeWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIIdcardEeWalletVerificationStartCountryEnum(\"EST\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiIdcardEeWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startIdcardEe(DigitalIdWalletApiIdcardEeWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum.of(\"EST\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startIdcardEe([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'EST',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_idcard_ee(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartIdcardEeAsync(new DigitalIdWalletApiIdcardEeWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum(\"EST\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "idcard_ee" } }, "/v3/id-verification/wallets/eparaksts-mobile/": { "post": { "operationId": "start_eparaksts_mobile_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_eparaksts_mobile", "auth": "api_key", "server": true }, "description": "Avvia un accesso eParaksts mobile (LVRTC (Latvian State Radio and Television Centre); LVA) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui reindirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni in sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia una verifica eParaksts mobile", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest" }, "example": { "country": "LVA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "eparaksts_mobile", "name": "eParaksts mobile", "issuing_authority": "LVRTC (Latvian State Radio and Television Centre)" }, "country": "LVA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/eparaksts-mobile/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"LVA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_eparaksts_mobile(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"LVA\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startEparakstsMobile({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"LVA\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartEparakstsMobile(ctx, didit.IDWalletsStartEparakstsMobileParams{\n\tBody: didit.DigitalIDWalletAPIEparakstsMobileWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIEparakstsMobileWalletVerificationStartCountryEnum(\"LVA\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startEparakstsMobile(DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum.of(\"LVA\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startEparakstsMobile([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'LVA',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_eparaksts_mobile(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"LVA\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartEparakstsMobileAsync(new DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum(\"LVA\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "eparaksts_mobile" } }, "/v3/id-verification/wallets/bankid-cz/": { "post": { "operationId": "start_bankid_cz_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_bankid_cz", "auth": "api_key", "server": true }, "description": "Avvia un accesso Bank iD (Bankovní identita, a.s.; CZE) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=redirect con l'URL a cui indirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il fornitore.", "summary": "Avvia la verifica Bank iD", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidCzWalletVerificationStartRequest" }, "example": { "country": "CZE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidCzWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidCzWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "bankid_cz", "name": "Bank iD", "issuing_authority": "Bankovní identita, a.s." }, "country": "CZE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/bankid-cz/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"CZE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_bankid_cz(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"CZE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBankidCz({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBankidCz(ctx, didit.IDWalletsStartBankidCzParams{\n\tBody: didit.DigitalIDWalletAPIBankidCzWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryE2dEnum(\"CZE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBankidCzWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryE2dEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBankidCz(DigitalIdWalletApiBankidCzWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryE2dEnum.of(\"CZE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBankidCz([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'CZE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_bankid_cz(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBankidCzAsync(new DigitalIdWalletApiBankidCzWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryE2dEnum(\"CZE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "bankid_cz" } }, "/v3/id-verification/wallets/mojeid/": { "post": { "operationId": "start_mojeid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_mojeid", "auth": "api_key", "server": true }, "description": "Avvia un accesso MojeID (CZ.NIC; CZE) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui reindirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni in sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica MojeID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMojeidWalletVerificationStartRequest" }, "example": { "country": "CZE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMojeidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMojeidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "mojeid", "name": "MojeID", "issuing_authority": "CZ.NIC" }, "country": "CZE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/mojeid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"CZE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_mojeid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"CZE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startMojeid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartMojeid(ctx, didit.IDWalletsStartMojeidParams{\n\tBody: didit.DigitalIDWalletAPIMojeidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryE2dEnum(\"CZE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountryE2dEnum;\nimport me.didit.types.DigitalIdWalletApiMojeidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startMojeid(DigitalIdWalletApiMojeidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryE2dEnum.of(\"CZE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startMojeid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'CZE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_mojeid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartMojeidAsync(new DigitalIdWalletApiMojeidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryE2dEnum(\"CZE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "mojeid" } }, "/v3/id-verification/wallets/diia/": { "post": { "operationId": "start_diia_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_diia", "auth": "api_key", "server": true }, "description": "Avvia un accesso Diia (Ministry of Digital Transformation of Ukraine; UKR) senza alcun workflow. Addebitato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui indirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il fornitore.", "summary": "Avvia la verifica Diia", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartRequest" }, "example": { "country": "UKR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "diia", "name": "Diia", "issuing_authority": "Ministry of Digital Transformation of Ukraine" }, "country": "UKR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/diia/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"UKR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_diia(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"UKR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startDiia({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"UKR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartDiia(ctx, didit.IDWalletsStartDiiaParams{\n\tBody: didit.DigitalIDWalletAPIDiiaWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIDiiaWalletVerificationStartCountryEnum(\"UKR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiDiiaWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startDiia(DigitalIdWalletApiDiiaWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum.of(\"UKR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startDiia([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'UKR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_diia(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"UKR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartDiiaAsync(new DigitalIdWalletApiDiiaWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum(\"UKR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "diia" } }, "/v3/id-verification/wallets/franceconnect/": { "post": { "operationId": "start_franceconnect_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_franceconnect", "auth": "api_key", "server": true }, "description": "Avvia un accesso FranceConnect (DINUM (Stato francese); FRA) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=redirect con l'URL a cui inviare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ottengono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica FranceConnect", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartRequest" }, "example": { "country": "FRA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "franceconnect", "name": "FranceConnect", "issuing_authority": "DINUM (French state)" }, "country": "FRA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/franceconnect/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"FRA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_franceconnect(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"FRA\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startFranceconnect({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FRA\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartFranceconnect(ctx, didit.IDWalletsStartFranceconnectParams{\n\tBody: didit.DigitalIDWalletAPIFranceconnectWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIFranceconnectWalletVerificationStartCountryEnum(\"FRA\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiFranceconnectWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startFranceconnect(DigitalIdWalletApiFranceconnectWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum.of(\"FRA\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startFranceconnect([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'FRA',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_franceconnect(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FRA\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartFranceconnectAsync(new DigitalIdWalletApiFranceconnectWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum(\"FRA\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "franceconnect" } }, "/v3/id-verification/wallets/audkenni/": { "post": { "operationId": "start_audkenni_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_audkenni", "auth": "api_key", "server": true }, "description": "Avvia un accesso Auðkenni (Auðkenni (identità elettronica islandese); ISL) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=redirect con l'URL a cui indirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il fornitore.", "summary": "Avvia la verifica Auðkenni", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartRequest" }, "example": { "country": "ISL", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "audkenni", "name": "Auðkenni", "issuing_authority": "Auðkenni (Icelandic electronic ID)" }, "country": "ISL", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/audkenni/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"ISL\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_audkenni(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"ISL\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startAudkenni({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ISL\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartAudkenni(ctx, didit.IDWalletsStartAudkenniParams{\n\tBody: didit.DigitalIDWalletAPIAudkenniWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIAudkenniWalletVerificationStartCountryEnum(\"ISL\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiAudkenniWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startAudkenni(DigitalIdWalletApiAudkenniWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum.of(\"ISL\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startAudkenni([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'ISL',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_audkenni(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ISL\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartAudkenniAsync(new DigitalIdWalletApiAudkenniWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum(\"ISL\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "audkenni" } }, "/v3/id-verification/wallets/connectid/": { "post": { "operationId": "start_connectid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_connectid", "auth": "api_key", "server": true }, "description": "Avvia un accesso ConnectID (Australian Payments Plus; AUS) senza alcun workflow. Addebitato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui indirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il fornitore.", "summary": "Avvia la verifica ConnectID", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartRequest" }, "example": { "country": "AUS", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "connectid", "name": "ConnectID", "issuing_authority": "Australian Payments Plus" }, "country": "AUS", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/connectid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"AUS\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_connectid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"AUS\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startConnectid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUS\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartConnectid(ctx, didit.IDWalletsStartConnectidParams{\n\tBody: didit.DigitalIDWalletAPIConnectidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIConnectidWalletVerificationStartCountryEnum(\"AUS\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiConnectidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startConnectid(DigitalIdWalletApiConnectidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum.of(\"AUS\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startConnectid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'AUS',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_connectid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUS\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartConnectidAsync(new DigitalIdWalletApiConnectidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum(\"AUS\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "connectid" } }, "/v3/id-verification/wallets/eudi/": { "post": { "operationId": "start_eudi_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_eudi", "auth": "api_key", "server": true }, "description": "Avvia un accesso EUDI Wallet (lo Stato membro dell'utente; l'emittente varia a seconda del paese; AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE, ISL, LIE, NOR) senza alcun workflow. Addebitato una sola volta, solo quando l'identità viene verificata. La risposta include next_action.type=redirect con l'URL a cui indirizzare il browser dell'utente; l'utente torna a return_url con request_id e result aggiunti in coda. Leggi l'esito con GET /v3/id-verification/wallets/verifications/{request_id}/ o dal webhook, mai dall'URL. Le applicazioni sandbox ricevono una simulazione deterministica (simulated: true) che non contatta mai il fornitore.", "summary": "Avvia la verifica EUDI Wallet", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest" }, "example": { "country": "AUT", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "eudi", "name": "EUDI Wallet", "issuing_authority": "The user's own member state; the issuer differs per country" }, "country": "AUT", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/eudi/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"AUT\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_eudi(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"AUT\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startEudi({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUT\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartEudi(ctx, didit.IDWalletsStartEudiParams{\n\tBody: didit.DigitalIDWalletAPIEudiWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIEudiWalletVerificationStartCountryEnum(\"AUT\"),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiEudiWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiEudiWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startEudi(DigitalIdWalletApiEudiWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiEudiWalletVerificationStartCountryEnum.of(\"AUT\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startEudi([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'AUT',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_eudi(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUT\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartEudiAsync(new DigitalIdWalletApiEudiWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"AUT\",\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "eudi" } }, "/v3/organization/{organization_id}/application/{application_id}/cases/teams/": { "get": { "summary": "Elenca i team di revisione", "description": "Richiede `list:cases` per l'applicazione richiesta.", "operationId": "list_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Riuscito", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeam" } }, "count": { "type": "integer", "description": "Conteggio delle corrispondenze, limitato a 100. Segui next per continuare oltre il limite." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.teams.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.teams.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Teams.ListAutoPaging(ctx, didit.CasesTeamsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().teams().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->teams->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.teams.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Teams.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Crea team di revisione", "description": "Richiede `write:cases` per l'applicazione richiesta.", "operationId": "create_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "responses": { "201": { "description": "Riuscito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeam" } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeamCreate" }, "example": { "name": "AML analysts", "members": [ { "user_id": "9a000000-0000-4000-8000-0000000000aa", "capacity": 10 } ] } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.teams.create(\n name=\"AML analysts\",\n members=[{\n \"user_id\": \"9a000000-0000-4000-8000-0000000000aa\",\n \"capacity\": 10,\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.teams.create({\n name: \"AML analysts\",\n members: [{\n user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n capacity: 10,\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Teams.Create(ctx, didit.CaseReviewTeamCreate{\n\tName: \"AML analysts\",\n\tMembers: []didit.CaseReviewTeamMemberParam{{\n\t\tUserID: \"9a000000-0000-4000-8000-0000000000aa\",\n\t\tCapacity: didit.Int(10),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseReviewTeamCreate;\nimport me.didit.types.CaseReviewTeamMember;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().teams().create(CaseReviewTeamCreate.builder()\n .name(\"AML analysts\")\n .members(List.of(CaseReviewTeamMember.builder()\n .userId(\"9a000000-0000-4000-8000-0000000000aa\")\n .capacity(10L)\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->teams->create([\n 'name' => 'AML analysts',\n 'members' => [[\n 'user_id' => '9a000000-0000-4000-8000-0000000000aa',\n 'capacity' => 10,\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.teams.create(\n name: \"AML analysts\",\n members: [{\n user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n capacity: 10,\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Teams.CreateAsync(new CaseReviewTeamCreate\n{\n Name = \"AML analysts\",\n Members = new CaseReviewTeamMember[]\n {\n new()\n {\n UserId = \"9a000000-0000-4000-8000-0000000000aa\",\n Capacity = 10,\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/fraud/checks/{check_id}/": { "get": { "operationId": "root_retrieve", "x-didit-sdk": { "resource": "fraud_checks", "method": "retrieve", "auth": "api_key", "server": true }, "description": "Recupera un controllo creato in precedenza tramite il relativo `check_id`.", "summary": "Recupera un controllo antifrode", "parameters": [ { "in": "path", "name": "check_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckResponse" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsErrorMessage" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsForbiddenErrorMessage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ "Fraud Check" ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.fraud_checks.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.fraudChecks.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.fraudChecks().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "fraudChecks->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.fraud_checks.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FraudChecks.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/": { "get": { "operationId": "organization_application_cases_requests_list", "x-didit-sdk": { "resource": "cases.requests", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "Quale campo utilizzare per ordinare i risultati.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Numero di risultati da restituire per pagina.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "L'indice iniziale da cui restituire i risultati.", "schema": { "type": "integer" } } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingPaginatedCaseRequestList" } } }, "description": "" }, "404": { "description": "La richiesta o il caso non è disponibile per questo chiamante." }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.requests.list(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.requests.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Requests.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesRequestsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().requests().list(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->requests->list('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.requests.list(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Requests.ListAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "operationId": "organization_application_cases_requests_create", "x-didit-sdk": { "resource": "cases.requests", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestConfirmRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestConfirmRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestConfirmRequest" } } }, "required": true }, "responses": { "404": { "description": "La richiesta o il caso non è disponibile per questo chiamante." }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." }, "400": { "description": "Dati di input non validi, finalità non supportata, contatto verificato non disponibile o risposta immutabile già esistente." }, "409": { "description": "L'anteprima è cambiata o è scaduta. Visualizza nuovamente l'anteprima prima di confermare." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Conferma l'anteprima firmata esatta entro 15 minuti. Sono accettati solo modelli fissi e un contatto verificato tramite OTP appartenente al soggetto del caso. L'ID richiesta rende i nuovi tentativi idempotenti. La consegna è accodata; SENT, SIMULATED e UNKNOWN sono esiti distinti. Una richiesta operativa imposta il caso su In attesa dell'utente. Un aggiornamento di revisione lascia invariato il relativo stato.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.create(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id=\"11111111-2222-3333-4444-555555555555\",\n purpose=\"identity_document\",\n request_id=\"11111111-2222-3333-4444-555555555555\",\n expires_at=\"2026-01-15T10:00:00Z\",\n preview_token=\"your-preview-token\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.create(\"11111111-2222-3333-4444-555555555555\", {\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\",\n request_id: \"11111111-2222-3333-4444-555555555555\",\n expires_at: \"2026-01-15T10:00:00Z\",\n preview_token: \"your-preview-token\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CustomerMessagingCaseRequestConfirmRequest{\n\tContactID: \"11111111-2222-3333-4444-555555555555\",\n\tPurpose: didit.CustomerMessagingPurposeEnum(\"identity_document\"),\n\tRequestID: \"11111111-2222-3333-4444-555555555555\",\n\tExpiresAt: time.Date(2026, 1, 15, 10, 0, 0, 0, time.UTC),\n\tPreviewToken: \"your-preview-token\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport me.didit.Didit;\nimport me.didit.types.CustomerMessagingCaseRequestConfirmRequest;\nimport me.didit.types.CustomerMessagingPurposeEnum;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().create(\"11111111-2222-3333-4444-555555555555\", CustomerMessagingCaseRequestConfirmRequest.builder()\n .contactId(\"11111111-2222-3333-4444-555555555555\")\n .purpose(CustomerMessagingPurposeEnum.of(\"identity_document\"))\n .requestId(\"11111111-2222-3333-4444-555555555555\")\n .expiresAt(OffsetDateTime.parse(\"2026-01-15T10:00:00Z\"))\n .previewToken(\"your-preview-token\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->create('11111111-2222-3333-4444-555555555555', [\n 'contact_id' => '11111111-2222-3333-4444-555555555555',\n 'purpose' => 'identity_document',\n 'request_id' => '11111111-2222-3333-4444-555555555555',\n 'expires_at' => '2026-01-15T10:00:00Z',\n 'preview_token' => 'your-preview-token',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.create(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\",\n request_id: \"11111111-2222-3333-4444-555555555555\",\n expires_at: \"2026-01-15T10:00:00Z\",\n preview_token: \"your-preview-token\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new CustomerMessagingCaseRequestConfirmRequest\n{\n ContactId = \"11111111-2222-3333-4444-555555555555\",\n Purpose = \"identity_document\",\n RequestId = \"11111111-2222-3333-4444-555555555555\",\n ExpiresAt = DateTimeOffset.Parse(\"2026-01-15T10:00:00Z\"),\n PreviewToken = \"your-preview-token\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/fraud/checks/": { "post": { "operationId": "create_fraud_check", "x-didit-sdk": { "resource": "fraud_checks", "method": "create", "auth": "api_key", "server": true }, "description": "Invia uno o più identificativi tipizzati e ricevi normalizzazione, arricchimento aggiornato, validazione da fonte autorevole quando il paese e il tipo di identificativo sono supportati, dimensioni di rischio indipendenti e una raccomandazione in un'unica risposta.\n\nQuesti profili supportano i controlli degli identificativi. L'associazione dell'identità basata su selfie (`biometric_identity`) richiede la versione del profilo `2026-09-14.2` e un CPF brasiliano; viene eseguita solo con il consenso dell'utente e quando la tua organizzazione ne ha diritto. Le versioni precedenti la segnalano come `not_available_in_profile_version`. I moduli che non possono essere eseguiti vengono segnalati come ignorati con un motivo deterministico; una fonte che non ha potuto rispondere non viene mai segnalata come mancata corrispondenza dell'identità.", "summary": "Esegui un controllo antifrode", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" }, "example": { "client_reference": "review-attempt-001", "subject": { "identifiers": [ { "type": "email", "value": "applicant@example.com" } ], "attributes": { "first_name": "Alex", "last_name": "Example" } }, "checks": { "include": [ "networks_same_org", "networks_cross_org", "email_risk" ] } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckResponse" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsErrorMessage" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsForbiddenErrorMessage" } } }, "description": "" }, "409": { "description": "Conflitto, restituito senza addebito: il `client_reference` è già stato utilizzato con un corpo della richiesta diverso; un controllo con lo stesso `client_reference` è ancora in esecuzione (riprova dopo `Retry-After` secondi con lo stesso riferimento); oppure la verifica in cui questo controllo registra i dati è stata eliminata prima del completamento del controllo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "examples": { "different_body": { "summary": "Riferimento riutilizzato con un body diverso", "value": { "error": "client_reference has already been used with a different request body." } }, "still_running": { "summary": "Un controllo con questo riferimento è ancora in esecuzione", "value": { "error": "A check with this client_reference is already running. Retry with the same reference later." } }, "verification_deleted": { "summary": "La verifica è stata eliminata prima del completamento del controllo", "value": { "error": "This verification was deleted before the check completed." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di riprovare, inviati quando un controllo con lo stesso `client_reference` è ancora in esecuzione.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ "Fraud Check" ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.fraud_checks.create(\n client_reference=\"review-attempt-001\",\n subject={\n \"identifiers\": [{\n \"type\": \"email\",\n \"value\": \"applicant@example.com\",\n }],\n \"attributes\": {\n \"first_name\": \"Alex\",\n \"last_name\": \"Example\",\n },\n },\n checks={\n \"include\": [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.fraudChecks.create({\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Create(ctx, didit.FraudCheckRequestRequest{\n\tClientReference: didit.String(\"review-attempt-001\"),\n\tSubject: didit.FraudCheckSubjectRequest{\n\t\tIdentifiers: []didit.FraudCheckIdentifierRequest{{\n\t\t\tType: didit.FraudTypeEnum(\"email\"),\n\t\t\tValue: \"applicant@example.com\",\n\t\t}},\n\t\tAttributes: didit.Some(didit.FraudCheckAttributesRequest{\n\t\t\tFirstName: didit.String(\"Alex\"),\n\t\t\tLastName: didit.String(\"Example\"),\n\t\t}),\n\t},\n\tChecks: didit.Some(didit.FraudCheckModuleSelectionRequest{\n\t\tInclude: didit.Some([]didit.FraudExcludeEnum{didit.FraudExcludeEnum(\"networks_same_org\"), didit.FraudExcludeEnum(\"networks_cross_org\"), didit.FraudExcludeEnum(\"email_risk\")}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.FraudCheckAttributesRequest;\nimport me.didit.types.FraudCheckIdentifierRequest;\nimport me.didit.types.FraudCheckModuleSelectionRequest;\nimport me.didit.types.FraudCheckRequestRequest;\nimport me.didit.types.FraudCheckSubjectRequest;\nimport me.didit.types.FraudExcludeEnum;\nimport me.didit.types.FraudTypeEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.fraudChecks().create(FraudCheckRequestRequest.builder()\n .clientReference(\"review-attempt-001\")\n .subject(FraudCheckSubjectRequest.builder()\n .identifiers(List.of(FraudCheckIdentifierRequest.builder()\n .type(FraudTypeEnum.of(\"email\"))\n .value(\"applicant@example.com\")\n .build()))\n .attributes(FraudCheckAttributesRequest.builder()\n .firstName(\"Alex\")\n .lastName(\"Example\")\n .build())\n .build())\n .checks(FraudCheckModuleSelectionRequest.builder()\n .include(List.of(FraudExcludeEnum.of(\"networks_same_org\"), FraudExcludeEnum.of(\"networks_cross_org\"), FraudExcludeEnum.of(\"email_risk\")))\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "fraudChecks->create([\n 'client_reference' => 'review-attempt-001',\n 'subject' => [\n 'identifiers' => [[\n 'type' => 'email',\n 'value' => 'applicant@example.com',\n ]],\n 'attributes' => [\n 'first_name' => 'Alex',\n 'last_name' => 'Example',\n ],\n ],\n 'checks' => [\n 'include' => ['networks_same_org', 'networks_cross_org', 'email_risk'],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.fraud_checks.create(\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FraudChecks.CreateAsync(new FraudCheckRequestRequest\n{\n ClientReference = \"review-attempt-001\",\n Subject = new()\n {\n Identifiers = new FraudCheckIdentifierRequest[]\n {\n new()\n {\n Type = \"email\",\n Value = \"applicant@example.com\",\n },\n },\n Attributes = new FraudCheckAttributesRequest\n {\n FirstName = \"Alex\",\n LastName = \"Example\",\n },\n },\n Checks = new FraudCheckModuleSelectionRequest\n {\n Include = new FraudExcludeEnum[] { \"networks_same_org\", \"networks_cross_org\", \"email_risk\" },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/{request_uuid}/cancel/": { "post": { "operationId": "organization_application_cases_requests_cancel_create", "x-didit-sdk": { "resource": "cases.requests", "method": "cancel", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" } } }, "description": "" }, "404": { "description": "La richiesta o il caso non è disponibile per questo chiamante." }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." }, "400": { "description": "Dati di input non validi, finalità non supportata, contatto verificato non disponibile o risposta immutabile già esistente." }, "409": { "description": "L'anteprima è cambiata o è scaduta. Visualizza nuovamente l'anteprima prima di confermare." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Cancel(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().cancel(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->cancel('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.CancelAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/options/": { "get": { "operationId": "organization_application_cases_requests_options_retrieve", "x-didit-sdk": { "resource": "cases.requests", "method": "retrieve_options", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestOptions" } } }, "description": "" }, "404": { "description": "La richiesta o il caso non è disponibile per questo chiamante." }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.retrieve_options(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.retrieveOptions(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.RetrieveOptions(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().retrieveOptions(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->retrieveOptions('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.retrieve_options(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.RetrieveOptionsAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/{request_uuid}/attachment/": { "get": { "operationId": "organization_application_cases_requests_attachment_retrieve", "x-didit-sdk": { "resource": "cases.requests", "method": "retrieve_attachment", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } }, "description": "" }, "404": { "description": "La richiesta o il caso non è disponibile per questo chiamante." }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\ncontent = client.cases.requests.retrieve_attachment(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.png\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst content = await didit.cases.requests.retrieveAttachment(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nawait writeFile(\"download.png\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresp, err := client.Cases.Requests.RetrieveAttachment(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.png\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().requests().retrieveAttachment(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.png\"));" }, { "lang": "php", "label": "PHP", "source": "cases->requests->retrieveAttachment('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.png');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ncontent = didit.cases.requests.retrieve_attachment(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nFile.binwrite(\"download.png\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar content = await client.Cases.Requests.RetrieveAttachmentAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.png\");" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/history/": { "get": { "operationId": "list_case_routing_rule_history", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "list_history", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "Quale campo utilizzare per ordinare i risultati.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Numero di risultati da restituire per pagina.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "L'indice iniziale da cui restituire i risultati.", "schema": { "type": "integer" } } ], "tags": [ "Case Assignment" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPaginatedPolicyRevisionList" } } }, "description": "" }, "403": { "description": "L'accesso al caso è obbligatorio." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.routing_rules.list_history(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.routingRules.listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.RoutingRules.ListHistoryAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesRoutingRulesListHistoryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().routingRules().listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->listHistory('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.routing_rules.list_history(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.RoutingRules.ListHistoryAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/resubmission-preview/": { "post": { "summary": "Visualizza l'anteprima di un'email di nuovo invio", "description": "Esegue il rendering dell'email che accompagnerebbe un nuovo invio KYC o KYB senza modificare la sessione, azzerare i controlli, estenderne la scadenza, eseguire verifiche o inviare email. Richiede il privilegio `write:sessions` (una chiave API con ambito limitato necessita dell'accesso in scrittura alle decisioni) e una sessione nello stato `Approved`, `Declined`, `In Review`, `Kyc Expired` o `Abandoned`. Il server convalida i passaggi del workflow selezionati ed esegue il rendering del relativo modello tradotto fisso con il mittente e il branding white label verificati applicabili. La richiesta non può impostare un oggetto, il corpo del messaggio o l'URL dell'azione.\n\n`email_address` è opzionale. Senza di esso, l'email viene inviata all'indirizzo della persona stessa: quello verificato in un passaggio di verifica email del flusso, altrimenti quello fornito in `contact_details` al momento della creazione della sessione. Un indirizzo trasmesso ha la precedenza (`recipient_source: request`). Quando non è noto alcun indirizzo e non ne viene trasmesso alcuno, `recipient` e `preview_token` sono stringhe vuote e non è possibile inviare alcuna email.\n\nLa risposta include il destinatario e la relativa origine, il mittente, l'oggetto, l'HTML, la lingua, i passaggi risolti, se la conferma comporta l'invio dell'email (`will_be_sent`, `not_sent_reason`) e un `preview_token` firmato. `requires_user_action` è `false` quando ogni passaggio selezionato viene eseguito senza la persona: il nuovo invio si conclude quindi autonomamente e non viene inviata alcuna email (`not_sent_reason: no_user_action`).\n\nQuesta anteprima non riserva lo stato della sessione né autorizza la consegna. Dopo averla esaminata, chiama [Update Session Status](/it/sessions-api/update-status) con `new_status: Resubmitted`, gli stessi `nodes_to_resubmit` ed `email_language` visualizzati in anteprima, `send_email: true`, `email_address` impostato su `recipient` ed `email_preview_token` impostato su `preview_token`. La ricevuta scade dopo 15 minuti. Quando viene fornita una ricevuta, eventuali modifiche a input, contenuto del messaggio, mittente o stato della sessione restituiscono `409` prima di qualsiasi modifica o invio. Le integrazioni esistenti possono omettere la ricevuta. Rigenera l'anteprima dopo un conflitto. Considera la risposta come contenuto di verifica sensibile; le risposte utilizzano `Cache-Control: no-store`. Esegui il rendering dell'HTML in un frame sandbox, mai direttamente nel DOM della tua applicazione.", "operationId": "post_v3_session_resubmission_preview", "x-didit-sdk": { "resource": "sessions", "method": "preview_resubmission", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica da aggiornare. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB): il servizio risolve l'ID per entrambi i tipi di sessione.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes_to_resubmit": { "type": "array", "description": "Passaggi da visualizzare in anteprima, utilizzando le stesse regole di validazione, selezione e ordinamento del workflow di un nuovo invio. Ometti per selezionare automaticamente i tentativi registrati che richiedono un nuovo invio.", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "Identificativo del nodo così come appare nella definizione del workflow della sessione (ad esempio `feature_ocr`, `feature_liveness`).", "example": "feature_ocr" }, "feature": { "type": "string", "description": "Tipo di funzionalità del nodo. Gli alias `ID_VERIFICATION`, `POA`, `PHONE` ed `EMAIL` vengono normalizzati lato server in `OCR`, `PROOF_OF_ADDRESS`, `PHONE_VERIFICATION` ed `EMAIL_VERIFICATION`. `KYB_REGISTRY`, `KYB_KEY_PEOPLE` e `KYB` superano la convalida dello schema ma vengono sempre rifiutati con l'errore di regola di business `400` mostrato negli esempi.", "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_DOCUMENTS", "ID_VERIFICATION", "POA", "PHONE", "EMAIL", "KYB_REGISTRY", "KYB_KEY_PEOPLE", "KYB", "GEOLOCATION" ], "example": "OCR" } } } }, "email_address": { "type": "string", "format": "email", "description": "Opzionale. Invia l'email a questo indirizzo invece che a quello della persona stessa. In sua assenza, il destinatario è l'indirizzo verificato dalla persona nel workflow, altrimenti quello indicato in `contact_details`. Nessuna email viene inviata da questa chiamata.", "example": "user@example.com" }, "email_language": { "type": "string", "description": "Lingua per l'email di notifica. Accetta qualsiasi stringa a livello di schema; i codici non supportati ripiegano silenziosamente sull'inglese (`en`).", "default": "en", "example": "en" } } }, "examples": { "Person's Own Address": { "summary": "Visualizza l'anteprima di un nuovo invio della prova di residenza per l'indirizzo della persona", "value": { "nodes_to_resubmit": [ { "node_id": "feature_poa_1", "feature": "POA" } ], "email_language": "en" } }, "Named Recipient": { "summary": "Visualizza l'anteprima dell'email per un indirizzo specificato da te", "value": { "nodes_to_resubmit": [ { "node_id": "feature_ocr", "feature": "OCR" } ], "email_address": "person@example.com", "email_language": "en" } } } } } }, "responses": { "200": { "description": "Solo anteprima. La sessione non viene modificata e non viene inviata alcuna email.", "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient", "recipient_source", "sender", "sender_name", "sender_email", "sender_kind", "subject", "html", "text", "language", "will_be_sent", "not_sent_reason", "preview_token", "nodes_to_resubmit", "requires_user_action" ], "properties": { "recipient": { "type": "string", "description": "L'indirizzo a cui viene inviata l'email. Stringa vuota se non si conosce alcun indirizzo per la persona: in tal caso non è possibile inviare alcuna email e anche `preview_token` è vuoto. Passalo come `email_address` quando confermi.", "example": "person@example.com" }, "recipient_source": { "type": "string", "enum": [ "email_verification", "contact_details", "request", "" ], "description": "Da dove proviene `recipient`. `request`: l'`email_address` trasmesso. `email_verification`: l'indirizzo verificato dalla persona in un passaggio di verifica email del flusso. `contact_details`: l'indirizzo fornito in `contact_details` alla creazione della sessione. Una stringa vuota quando non è presente alcun indirizzo.", "example": "email_verification" }, "sender": { "type": "string", "description": "L'intestazione `From` con cui viene inviata l'email.", "example": "Example App " }, "sender_name": { "type": "string", "description": "La parte del nome visualizzato di `sender`.", "example": "Example App" }, "sender_email": { "type": "string", "format": "email", "description": "La parte relativa all'indirizzo di `sender`.", "example": "no-reply@mail.example.com" }, "sender_kind": { "type": "string", "enum": [ "customer", "didit" ], "description": "`customer`: l'email viene inviata dal dominio mittente verificato della tua applicazione (white label). `didit`: viene inviata dal mittente di Didit.", "example": "customer" }, "subject": { "type": "string", "description": "La riga dell'oggetto esattamente come viene inviata.", "example": "Action Required: Complete your verification in Example App" }, "html": { "type": "string", "description": "L'HTML dell'email esattamente come inviato, con il logo incorporato come data URL. Effettuane il rendering in un frame in sandbox, mai direttamente nel DOM della tua applicazione.", "example": "..." }, "text": { "type": "string", "description": "Il testo dell'email in testo normale, così come viene mantenuto nel thread Messaggi della persona, per un'anteprima compatta (l'HTML rimane l'email ricevuta dalla persona).", "example": "Almost there\n\nSome steps need to be completed again.\nHere’s what to fix:\n\nhttps://verify.didit.me/session/abc123" }, "language": { "type": "string", "description": "La lingua in cui è scritta l'email. Inglese (`en`) se l'`email_language` richiesta non è disponibile.", "example": "en" }, "will_be_sent": { "type": "boolean", "description": "Indica se la conferma della modifica con `send_email: true` comporta l'invio di questa email. `false` quando `not_sent_reason` è impostato.", "example": true }, "not_sent_reason": { "type": "string", "nullable": true, "enum": [ "no_user_action", "no_recipient", "sandbox", null ], "description": "Il motivo per cui la conferma non invierebbe alcuna email, oppure `null` se verrà inviata. `no_user_action`: ogni passaggio selezionato viene eseguito senza la persona, quindi il nuovo invio si completa autonomamente e non viene spedita alcuna email. `no_recipient`: non è noto alcun indirizzo per la persona e non ne hai passato nessuno. `sandbox`: una sessione sandbox il cui destinatario non ha acconsentito alla consegna delle email in sandbox, quindi l'invio viene solo simulato.", "example": null }, "nodes_to_resubmit": { "type": "array", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "Identificativo del nodo così come appare nella definizione del workflow della sessione (ad esempio `feature_ocr`, `feature_liveness`).", "example": "feature_ocr" }, "feature": { "type": "string", "description": "Tipo di funzionalità del nodo. Gli alias `ID_VERIFICATION`, `POA`, `PHONE` ed `EMAIL` vengono normalizzati lato server in `OCR`, `PROOF_OF_ADDRESS`, `PHONE_VERIFICATION` ed `EMAIL_VERIFICATION`. `KYB_REGISTRY`, `KYB_KEY_PEOPLE` e `KYB` superano la convalida dello schema ma vengono sempre rifiutati con l'errore di regola di business `400` mostrato negli esempi.", "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_DOCUMENTS", "ID_VERIFICATION", "POA", "PHONE", "EMAIL", "KYB_REGISTRY", "KYB_KEY_PEOPLE", "KYB", "GEOLOCATION" ], "example": "OCR" } } } }, "requires_user_action": { "type": "boolean", "description": "Indica se almeno un controllo selezionato richiede l'interazione dell'utente. Ciò non prevede l'esito finale del workflow." }, "preview_token": { "type": "string", "description": "Ricevuta firmata per questa specifica email, valida per 15 minuti. Inviala come `email_preview_token` a [Update Session Status](/it/sessions-api/update-status). Una stringa vuota quando non è presente alcun destinatario.", "example": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } }, "examples": { "Will Be Sent": { "summary": "Destinatario predefinito: l'indirizzo verificato nel flusso", "value": { "recipient": "person@example.com", "recipient_source": "email_verification", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Action Required: Complete your verification in Example App", "html": "...", "language": "en", "will_be_sent": true, "not_sent_reason": null, "nodes_to_resubmit": [ { "node_id": "feature_poa_1", "feature": "PROOF_OF_ADDRESS" } ], "requires_user_action": true, "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } }, "No User Action": { "summary": "Sono selezionati solo passaggi di back-end, quindi non viene inviata alcuna email", "value": { "recipient": "person@example.com", "recipient_source": "contact_details", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Action Required: Complete your verification in Example App", "html": "...", "language": "en", "will_be_sent": false, "not_sent_reason": "no_user_action", "nodes_to_resubmit": [ { "node_id": "feature_aml", "feature": "AML" } ], "requires_user_action": false, "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } } } }, "headers": { "Cache-Control": { "description": "Sempre `no-store`: l'anteprima contiene contenuti di verifica e non deve essere memorizzata nella cache.", "schema": { "type": "string", "example": "no-store" } } } }, "400": { "description": "La sessione non è in uno stato accettato da questo endpoint, è già `Resubmitted`, i passaggi selezionati non possono essere ripresentati oppure un campo non è valido.", "content": { "application/json": { "examples": { "Wrong Current Status": { "summary": "La sessione non si trova in uno stato accettato da questo endpoint", "value": { "detail": "Only sessions with status Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted can be updated. Current status: In Progress" } }, "Already Resubmitted": { "summary": "La sessione è già Resubmitted", "value": [ "The new status is the same as the current status." ] }, "Nothing To Resubmit": { "summary": "La selezione automatica non ha trovato alcun passaggio da inviare nuovamente", "value": { "nodes_to_resubmit": "No features found that need resubmission. All features are already approved." } }, "Invalid Email": { "summary": "email_address non è un indirizzo email", "value": { "email_address": [ "Enter a valid email address." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chiave API con ambito oltre la sua data di scadenza", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenziali mancanti, chiamante senza il privilegio `write:sessions`, chiave API con ambito limitato priva dell'accesso richiesto da questo endpoint, oppure un `session_id` che appartiene a un'altra applicazione.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "Il chiamante non dispone dell'autorizzazione write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chiave API con ambito priva di questo accesso", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "Non esiste alcuna sessione KYC o KYB con questo `session_id`.", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id sconosciuto", "value": { "detail": "Not found." } } } } } }, "429": { "description": "I passaggi da reinviare sono tutti solo backend (AML, DATABASE_VALIDATION, IP_ANALYSIS) e la sessione è già stata reinviata per passaggi solo backend negli ultimi 30 secondi, pertanto Update Session Status rifiuterebbe il reinvio. Riprova dopo l'intervallo indicato in `Retry-After`.", "content": { "application/json": { "examples": { "Backend-only resubmit throttled": { "value": { "detail": "This session was already resubmitted for backend-only features within the last 30 seconds; repeating it cannot change the outcome. Wait before resubmitting again." } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.preview_resubmission(\n \"11111111-2222-3333-4444-555555555555\",\n nodes_to_resubmit=[{\n \"node_id\": \"feature_poa_1\",\n \"feature\": \"POA\",\n }],\n email_language=\"en\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.previewResubmission(\"11111111-2222-3333-4444-555555555555\", {\n nodes_to_resubmit: [{\n node_id: \"feature_poa_1\",\n feature: \"POA\",\n }],\n email_language: \"en\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.PreviewResubmission(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsPreviewResubmissionParams{\n\tNodesToResubmit: didit.Some([]didit.SessionsPreviewResubmissionParamsNodesToResubmit{{\n\t\tNodeID: \"feature_poa_1\",\n\t\tFeature: \"POA\",\n\t}}),\n\tEmailLanguage: didit.String(\"en\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsPreviewResubmissionParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().previewResubmission(\"11111111-2222-3333-4444-555555555555\", SessionsPreviewResubmissionParams.builder()\n .nodesToResubmit(List.of(SessionsPreviewResubmissionParams.NodesToResubmit.builder()\n .nodeId(\"feature_poa_1\")\n .feature(SessionsPreviewResubmissionParams.NodesToResubmit.Feature.of(\"POA\"))\n .build()))\n .emailLanguage(\"en\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->previewResubmission('11111111-2222-3333-4444-555555555555', [\n 'nodes_to_resubmit' => [[\n 'node_id' => 'feature_poa_1',\n 'feature' => 'POA',\n ]],\n 'email_language' => 'en',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.preview_resubmission(\n \"11111111-2222-3333-4444-555555555555\",\n nodes_to_resubmit: [{\n node_id: \"feature_poa_1\",\n feature: \"POA\",\n }],\n email_language: \"en\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.PreviewResubmissionAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsPreviewResubmissionParams\n{\n NodesToResubmit = new SessionsPreviewResubmissionParamsNodesToResubmit[]\n {\n new()\n {\n NodeId = \"feature_poa_1\",\n Feature = \"POA\",\n },\n },\n EmailLanguage = \"en\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/": { "get": { "summary": "Recupera la regola di routing", "description": "Richiede `read:cases` per l'applicazione richiesta.", "operationId": "retrieve_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Riuscito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRule" } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." }, "404": { "description": "Record non trovato in questa applicazione." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Aggiorna la regola di instradamento", "description": "Richiede `write:cases` per l'applicazione richiesta.", "operationId": "update_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Riuscito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRule" } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." }, "404": { "description": "Record non trovato in questa applicazione." }, "409": { "description": "La regola di routing è cambiata rispetto a expected_version. Verifica la regola più recente prima di riprovare." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRuleUpdate" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n name=\"your-name\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.update(\"11111111-2222-3333-4444-555555555555\", {\n name: \"your-name\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseRoutingRuleUpdate{\n\tName: didit.String(\"your-name\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseRoutingRuleUpdate;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().update(\"11111111-2222-3333-4444-555555555555\", CaseRoutingRuleUpdate.builder()\n .name(\"your-name\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->update('11111111-2222-3333-4444-555555555555', [\n 'name' => 'your-name',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n name: \"your-name\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new CaseRoutingRuleUpdate\n{\n Name = \"your-name\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/case-requests/{request_uuid}/": { "get": { "operationId": "case_requests_retrieve", "x-didit-sdk": { "resource": "case_requests", "method": "retrieve", "auth": "device_token", "server": false }, "parameters": [ { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPublic" } } }, "description": "" }, "404": { "description": "La richiesta o il caso non è disponibile per questo chiamante." } }, "security": [ { "CaseRequestToken": [] } ], "description": "Accedi a una richiesta del cliente utilizzando il relativo token specifico della richiesta. Non vengono restituiti riscontri privati del caso, dati identificativi originali o l'indirizzo del destinatario. Le richieste su cui è possibile intervenire scadono dopo sette giorni. L'annullamento o la risoluzione del caso invalida il link. Le risposte sono immutabili e costituiscono prove per la valutazione del revisore; non approvano né aggiornano mai una verifica di origine." }, "post": { "operationId": "case_requests_create", "x-didit-sdk": { "resource": "case_requests", "method": "respond", "auth": "device_token", "server": false }, "parameters": [ { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseCustomerResponseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseCustomerResponseRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseCustomerResponseResult" } } }, "description": "" }, "404": { "description": "La richiesta o il caso non è disponibile per questo chiamante." }, "400": { "description": "Dati di input non validi, finalità non supportata, contatto verificato non disponibile o risposta immutabile già esistente." }, "409": { "description": "L'anteprima è cambiata o è scaduta. Visualizza nuovamente l'anteprima prima di confermare." } }, "security": [ { "CaseRequestToken": [] } ], "description": "Accedi a una richiesta del cliente utilizzando il relativo token specifico della richiesta. Non vengono restituiti riscontri privati del caso, dati identificativi originali o l'indirizzo del destinatario. Le richieste su cui è possibile intervenire scadono dopo sette giorni. L'annullamento o la risoluzione del caso invalida il link. Le risposte sono immutabili e costituiscono prove per la valutazione del revisore; non approvano né aggiornano mai una verifica di origine." } }, "/v3/fraud/checks/plan/": { "post": { "operationId": "plan_create", "x-didit-sdk": { "resource": "fraud_checks", "method": "plan", "auth": "api_key", "server": true }, "description": "Valida i controlli selezionati e stima il relativo prezzo senza eseguire, creare una sessione o addebitare costi.", "summary": "Pianificare un controllo antifrode", "tags": [ "Fraud Check" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" }, "example": { "client_reference": "review-attempt-001", "subject": { "identifiers": [ { "type": "email", "value": "applicant@example.com" } ], "attributes": { "first_name": "Alex", "last_name": "Example" } }, "checks": { "include": [ "networks_same_org", "networks_cross_org", "email_risk" ] } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckPlan" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudBadRequestErrorMessage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.fraud_checks.plan(\n client_reference=\"review-attempt-001\",\n subject={\n \"identifiers\": [{\n \"type\": \"email\",\n \"value\": \"applicant@example.com\",\n }],\n \"attributes\": {\n \"first_name\": \"Alex\",\n \"last_name\": \"Example\",\n },\n },\n checks={\n \"include\": [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.fraudChecks.plan({\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Plan(ctx, didit.FraudCheckRequestRequest{\n\tClientReference: didit.String(\"review-attempt-001\"),\n\tSubject: didit.FraudCheckSubjectRequest{\n\t\tIdentifiers: []didit.FraudCheckIdentifierRequest{{\n\t\t\tType: didit.FraudTypeEnum(\"email\"),\n\t\t\tValue: \"applicant@example.com\",\n\t\t}},\n\t\tAttributes: didit.Some(didit.FraudCheckAttributesRequest{\n\t\t\tFirstName: didit.String(\"Alex\"),\n\t\t\tLastName: didit.String(\"Example\"),\n\t\t}),\n\t},\n\tChecks: didit.Some(didit.FraudCheckModuleSelectionRequest{\n\t\tInclude: didit.Some([]didit.FraudExcludeEnum{didit.FraudExcludeEnum(\"networks_same_org\"), didit.FraudExcludeEnum(\"networks_cross_org\"), didit.FraudExcludeEnum(\"email_risk\")}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.FraudCheckAttributesRequest;\nimport me.didit.types.FraudCheckIdentifierRequest;\nimport me.didit.types.FraudCheckModuleSelectionRequest;\nimport me.didit.types.FraudCheckRequestRequest;\nimport me.didit.types.FraudCheckSubjectRequest;\nimport me.didit.types.FraudExcludeEnum;\nimport me.didit.types.FraudTypeEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.fraudChecks().plan(FraudCheckRequestRequest.builder()\n .clientReference(\"review-attempt-001\")\n .subject(FraudCheckSubjectRequest.builder()\n .identifiers(List.of(FraudCheckIdentifierRequest.builder()\n .type(FraudTypeEnum.of(\"email\"))\n .value(\"applicant@example.com\")\n .build()))\n .attributes(FraudCheckAttributesRequest.builder()\n .firstName(\"Alex\")\n .lastName(\"Example\")\n .build())\n .build())\n .checks(FraudCheckModuleSelectionRequest.builder()\n .include(List.of(FraudExcludeEnum.of(\"networks_same_org\"), FraudExcludeEnum.of(\"networks_cross_org\"), FraudExcludeEnum.of(\"email_risk\")))\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "fraudChecks->plan([\n 'client_reference' => 'review-attempt-001',\n 'subject' => [\n 'identifiers' => [[\n 'type' => 'email',\n 'value' => 'applicant@example.com',\n ]],\n 'attributes' => [\n 'first_name' => 'Alex',\n 'last_name' => 'Example',\n ],\n ],\n 'checks' => [\n 'include' => ['networks_same_org', 'networks_cross_org', 'email_risk'],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.fraud_checks.plan(\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FraudChecks.PlanAsync(new FraudCheckRequestRequest\n{\n ClientReference = \"review-attempt-001\",\n Subject = new()\n {\n Identifiers = new FraudCheckIdentifierRequest[]\n {\n new()\n {\n Type = \"email\",\n Value = \"applicant@example.com\",\n },\n },\n Attributes = new FraudCheckAttributesRequest\n {\n FirstName = \"Alex\",\n LastName = \"Example\",\n },\n },\n Checks = new FraudCheckModuleSelectionRequest\n {\n Include = new FraudExcludeEnum[] { \"networks_same_org\", \"networks_cross_org\", \"email_risk\" },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/": { "get": { "summary": "Elenca le regole di routing", "description": "Richiede `list:cases` per l'applicazione richiesta.", "operationId": "list_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Riuscito", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingRule" } }, "count": { "type": "integer", "description": "Conteggio delle corrispondenze, limitato a 100. Segui next per continuare oltre il limite." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.routing_rules.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.routingRules.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.RoutingRules.ListAutoPaging(ctx, didit.CasesRoutingRulesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().routingRules().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.routing_rules.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.RoutingRules.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "Crea regola di routing", "description": "Richiede `write:cases` per l'applicazione richiesta. Imposta publish=false per creare una bozza non pubblicata; Pubblica crea la sua prima versione attiva. L'eliminazione di una bozza mai pubblicata la cancella definitivamente.", "operationId": "create_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "responses": { "201": { "description": "Riuscito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRule" } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRuleCreate" }, "example": { "name": "AML screening alerts", "conditions": [ { "field": "source", "operator": "equals", "value": "AML_SCREENING" } ], "blueprint": "b1de0000-0000-4000-8000-000000000002" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.create(\n name=\"AML screening alerts\",\n conditions=[{\n \"field\": \"source\",\n \"operator\": \"equals\",\n \"value\": \"AML_SCREENING\",\n }],\n blueprint=\"b1de0000-0000-4000-8000-000000000002\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.create({\n name: \"AML screening alerts\",\n conditions: [{\n field: \"source\",\n operator: \"equals\",\n value: \"AML_SCREENING\",\n }],\n blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Create(ctx, didit.CaseRoutingRuleCreate{\n\tName: \"AML screening alerts\",\n\tConditions: []didit.CaseRoutingConditionParam{{\n\t\tField: \"source\",\n\t\tOperator: \"equals\",\n\t\tValue: \"AML_SCREENING\",\n\t}},\n\tBlueprint: \"b1de0000-0000-4000-8000-000000000002\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseRoutingCondition;\nimport me.didit.types.CaseRoutingRuleCreate;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().create(CaseRoutingRuleCreate.builder()\n .name(\"AML screening alerts\")\n .conditions(List.of(CaseRoutingCondition.builder()\n .field(CaseRoutingCondition.Field.of(\"source\"))\n .operator(CaseRoutingCondition.Operator.of(\"equals\"))\n .value(CaseRoutingCondition.Value.ofString(\"AML_SCREENING\"))\n .build()))\n .blueprint(\"b1de0000-0000-4000-8000-000000000002\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->create([\n 'name' => 'AML screening alerts',\n 'conditions' => [[\n 'field' => 'source',\n 'operator' => 'equals',\n 'value' => 'AML_SCREENING',\n ]],\n 'blueprint' => 'b1de0000-0000-4000-8000-000000000002',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.create(\n name: \"AML screening alerts\",\n conditions: [{\n field: \"source\",\n operator: \"equals\",\n value: \"AML_SCREENING\",\n }],\n blueprint: \"b1de0000-0000-4000-8000-000000000002\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.CreateAsync(new CaseRoutingRuleCreate\n{\n Name = \"AML screening alerts\",\n Conditions = new CaseRoutingCondition[]\n {\n new()\n {\n Field = \"source\",\n Operator = \"equals\",\n Value = \"AML_SCREENING\",\n },\n },\n Blueprint = \"b1de0000-0000-4000-8000-000000000002\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/publish/": { "post": { "operationId": "publish_case_routing_rule", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "publish", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationCaseRoutingRule" } } }, "description": "" }, "403": { "description": "L'accesso al caso è obbligatorio." }, "409": { "description": "La versione pubblicata o la revisione in bozza è cambiata. Ricarica prima di riprovare." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.publish(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Publish(ctx, \"11111111-2222-3333-4444-555555555555\", didit.RoutingPublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RoutingPublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().publish(\"11111111-2222-3333-4444-555555555555\", RoutingPublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->publish('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.PublishAsync(\"11111111-2222-3333-4444-555555555555\", new RoutingPublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/publish/": { "post": { "operationId": "publish_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "publish", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationCaseBlueprint" } } }, "description": "" }, "409": { "description": "La versione pubblicata o la revisione della bozza salvata è cambiata. Ricarica prima di riprovare." }, "403": { "description": "L'autorizzazione richiesta per il caso è mancante." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.publish(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Publish(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasePublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasePublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().publish(\"11111111-2222-3333-4444-555555555555\", CasePublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->publish('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.PublishAsync(\"11111111-2222-3333-4444-555555555555\", new CasePublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/preview/": { "post": { "operationId": "organization_application_cases_requests_preview_create", "x-didit-sdk": { "resource": "cases.requests", "method": "preview", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewResponse" } } }, "description": "" }, "404": { "description": "La richiesta o il caso non è disponibile per questo chiamante." }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." }, "400": { "description": "Dati di input non validi, finalità non supportata, contatto verificato non disponibile o risposta immutabile già esistente." }, "409": { "description": "L'anteprima è cambiata o è scaduta. Visualizza nuovamente l'anteprima prima di confermare." } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Genera l'anteprima dell'email di produzione senza inviare né modificare il caso. Restituisce il destinatario esatto, il mittente, l'oggetto, il corpo e un preview_token firmato. Invia gli stessi contact_id, purpose, language, request_id, expires_at e preview_token per confermare entro 15 minuti.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.preview(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id=\"11111111-2222-3333-4444-555555555555\",\n purpose=\"identity_document\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.preview(\"11111111-2222-3333-4444-555555555555\", {\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Preview(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CustomerMessagingCaseRequestPreviewRequest{\n\tContactID: \"11111111-2222-3333-4444-555555555555\",\n\tPurpose: didit.CustomerMessagingPurposeEnum(\"identity_document\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CustomerMessagingCaseRequestPreviewRequest;\nimport me.didit.types.CustomerMessagingPurposeEnum;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().preview(\"11111111-2222-3333-4444-555555555555\", CustomerMessagingCaseRequestPreviewRequest.builder()\n .contactId(\"11111111-2222-3333-4444-555555555555\")\n .purpose(CustomerMessagingPurposeEnum.of(\"identity_document\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->preview('11111111-2222-3333-4444-555555555555', [\n 'contact_id' => '11111111-2222-3333-4444-555555555555',\n 'purpose' => 'identity_document',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.preview(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.PreviewAsync(\"11111111-2222-3333-4444-555555555555\", new CustomerMessagingCaseRequestPreviewRequest\n{\n ContactId = \"11111111-2222-3333-4444-555555555555\",\n Purpose = \"identity_document\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/action-receipts/": { "get": { "operationId": "action_receipts_retrieve", "x-didit-sdk": { "resource": "cases", "method": "list_action_receipts", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "query", "name": "offset", "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0 } } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseActionReceiptPage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Elenca le ricevute soggetto-azione, in ordine dalla più recente alla meno recente, con un massimo di 20 risultati per pagina. Usa next_offset per la pagina successiva. Il testo della nota di input non viene mostrato nella cronologia.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.list_action_receipts(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.listActionReceipts(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ListActionReceipts(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesListActionReceiptsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().listActionReceipts(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->listActionReceipts('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.list_action_receipts(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ListActionReceiptsAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/{note_uuid}/": { "delete": { "operationId": "delete_network_note", "x-didit-sdk": { "resource": "networks.notes", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "Elimina la tua nota di rete", "description": "Richiede write:networks e l'autore autenticato della nota. L'eliminazione è irreversibile. I dati dell'account connesso e di verifica rimangono invariati.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID della rete." }, { "name": "note_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Token di accesso dell'utente della Console nel formato Bearer ." } ], "responses": { "204": { "description": "Nota eliminata." }, "401": { "description": "L'autenticazione è richiesta." }, "403": { "description": "Autorizzazione mancante o accesso Networks mancante." }, "404": { "description": "La rete o la nota non è visibile per questa applicazione." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\nclient.networks.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nawait didit.networks.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\nif err := client.Networks.Notes.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", didit.NetworksNotesDeleteParams{\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.core.RequestOptions;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nclient.networks().notes().delete(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build());" }, { "lang": "php", "label": "PHP", "source": "networks->notes->delete('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555', [\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\ndidit.networks.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nawait client.Networks.Notes.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n});" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/action-receipts/{receipt_uuid}/retry/": { "post": { "operationId": "action_receipts_retry_create", "x-didit-sdk": { "resource": "cases", "method": "retry_action_receipt", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "receipt_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseActionReceipt" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Riprova solo questa azione del soggetto non riuscita utilizzando i relativi input salvati. Viene verificata l'autorizzazione di scrittura corrente. Le azioni applicate restituiscono la relativa ricevuta senza essere eseguite di nuovo. La chiusura del caso è indipendente.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.retry_action_receipt(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.retryActionReceipt(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RetryActionReceipt(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().retryActionReceipt(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->retryActionReceipt('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.retry_action_receipt(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RetryActionReceiptAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/draft/": { "get": { "operationId": "get_case_blueprint_draft", "x-didit-sdk": { "resource": "cases.blueprints", "method": "retrieve_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftResponse" } } }, "description": "" }, "403": { "description": "L'autorizzazione richiesta per il caso è mancante." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.retrieve_draft(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.RetrieveDraft(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->retrieveDraft('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.retrieve_draft(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.RetrieveDraftAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "put": { "operationId": "save_case_blueprint_draft", "x-didit-sdk": { "resource": "cases.blueprints", "method": "save_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftWriteRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftWriteRequest" }, "example": { "expected_version": 1, "expected_revision": "4e5f0000-0000-4000-8000-000000000003", "changes": { "max_active_cases": 20 } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraft" } } }, "description": "" }, "409": { "description": "La versione pubblicata o la revisione della bozza salvata è cambiata. Ricarica prima di riprovare." }, "403": { "description": "L'autorizzazione richiesta per il caso è mancante." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=1,\n expected_revision=\"4e5f0000-0000-4000-8000-000000000003\",\n changes={\"max_active_cases\": 20},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.saveDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { max_active_cases: 20 },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.SaveDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasePublicationPolicyDraftWriteRequest{\n\tExpectedVersion: 1,\n\tExpectedRevision: didit.String(\"4e5f0000-0000-4000-8000-000000000003\"),\n\tChanges: map[string]any{\"max_active_cases\": 20},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.CasePublicationPolicyDraftWriteRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().saveDraft(\"11111111-2222-3333-4444-555555555555\", CasePublicationPolicyDraftWriteRequest.builder()\n .expectedVersion(1L)\n .expectedRevision(\"4e5f0000-0000-4000-8000-000000000003\")\n .changes(Map.of(\"max_active_cases\", 20))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->saveDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 1,\n 'expected_revision' => '4e5f0000-0000-4000-8000-000000000003',\n 'changes' => ['max_active_cases' => 20],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { max_active_cases: 20 }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.SaveDraftAsync(\"11111111-2222-3333-4444-555555555555\", new CasePublicationPolicyDraftWriteRequest\n{\n ExpectedVersion = 1,\n ExpectedRevision = \"4e5f0000-0000-4000-8000-000000000003\",\n Changes = new Dictionary { [\"max_active_cases\"] = 20 },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "operationId": "discard_case_blueprint_draft", "x-didit-sdk": { "resource": "cases.blueprints", "method": "discard_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "204": { "description": "Nessun corpo della risposta" }, "409": { "description": "La versione pubblicata o la revisione della bozza salvata è cambiata. Ricarica prima di riprovare." }, "403": { "description": "L'autorizzazione richiesta per il caso è mancante." } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.blueprints.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.blueprints.discardDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Blueprints.DiscardDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasePublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasePublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().blueprints().discardDraft(\"11111111-2222-3333-4444-555555555555\", CasePublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->discardDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Blueprints.DiscardDraftAsync(\"11111111-2222-3333-4444-555555555555\", new CasePublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/teams/{record_uuid}/": { "get": { "summary": "Recupera il team di revisione", "description": "Richiede `read:cases` per l'applicazione richiesta.", "operationId": "retrieve_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Riuscito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeam" } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." }, "404": { "description": "Record non trovato in questa applicazione." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.teams.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.teams.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Teams.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().teams().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->teams->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.teams.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Teams.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "Aggiorna il team di revisione", "description": "Richiede `write:cases` per l'applicazione richiesta.", "operationId": "update_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Riuscito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeam" } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." }, "404": { "description": "Record non trovato in questa applicazione." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeamUpdate" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.teams.update(\n \"11111111-2222-3333-4444-555555555555\",\n name=\"your-name\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.teams.update(\"11111111-2222-3333-4444-555555555555\", {\n name: \"your-name\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Teams.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseReviewTeamUpdate{\n\tName: didit.String(\"your-name\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseReviewTeamUpdate;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().teams().update(\"11111111-2222-3333-4444-555555555555\", CaseReviewTeamUpdate.builder()\n .name(\"your-name\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->teams->update('11111111-2222-3333-4444-555555555555', [\n 'name' => 'your-name',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.teams.update(\n \"11111111-2222-3333-4444-555555555555\",\n name: \"your-name\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Teams.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new CaseReviewTeamUpdate\n{\n Name = \"your-name\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/report/": { "get": { "operationId": "download_network_report", "x-didit-sdk": { "resource": "networks", "method": "download_report", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "Scarica un report probatorio della rete", "description": "Scarica un PDF della rete dell'organizzazione corrente, delle relative connessioni di account rilevate, dei riferimenti ai segnali e dello stato di revisione. Richiede read:networks. L'intelligence globale e le note private degli analisti non sono incluse. Ciascun elenco di account e segnali è limitato a 500 voci e il report indica se è incompleto. La richiesta non modifica lo stato della rete. Gli errori vengono restituiti in formato JSON.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID della rete." }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Token di accesso dell'utente della Console nel formato Bearer ." } ], "responses": { "200": { "description": "Report sulle prove di rete. Cache-Control: no-store.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "L'autenticazione è richiesta." }, "403": { "description": "Autorizzazione mancante o accesso Networks mancante." }, "404": { "description": "La rete o la nota non è visibile per questa applicazione." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\ncontent = client.networks.download_report(\n \"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nconst content = await didit.networks.downloadReport(\"11111111-2222-3333-4444-555555555555\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\nresp, err := client.Networks.DownloadReport(ctx, \"11111111-2222-3333-4444-555555555555\", didit.NetworksDownloadReportParams{\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.core.RequestOptions;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nclient.networks().downloadReport(\"11111111-2222-3333-4444-555555555555\", RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build())\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "networks->downloadReport('11111111-2222-3333-4444-555555555555', [\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]);\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\ncontent = didit.networks.download_report(\n \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nvar content = await client.Networks.DownloadReportAsync(\"11111111-2222-3333-4444-555555555555\", requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n});\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/": { "get": { "operationId": "list_network_notes", "x-didit-sdk": { "resource": "networks.notes", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "Elenca le note private della rete", "description": "Gli utenti della Console con read:networks possono leggere le note su una rete visibile all'applicazione. Le note rimangono all'interno dell'organizzazione e non contribuiscono all'intelligence condivisa. Le note più recenti compaiono per prime.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID della rete." }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Token di accesso dell'utente della Console nel formato Bearer ." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "Una pagina di note. Il conteggio è limitato a 100; usa next per continuare.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkNote" } } } } } } }, "401": { "description": "L'autenticazione è richiesta." }, "403": { "description": "Autorizzazione mancante o accesso Networks mancante." }, "404": { "description": "La rete o la nota non è visibile per questa applicazione." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\nfor item in client.networks.notes.list(\n \"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nfor await (const item of didit.networks.notes.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\niter := client.Networks.Notes.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.NetworksNotesListParams{\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.core.RequestOptions;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nfor (var item : client.networks().notes().list(\"11111111-2222-3333-4444-555555555555\", RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build())) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "networks->notes->list('11111111-2222-3333-4444-555555555555', [\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]) as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\ndidit.networks.notes.list(\n \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n).auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Networks.Notes.ListAsync(\"11111111-2222-3333-4444-555555555555\", requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n}))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "operationId": "create_network_note", "x-didit-sdk": { "resource": "networks.notes", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "Aggiungi una nota privata sulla rete", "description": "Richiede un utente della console con write:networks. L'autore viene assegnato a partire dall'utente autenticato. Fornisci un nuovo UUID casuale client_reference per ogni nota; riprova con lo stesso body e riferimento dopo una risposta incerta per evitare duplicati. Il riutilizzo di un riferimento per un altro body, autore o rete restituisce 409. Le note seguono l'indagine superstite in caso di unione delle reti.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID della rete." }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Token di accesso dell'utente della Console nel formato Bearer ." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "comment", "client_reference" ], "properties": { "comment": { "type": "string", "minLength": 1, "maxLength": 10000 }, "client_reference": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Nota privata salvata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkNote" } } } }, "200": { "description": "Nota privata salvata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkNote" } } } }, "400": { "description": "Nota non valida o vuota." }, "409": { "description": "Il riferimento è già stato utilizzato per un'altra nota." }, "401": { "description": "L'autenticazione è richiesta." }, "403": { "description": "Autorizzazione mancante o accesso Networks mancante." }, "404": { "description": "La rete o la nota non è visibile per questa applicazione." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\nresult = client.networks.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment=\"your-comment\",\n client_reference=\"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nconst result = await didit.networks.notes.create(\"11111111-2222-3333-4444-555555555555\", {\n comment: \"your-comment\",\n client_reference: \"11111111-2222-3333-4444-555555555555\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\nresult, err := client.Networks.Notes.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.NetworksNotesCreateParams{\n\tComment: \"your-comment\",\n\tClientReference: \"11111111-2222-3333-4444-555555555555\",\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.core.RequestOptions;\nimport me.didit.types.NetworksNotesCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nvar result = client.networks().notes().create(\"11111111-2222-3333-4444-555555555555\", NetworksNotesCreateParams.builder()\n .comment(\"your-comment\")\n .clientReference(\"11111111-2222-3333-4444-555555555555\")\n .build(), RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->notes->create('11111111-2222-3333-4444-555555555555', [\n 'comment' => 'your-comment',\n 'client_reference' => '11111111-2222-3333-4444-555555555555',\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\nresult = didit.networks.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment: \"your-comment\",\n client_reference: \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.Notes.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new NetworksNotesCreateParams\n{\n Comment = \"your-comment\",\n ClientReference = \"11111111-2222-3333-4444-555555555555\",\n}, requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/draft/": { "get": { "operationId": "get_case_routing_rule_draft", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "retrieve_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftResponse" } } }, "description": "" }, "403": { "description": "L'accesso al caso è obbligatorio." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.retrieve_draft(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.RetrieveDraft(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->retrieveDraft('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.retrieve_draft(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.RetrieveDraftAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "put": { "operationId": "save_case_routing_rule_draft", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "save_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftWriteRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftWriteRequest" }, "example": { "expected_version": 1, "expected_revision": "4e5f0000-0000-4000-8000-000000000003", "changes": { "priority": 10 } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraft" } } }, "description": "" }, "403": { "description": "L'accesso al caso è obbligatorio." }, "409": { "description": "La versione pubblicata o la revisione in bozza è cambiata. Ricarica prima di riprovare." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=1,\n expected_revision=\"4e5f0000-0000-4000-8000-000000000003\",\n changes={\"priority\": 10},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.saveDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { priority: 10 },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.SaveDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.RoutingPublicationPolicyDraftWriteRequest{\n\tExpectedVersion: 1,\n\tExpectedRevision: didit.String(\"4e5f0000-0000-4000-8000-000000000003\"),\n\tChanges: map[string]any{\"priority\": 10},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.RoutingPublicationPolicyDraftWriteRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().saveDraft(\"11111111-2222-3333-4444-555555555555\", RoutingPublicationPolicyDraftWriteRequest.builder()\n .expectedVersion(1L)\n .expectedRevision(\"4e5f0000-0000-4000-8000-000000000003\")\n .changes(Map.of(\"priority\", 10))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->saveDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 1,\n 'expected_revision' => '4e5f0000-0000-4000-8000-000000000003',\n 'changes' => ['priority' => 10],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { priority: 10 }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.SaveDraftAsync(\"11111111-2222-3333-4444-555555555555\", new RoutingPublicationPolicyDraftWriteRequest\n{\n ExpectedVersion = 1,\n ExpectedRevision = \"4e5f0000-0000-4000-8000-000000000003\",\n Changes = new Dictionary { [\"priority\"] = 10 },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "operationId": "discard_case_routing_rule_draft", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "discard_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "responses": { "204": { "description": "Nessun corpo della risposta" }, "403": { "description": "L'accesso al caso è obbligatorio." }, "409": { "description": "La versione pubblicata o la revisione in bozza è cambiata. Ricarica prima di riprovare." } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.routing_rules.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.routingRules.discardDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.RoutingRules.DiscardDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.RoutingPublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RoutingPublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().routingRules().discardDraft(\"11111111-2222-3333-4444-555555555555\", RoutingPublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->discardDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.routing_rules.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.RoutingRules.DiscardDraftAsync(\"11111111-2222-3333-4444-555555555555\", new RoutingPublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/duplicates/": { "post": { "operationId": "duplicates_create", "x-didit-sdk": { "resource": "cases", "method": "find_duplicates", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicateQueryRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicateQueryRequest" }, "example": { "subject": { "type": "user", "uuid": "5b9a0000-0000-4000-8000-00000000f00d" } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicateQueryRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicatePage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "Esamina i casi esistenti per un soggetto o un record di origine di proprietà prima della creazione manuale di un caso. Vengono restituite sia le indagini aperte che quelle risolte. Ciascuna pagina contiene al massimo 20 casi; usa next_offset per richiedere un'altra pagina.", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.find_duplicates(\n subject={\n \"type\": \"user\",\n \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.findDuplicates({\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.FindDuplicates(ctx, didit.CaseDuplicateCaseDuplicateQueryRequest{\n\tSubject: didit.Some(didit.CaseDuplicateCaseSubjectInputRequest{\n\t\tType: didit.CaseDuplicateTypeEnum(\"user\"),\n\t\tUUID: \"5b9a0000-0000-4000-8000-00000000f00d\",\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseDuplicateCaseDuplicateQueryRequest;\nimport me.didit.types.CaseDuplicateCaseSubjectInputRequest;\nimport me.didit.types.CaseDuplicateTypeEnum;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().findDuplicates(CaseDuplicateCaseDuplicateQueryRequest.builder()\n .subject(CaseDuplicateCaseSubjectInputRequest.builder()\n .type(CaseDuplicateTypeEnum.of(\"user\"))\n .uuid(\"5b9a0000-0000-4000-8000-00000000f00d\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->findDuplicates([\n 'subject' => [\n 'type' => 'user',\n 'uuid' => '5b9a0000-0000-4000-8000-00000000f00d',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.find_duplicates(\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.FindDuplicatesAsync(new CaseDuplicateCaseDuplicateQueryRequest\n{\n Subject = new CaseDuplicateCaseSubjectInputRequest\n {\n Type = \"user\",\n Uuid = \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/preview/": { "post": { "summary": "Routing del caso di test", "description": "Richiede `read:cases` per l'applicazione richiesta. Valuta le regole correnti o una bozza fornita rispetto all'accesso, alla disponibilità, alle competenze e alla capacità attuali del revisore. Non salva la bozza né riserva la capacità del revisore.", "operationId": "preview_case_routing", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "preview", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "responses": { "200": { "description": "Riuscito", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingPreview" } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingPreviewRequest" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.preview(\n source=\"MANUAL\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.preview({\n source: \"MANUAL\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Preview(ctx, didit.CaseRoutingPreviewRequest{\n\tSource: \"MANUAL\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseRoutingPreviewRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().preview(CaseRoutingPreviewRequest.builder()\n .source(CaseRoutingPreviewRequest.Source.of(\"MANUAL\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->preview([\n 'source' => 'MANUAL',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.preview(source: \"MANUAL\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.PreviewAsync(new CaseRoutingPreviewRequest\n{\n Source = \"MANUAL\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/reviewers/": { "get": { "summary": "Elenca i revisori di casi idonei", "description": "Richiede `list:cases` per l'applicazione richiesta.", "operationId": "list_case_reviewers", "x-didit-sdk": { "resource": "cases", "method": "list_reviewers", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "responses": { "200": { "description": "Riuscito", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } } } } } } } }, "400": { "description": "Dati di input non validi." }, "403": { "description": "Autorizzazione insufficiente." }, "503": { "description": "Impossibile verificare l'accesso del revisore. Riprova più tardi." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.list_reviewers()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.listReviewers();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ListReviewers(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().listReviewers();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->listReviewers();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.list_reviewers\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ListReviewersAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/history/": { "get": { "operationId": "list_case_blueprint_history", "x-didit-sdk": { "resource": "cases.blueprints", "method": "list_history", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "Quale campo utilizzare per ordinare i risultati.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Numero di risultati da restituire per pagina.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "L'indice iniziale da cui restituire i risultati.", "schema": { "type": "integer" } } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPaginatedPolicyRevisionList" } } }, "description": "" }, "403": { "description": "L'autorizzazione richiesta per il caso è mancante." } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.blueprints.list_history(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.blueprints.listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Blueprints.ListHistoryAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesBlueprintsListHistoryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().blueprints().listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->listHistory('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.list_history(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Blueprints.ListHistoryAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/documents/{documentId}/file/": { "get": { "summary": "Scarica un documento firmato", "description": "Scarica il PDF firmato di un documento di un passaggio di Firma elettronica. Usa il percorso `signed_file` di `signatures[].documents[]` nella decisione. Il PDF contiene il documento mostrato al firmatario con i valori dei relativi campi stampati e la pagina di prova (a meno che `signature_evidence_page` non sia disattivato). Un PDF Avanzato (AES) include anche la firma PAdES con la relativa marca temporale; un PDF Semplice non ha firma digitale, sigillo o marca temporale. Didit verifica il file confrontandolo con `sha256_signed` prima di restituirlo.\n\nFunziona per sessioni di Verifica degli utenti (KYC) e Verifica aziendale (KYB). Richiede `read:sessions`; la tua chiave API funziona. Consulta il [report della Firma elettronica](/it/core-technology/electronic-signature/report-electronic-signature#scarica-i-documenti-firmati).", "operationId": "get_v3_session_signature_document_file", "x-didit-sdk": { "resource": "sessions.signatures", "method": "download_document", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "La sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "Il passaggio di Firma elettronica: `node_id` dell'elemento in `signatures[]`.", "schema": { "type": "string", "example": "feature_signature" } }, { "name": "documentId", "in": "path", "required": true, "description": "`id` del documento in `signatures[].documents[]`.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Il PDF firmato.", "headers": { "Content-Disposition": { "description": "Allegato con il nome del file.", "schema": { "type": "string", "example": "attachment; filename=\"agreement-signed.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Credenziali mancanti o credenziale che non può leggere questa sessione. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "Nessun documento firmato corrispondente: la sessione, il passaggio o il documento non esiste, è stato eliminato o non è ancora stato firmato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Not signed yet": { "summary": "Il firmatario non ha firmato", "value": { "code": "signature_not_signed", "detail": "signature_not_signed" } }, "Unknown document": { "summary": "Nessun documento del genere in questo passaggio", "value": { "code": "signature_not_found", "detail": "signature_not_found" } } } } } }, "409": { "description": "Il file salvato non corrisponde più al suo SHA-256 registrato. Non viene restituito nulla.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Changed file": { "summary": "Il file archiviato non corrisponde al relativo hash", "value": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.signatures.download_document(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.signatures.downloadDocument(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Signatures.DownloadDocument(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().signatures().downloadDocument(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->downloadDocument('11111111-2222-3333-4444-555555555555', 'feature_signature', '11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.signatures.download_document(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Signatures.DownloadDocumentAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/evidence/": { "get": { "summary": "Scarica il documento probatorio della firma", "description": "Scarica il PDF probatorio di un firmatario: livello e formato, firmatario, indirizzo IP, ciascun documento con il relativo SHA-256 originale e i valori dei campi, lo SHA-256 di ogni file firmato e, per una firma avanzata (AES), la sessione di identità verificata, la conferma del codice, il certificato e la marca temporale. Usa il percorso `evidence_file` dell'elemento del firmatario in `signatures[]`.\n\nPassa sempre `signature_id` quando un passaggio di Verifica aziendale include più firmatari: in caso contrario, il percorso seleziona uno dei firmatari del passaggio. Richiede `read:sessions`; la tua chiave API funziona.", "operationId": "get_v3_session_signature_evidence", "x-didit-sdk": { "resource": "sessions.signatures", "method": "download_evidence", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "La sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "Il passaggio di Firma elettronica: `node_id` dell'elemento in `signatures[]`.", "schema": { "type": "string", "example": "feature_signature" } }, { "name": "signature_id", "in": "query", "required": false, "description": "`id` dell'elemento del firmatario in `signatures[]`.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Il PDF delle prove.", "headers": { "Content-Disposition": { "description": "Allegato con il nome del file.", "schema": { "type": "string", "example": "attachment; filename=\"signature-evidence.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Credenziali mancanti o credenziale che non può leggere questa sessione. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "Nessuna prova corrisponde: la sessione, il passaggio o il firmatario non esiste, è stato eliminato o non ha firmato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Not signed yet": { "summary": "Il firmatario non ha firmato", "value": { "code": "signature_not_signed", "detail": "signature_not_signed" } }, "Unknown signer": { "summary": "Nessuna firma del genere in questo passaggio", "value": { "code": "signature_not_found", "detail": "signature_not_found" } } } } } }, "409": { "description": "Il file salvato non corrisponde più al suo SHA-256 registrato. Non viene restituito nulla.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Changed file": { "summary": "Il file archiviato non corrisponde al relativo hash", "value": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.signatures.download_evidence(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.signatures.downloadEvidence(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n);\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Signatures.DownloadEvidence(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", didit.SessionsSignaturesDownloadEvidenceParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().signatures().downloadEvidence(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->downloadEvidence('11111111-2222-3333-4444-555555555555', 'feature_signature');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.signatures.download_evidence(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\"\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Signatures.DownloadEvidenceAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/fields/{fieldId}/image/": { "get": { "summary": "Scarica l'immagine della firma", "description": "Scarica la firma o le sigle apposte da un firmatario su un campo, in formato PNG. Usa l'`image_url` del campo in `signatures[].documents[].fields[]`. Richiede `read:sessions`; la tua chiave API funziona.", "operationId": "get_v3_session_signature_field_image", "x-didit-sdk": { "resource": "sessions.signatures", "method": "download_field_image", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "La sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "Il passaggio di Firma elettronica: `node_id` dell'elemento in `signatures[]`.", "schema": { "type": "string", "example": "feature_signature" } }, { "name": "fieldId", "in": "path", "required": true, "description": "Il campo sulla copia di questo firmatario, come nel valore `image_url` del campo.", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "L'immagine.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "L'immagine salvata non corrisponde più al suo SHA-256 registrato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "example": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } }, "403": { "description": "Credenziali mancanti o credenziale che non può leggere questa sessione. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "Nessuna immagine corrisponde: la sessione, il passaggio o il campo non esiste, è stato eliminato o non presenta una firma o sigle applicate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Unknown field": { "summary": "Nessun campo del genere", "value": { "code": "signature_field_not_found", "detail": "signature_field_not_found" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.signatures.download_field_image(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.png\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.signatures.downloadFieldImage(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nawait writeFile(\"download.png\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Signatures.DownloadFieldImage(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.png\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().signatures().downloadFieldImage(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.png\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->downloadFieldImage('11111111-2222-3333-4444-555555555555', 'feature_signature', '11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.png');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.signatures.download_field_image(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nFile.binwrite(\"download.png\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Signatures.DownloadFieldImageAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.png\");" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/validate/": { "post": { "summary": "Valida nuovamente le firme", "description": "Verifica di nuovo i documenti firmati di un passaggio di Firma elettronica. Didit rilegge ogni PDF firmato, ne verifica lo SHA-256 e, per una firma avanzata (AES), convalida la firma PAdES, il certificato, i dati di revoca e la marcatura temporale (una firma semplice non ha firma digitale, quindi viene verificata solo l'integrità del file), quindi salva il risultato nella `validation` di ciascun firmatario e restituisce gli elementi aggiornati. Nessun elemento viene firmato nuovamente. Invia `signature_id` per verificare un singolo firmatario; senza di esso, viene verificato ogni firmatario del passaggio e la chiamata fallisce se uno qualsiasi di essi non ha firmato.\n\nRichiede `write:sessions`; la tua chiave API funziona. Nella console corrisponde al pulsante **Validate again**.", "operationId": "post_v3_session_signature_validate", "x-didit-sdk": { "resource": "sessions.signatures", "method": "validate", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "La sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "Il passaggio di Firma elettronica: `node_id` dell'elemento in `signatures[]`.", "schema": { "type": "string", "example": "feature_signature" } } ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature_id": { "type": "string", "format": "uuid", "description": "`id` dell'elemento di un firmatario in `signatures[]`." } } }, "example": { "signature_id": "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10" } } } }, "responses": { "200": { "description": "I firmatari verificati, con la rispettiva `validation` aggiornata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/SignatureResult" } } } } } } }, "400": { "description": "Un PDF firmato archiviato non corrisponde più all'hash SHA-256 registrato al momento della firma.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Document changed": { "summary": "Un file firmato non corrisponde più al suo hash", "value": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } } } }, "403": { "description": "Credenziali mancanti o credenziale che non può leggere questa sessione. L'assenza della chiave restituisce `403`; una chiave errata, revocata o scaduta restituisce `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "Nessuna firma corrispondente: la sessione, il passaggio o il firmatario non esiste o è stato eliminato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Unknown signer": { "summary": "Nessuna firma del genere in questo passaggio", "value": { "code": "signature_not_found", "detail": "signature_not_found" } } } } } }, "409": { "description": "Un firmatario del passaggio non ha ancora firmato, quindi non c'è nulla da convalidare.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Not signed": { "summary": "Un firmatario non ha ancora firmato", "value": { "code": "signature_not_signed", "detail": "signature_not_signed" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.signatures.validate(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n signature_id=\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.signatures.validate(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n {\n signature_id: \"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Signatures.Validate(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", didit.SessionsSignaturesValidateParams{\n\tSignatureID: didit.String(\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsSignaturesValidateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().signatures().validate(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", SessionsSignaturesValidateParams.builder()\n .signatureId(\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->validate('11111111-2222-3333-4444-555555555555', 'feature_signature', [\n 'signature_id' => '0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.signatures.validate(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n signature_id: \"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Signatures.ValidateAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", new SessionsSignaturesValidateParams\n{\n SignatureId = \"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/document-ai/{sessionId}/documents/{documentUuid}/": { "patch": { "summary": "Aggiorna un documento di Document AI", "description": "Correggi i campi estratti da Document AI da un documento caricato, imposta il suo stato di revisione, o entrambi, su una sessione KYC o KYB. `extracted_data` deve essere un oggetto JSON e viene unito chiave per chiave: una chiave inviata sostituisce il valore memorizzato (una chiave inviata come `null` viene memorizzata come `null`) e le chiavi omesse mantengono i propri valori. Lo stato del documento alimenta il risultato Document AI del relativo nodo del workflow nella decisione della sessione; lo stato della sessione non viene ricalcolato. Ogni chiamata riuscita, inclusa quella che non apporta modifiche, invia un [webhook](https://docs.didit.me/it/integration/webhooks) `data.updated` con trigger `manual_review`. Una chiave API con restrizioni necessita di `decisions: write`; vedi [Document AI](https://docs.didit.me/it/core-technology/document-ai/overview).", "operationId": "patch_v3_document_ai_document", "x-didit-sdk": { "resource": "sessions", "method": "update_document_ai_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica (il `session_id` restituito da `POST /v3/session/`). Accetta sia ID di sessione di Verifica degli utenti (KYC) sia di Verifica aziendale (KYB): il server risolve l'ID per entrambi i tipi di sessione. Deve essere un UUID ben formato; un valore malformato non corrisponde alla route e restituisce una pagina HTML `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "documentUuid", "in": "path", "required": true, "description": "UUID del documento Document AI (`document_ai_documents[].items[].uuid` in `GET /v3/session/{sessionId}/decision/`). Deve appartenere alla sessione indicata nel percorso.", "schema": { "type": "string", "format": "uuid", "example": "44444444-5555-6666-7777-888888888888" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "extracted_data": { "type": "object", "additionalProperties": true, "description": "Chiavi di campo (le chiavi configurate per il documento) e i relativi valori corretti. Deve essere un oggetto JSON; unito chiave per chiave nei dati memorizzati. Omettilo invece di inviare `null`, che restituisce `400`.", "example": { "invoice_number": "INV-2026-0042" } }, "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Not Finished" ], "description": "Nuovo stato di revisione del documento.", "example": "Approved" } } }, "example": { "extracted_data": { "invoice_number": "INV-2026-0042" }, "status": "Approved" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/document-ai/11111111-2222-3333-4444-555555555555/documents/44444444-5555-6666-7777-888888888888/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"extracted_data\": {\"invoice_number\": \"INV-2026-0042\"}, \"status\": \"Approved\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_document_ai_data(\n \"11111111-2222-3333-4444-555555555555\",\n \"44444444-5555-6666-7777-888888888888\",\n extracted_data={\"invoice_number\": \"INV-2026-0042\"},\n status=\"Approved\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateDocumentAiData(\n \"11111111-2222-3333-4444-555555555555\",\n \"44444444-5555-6666-7777-888888888888\",\n {\n extracted_data: { invoice_number: \"INV-2026-0042\" },\n status: \"Approved\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateDocumentAiData(ctx, \"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", didit.SessionsUpdateDocumentAiDataParams{\n\tExtractedData: didit.Some(map[string]any{\"invoice_number\": \"INV-2026-0042\"}),\n\tStatus: didit.Some(didit.SessionsUpdateDocumentAiDataParamsStatus(\"Approved\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdateDocumentAiDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateDocumentAiData(\"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", SessionsUpdateDocumentAiDataParams.builder()\n .extractedData(Map.of(\"invoice_number\", \"INV-2026-0042\"))\n .status(SessionsUpdateDocumentAiDataParams.Status.of(\"Approved\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateDocumentAiData('11111111-2222-3333-4444-555555555555', '44444444-5555-6666-7777-888888888888', [\n 'extracted_data' => ['invoice_number' => 'INV-2026-0042'],\n 'status' => 'Approved',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_document_ai_data(\n \"11111111-2222-3333-4444-555555555555\",\n \"44444444-5555-6666-7777-888888888888\",\n extracted_data: { invoice_number: \"INV-2026-0042\" },\n status: \"Approved\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateDocumentAiDataAsync(\"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", new SessionsUpdateDocumentAiDataParams\n{\n ExtractedData = new Dictionary { [\"invoice_number\"] = \"INV-2026-0042\" },\n Status = new SessionsUpdateDocumentAiDataParamsStatus(\"Approved\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Documento aggiornato. Restituisce il documento dopo l'unione.", "content": { "application/json": { "schema": { "type": "object", "required": [ "uuid", "document_key", "original_filename", "file_url", "status", "extracted_data" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificativo del documento." }, "document_key": { "type": "string", "description": "Il documento configurato a cui corrisponde questo caricamento." }, "original_filename": { "type": "string", "nullable": true, "description": "Nome del file con cui è stato caricato il documento." }, "file_url": { "type": "string", "nullable": true, "description": "Percorso di archiviazione del file caricato. Non è un link di download: leggi la `file_url` pre-firmata dalla decisione della sessione per scaricare il file." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato di revisione del documento." }, "extracted_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Tutti i campi estratti dopo l'unione, indicizzati per chiave di campo." } } }, "example": { "uuid": "44444444-5555-6666-7777-888888888888", "document_key": "invoice", "original_filename": "invoice-2026-09.pdf", "file_url": "document_ai/11111111-2222-3333-4444-555555555555-66666666-7777-8888-9999-000000000000.pdf", "status": "Approved", "extracted_data": { "invoice_number": "INV-2026-0042", "total_amount": 1250.0, "issue_date": "2026-09-01" } } } } }, "400": { "description": "Errore di validazione, verificato prima della ricerca del documento: `status` non rientra tra i valori consentiti, oppure `extracted_data` inviato come `null`.", "content": { "application/json": { "examples": { "Invalid status": { "summary": "status non è presente nell'enum", "value": { "status": [ "\"Rejected\" is not a valid choice." ] } }, "Null extracted_data": { "summary": "extracted_data è null", "value": { "extracted_data": [ "This field may not be null." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata o non rientra nei limiti di una chiave con ambito limitato, oppure nessun documento corrente con questo UUID vi appartiene. La ricerca della sessione viene eseguita prima della verifica delle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche senza una chiave valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID esiste, oppure è stata eliminata", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "La sessione non rientra nei limiti di una chiave con ambito limitato (restituito anche per una sessione eliminata pochi istanti prima)", "value": { "detail": "Session not found." } }, "Unknown document": { "summary": "documentUuid non appartiene alla sessione", "value": { "detail": "Document AI document not found." } } } } } }, "429": { "description": "Limite di frequenza superato: 300 richieste di scrittura (POST, PATCH, DELETE) al minuto per chiave API. Attendi i secondi indicati in `Retry-After` prima di riprovare; le intestazioni `X-RateLimit-*` indicano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/aml/dataset-freshness/": { "get": { "summary": "Recupera lo stato di aggiornamento dei dataset AML", "description": "Riporta il grado di aggiornamento dei set di dati alla base dello screening AML, per famiglia di fonti (`sanctions`, `pep`, `warnings`, `adverse_media`), come prova di audit per il [monitoraggio AML continuo](https://docs.didit.me/it/core-technology/aml-screening/continuous-monitoring-aml-screening#dimostrare-l’avvenuta-esecuzione-del-monitoraggio). La risposta riguarda l'intera piattaforma: nessuna sessione nel percorso, nessun dato del cliente nel corpo, la stessa risposta per ogni applicazione.\n\nSempre `200` per una chiave accettata. Controlla prima `availability`: quando non è `available`, `dataset_freshness` è `null`. Le date non vengono mai stimate: una famiglia i cui set di dati non hanno riportato alcuna data è assente da `sources`, e una famiglia in cui solo alcuni set di dati ne hanno riportata una presenta `oldest_updated_at: null`. Le rilevazioni vengono effettuate durante l'esecuzione del monitoraggio continuo, non a ogni chiamata; `captured_at` indica quando.\n\nUna chiave API con ambito limitato richiede `sessions: read`; una chiave limitata ad alcuni workflow o a sessioni approvate non può chiamare questo endpoint. Non viene fatturato nulla.", "operationId": "get_aml_dataset_freshness", "x-didit-sdk": { "resource": "aml", "method": "retrieve_dataset_freshness", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/aml/dataset-freshness/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.aml.retrieve_dataset_freshness()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.aml.retrieveDatasetFreshness();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AML.RetrieveDatasetFreshness(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.aml().retrieveDatasetFreshness();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "aml->retrieveDatasetFreshness();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.aml.retrieve_dataset_freshness\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Aml.RetrieveDatasetFreshnessAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La lettura più recente della freschezza del dataset, o `null` con il motivo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset_freshness", "availability" ], "properties": { "dataset_freshness": { "allOf": [ { "$ref": "#/components/schemas/AMLDatasetFreshness" } ], "nullable": true, "description": "La lettura più recente, o `null` quando `availability` non è `available`." }, "availability": { "type": "string", "enum": [ "available", "not_configured", "not_yet_collected" ], "description": "`available` quando è presente una lettura; `not_configured` quando le date dei set di dati non vengono raccolte in questo ambiente; `not_yet_collected` quando la raccolta è configurata ma non esiste ancora alcuna lettura." } } }, "examples": { "Available": { "value": { "dataset_freshness": { "captured_at": "2026-10-17T06:00:12.345678+00:00", "provider": "aml_data_source", "catalog_version": "20261017054500-abc", "sources": { "sanctions": { "last_updated_at": "2026-10-17T04:10:00+00:00", "oldest_updated_at": "2026-10-15T22:30:00+00:00", "dataset_count": 48, "dated_dataset_count": 48 }, "pep": { "last_updated_at": "2026-10-16T23:05:00+00:00", "oldest_updated_at": null, "dataset_count": 12, "dated_dataset_count": 11 } } }, "availability": "available" } }, "Not collected yet": { "value": { "dataset_freshness": null, "availability": "not_yet_collected" } } } } } }, "401": { "description": "La chiave API è scaduta. Solo una chiave creata con una data di scadenza può scadere; dopo tale data ogni richiesta inviata con essa risponde con `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave mancante riceve il messaggio generico; una chiave errata, revocata o scaduta riceve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "value": { "detail": "This API key has no read access to sessions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Più di 600 richieste GET al minuto con questa chiave API. Attendi il numero di secondi indicato in `Retry-After`, quindi riprova.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi fino al ripristino della finestra temporale corrente di un minuto.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Richieste consentite al minuto per questo budget.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Ora Unix in cui la finestra si azzera.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/": { "get": { "summary": "Elenca le liste", "description": "Restituisce le liste dell'applicazione, a partire dalla più recente: le liste di sistema fornite da Didit (una blocklist per tipo di voce, la lista personalizzata **High Risk Countries** ed eventuali allowlist di sistema) e le allowlist e liste personalizzate che hai creato. Filtra con `list_type` e `entry_type`; le liste eliminate non compaiono mai. I risultati sono impaginati con `limit` e `offset`. Una chiave API con ambito limitato richiede `workflows: read`. Consulta [Liste](https://docs.didit.me/it/management-api/lists/overview) per scoprire lo scopo di ciascun tipo di lista.", "operationId": "list_lists", "x-didit-sdk": { "resource": "lists", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_type", "in": "query", "required": false, "description": "Solo liste di questo tipo.", "schema": { "type": "string", "enum": [ "blocklist", "allowlist", "custom" ] } }, { "name": "entry_type", "in": "query", "required": false, "description": "Solo liste di questo tipo di voce.", "schema": { "type": "string", "enum": [ "face", "document", "phone", "email", "ip_address", "device_fingerprint", "wallet_address", "bank_account", "country", "user", "business", "key" ] } }, { "name": "ordering", "in": "query", "required": false, "description": "Ordinamento: `-created_at` (i più recenti per primi, valore predefinito) o `created_at` (i meno recenti per primi).", "schema": { "type": "string", "enum": [ "-created_at", "created_at" ], "default": "-created_at" } }, { "name": "limit", "in": "query", "required": false, "description": "Dimensione della pagina. Il valore predefinito è 50. Un valore superiore a 1000000 restituisce `400`; zero, un valore negativo o non numerico utilizza 50 come valore predefinito.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 } }, { "name": "offset", "in": "query", "required": false, "description": "Indice in base zero del primo elemento da restituire. È preferibile seguire `next`. Un valore superiore a 1000000 restituisce `400`; un valore negativo o non numerico reimposta a 0.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/lists/?list_type=blocklist' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.lists.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.lists.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Lists.ListAutoPaging(ctx, didit.ListsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.lists().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "lists->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Lists.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina di elenchi.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Numero totale di liste corrispondenti ai filtri." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceList" } } } }, "examples": { "Lists": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "22222222-3333-4444-5555-666666666666", "name": "Trusted office IPs", "description": "Office egress ranges", "list_type": "allowlist", "entry_type": "ip_address", "is_system": false, "entry_count": 3, "last_entry_added_at": "2026-10-02T08:15:27.501334Z", "created_at": "2026-09-30T13:20:45.889120Z", "updated_at": "2026-09-30T13:20:45.889120Z" }, { "uuid": "11111111-2222-3333-4444-555555555555", "name": "Face Blocklist", "description": "Blocked biometric faces. When a face matching an entry in this list is detected during liveness verification, the session will be automatically declined.", "list_type": "blocklist", "entry_type": "face", "is_system": true, "entry_count": 12, "last_entry_added_at": "2026-10-09T16:42:03.118204Z", "created_at": "2026-01-14T10:02:11.402917Z", "updated_at": "2026-01-14T10:02:11.402917Z" } ] } } } } } }, "400": { "description": "Un parametro di query non è valido.", "content": { "application/json": { "examples": { "Unknown list type": { "value": { "list_type": [ "\"denylist\" is not a valid choice." ] } }, "Unsupported ordering": { "value": { "ordering": [ "\"name\" is not a valid choice." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: read` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "429": { "description": "Il limite di lettura condiviso di 600 richieste al minuto per chiave API è stato superato. Rispetta `Retry-After` prima di riprovare.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea una lista", "description": "Crea un'allowlist o una lista personalizzata nell'applicazione a cui appartiene la chiave API. Le blocklist non possono essere create: Didit predispone una blocklist di sistema per ogni tipo di voce, a cui puoi aggiungere elementi con [Crea una voce della lista](https://docs.didit.me/it/management-api/lists/create-entry). `entry_type` non può essere modificato dopo la creazione e stabilisce come i valori delle voci vengono convalidati e confrontati. Le voci dell'allowlist contrassegnano gli elementi corrispondenti come attendibili (ad esempio, un'allowlist dei volti salta l'azione per volto duplicato) e non sovrascrivono mai una corrispondenza con la blocklist; fai riferimento a qualsiasi lista da una condizione di una regola di workflow o di transazione con `value_type: \"list\"`. Una chiave API con ambito limitato richiede `workflows: write`.", "operationId": "create_list", "x-didit-sdk": { "resource": "lists", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "list_type", "entry_type" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Nome della lista. Deve differire dal nome di ogni altra lista dell'applicazione, incluse le liste di sistema." }, "description": { "type": "string", "default": "", "description": "Descrizione opzionale a testo libero." }, "list_type": { "type": "string", "enum": [ "allowlist", "custom" ], "description": "`allowlist` o `custom`. `blocklist` viene rifiutato con `400`." }, "entry_type": { "type": "string", "enum": [ "face", "document", "phone", "email", "ip_address", "device_fingerprint", "wallet_address", "bank_account", "country", "user", "business", "key" ], "description": "Cosa contiene la lista: `face`, `document` (numero del documento), `phone`, `email`, `ip_address` (indirizzo o intervallo CIDR), `device_fingerprint`, `wallet_address`, `bank_account`, `country` (ISO 3166-1 alpha-3), `user` o `business` (il tuo `vendor_data`), oppure `key` (qualsiasi stringa). Determina come vengono convalidati e confrontati i valori delle voci. Non può essere modificata in seguito." } } }, "examples": { "IP allowlist": { "value": { "name": "Trusted office IPs", "description": "Office egress ranges", "list_type": "allowlist", "entry_type": "ip_address" } }, "Custom country list": { "value": { "name": "Enhanced due diligence countries", "list_type": "custom", "entry_type": "country" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/lists/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"name\": \"Trusted office IPs\",\n \"description\": \"Office egress ranges\",\n \"list_type\": \"allowlist\",\n \"entry_type\": \"ip_address\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.create(\n name=\"Trusted office IPs\",\n description=\"Office egress ranges\",\n list_type=\"allowlist\",\n entry_type=\"ip_address\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.create({\n name: \"Trusted office IPs\",\n description: \"Office egress ranges\",\n list_type: \"allowlist\",\n entry_type: \"ip_address\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Create(ctx, didit.ListsCreateParams{\n\tName: \"Trusted office IPs\",\n\tDescription: didit.String(\"Office egress ranges\"),\n\tListType: \"allowlist\",\n\tEntryType: \"ip_address\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().create(ListsCreateParams.builder()\n .name(\"Trusted office IPs\")\n .description(\"Office egress ranges\")\n .listType(ListsCreateParams.ListType.of(\"allowlist\"))\n .entryType(ListsCreateParams.EntryType.of(\"ip_address\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->create([\n 'name' => 'Trusted office IPs',\n 'description' => 'Office egress ranges',\n 'list_type' => 'allowlist',\n 'entry_type' => 'ip_address',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.create(\n name: \"Trusted office IPs\",\n description: \"Office egress ranges\",\n list_type: \"allowlist\",\n entry_type: \"ip_address\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.CreateAsync(new ListsCreateParams\n{\n Name = \"Trusted office IPs\",\n Description = \"Office egress ranges\",\n ListType = \"allowlist\",\n EntryType = \"ip_address\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "La lista è stata creata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceList" }, "examples": { "New allowlist": { "value": { "uuid": "22222222-3333-4444-5555-666666666666", "name": "Trusted office IPs", "description": "Office egress ranges", "list_type": "allowlist", "entry_type": "ip_address", "is_system": false, "entry_count": 0, "last_entry_added_at": null, "created_at": "2026-10-12T09:15:44.031876Z", "updated_at": "2026-10-12T09:15:44.031876Z" } } } } } }, "400": { "description": "Il corpo non è valido.", "content": { "application/json": { "examples": { "Blocklist refused": { "value": { "list_type": [ "Cannot create additional blocklist lists. System blocklists are auto-created for each application." ] } }, "Duplicate name": { "value": { "name": [ "A list with this name already exists for this application." ] } }, "Missing fields": { "value": { "name": [ "This field is required." ], "list_type": [ "This field is required." ], "entry_type": [ "This field is required." ] } }, "Unknown entry type": { "value": { "entry_type": [ "\"iban\" is not a valid choice." ] } }, "Name too long": { "value": { "name": [ "Ensure this field has no more than 255 characters." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: write` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/": { "get": { "summary": "Recupera una lista", "description": "Restituisce una lista dell'applicazione indicando il relativo conteggio delle voci e quando è stata aggiunta la voce più recente. Una lista di un'altra applicazione, o una che è stata eliminata, restituisce `404`. Questo restituisce solo la lista: leggine i valori con [Elenca le voci della lista](https://docs.didit.me/it/management-api/lists/list-entries). Una chiave API con ambito limitato richiede `workflows: read`.", "operationId": "get_list", "x-didit-sdk": { "resource": "lists", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID della lista, come restituito da List lists o Create a list.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La lista.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceList" }, "examples": { "System face blocklist": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "name": "Face Blocklist", "description": "Blocked biometric faces. When a face matching an entry in this list is detected during liveness verification, the session will be automatically declined.", "list_type": "blocklist", "entry_type": "face", "is_system": true, "entry_count": 12, "last_entry_added_at": "2026-10-09T16:42:03.118204Z", "created_at": "2026-01-14T10:02:11.402917Z", "updated_at": "2026-01-14T10:02:11.402917Z" } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: read` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "404": { "description": "Nessuna lista con questo UUID esiste nell'applicazione della chiave API, oppure è stata eliminata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No List matches the given query." } } } } } }, "429": { "description": "Il limite di lettura condiviso di 600 richieste al minuto per chiave API è stato superato. Rispetta `Retry-After` prima di riprovare.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna una lista", "description": "Rinomina una lista o ne modifica la descrizione. Vengono letti solo `name` e `description`; qualsiasi altro campo viene ignorato, quindi `list_type` ed `entry_type` mantengono i valori con cui sono stati creati. Le liste di sistema non possono essere modificate e restituiscono `400`. La risposta contiene solo `name` e `description`: chiama [Ottieni una lista](https://docs.didit.me/it/management-api/lists/get) per ottenere la lista completa. Una chiave API con ambito limitato richiede `workflows: write`.", "operationId": "update_list", "x-didit-sdk": { "resource": "lists", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID della lista, come restituito da List lists o Create a list.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Nuovo nome. Deve essere diverso dal nome di qualsiasi altra lista dell'applicazione." }, "description": { "type": "string", "description": "Nuova descrizione. Invia una stringa vuota per rimuoverla." } } }, "examples": { "Rename": { "value": { "name": "Trusted office and VPN IPs" } }, "Rename and describe": { "value": { "name": "Trusted office and VPN IPs", "description": "Office egress ranges and the corporate VPN" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"Trusted office and VPN IPs\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.update(\n \"11111111-2222-3333-4444-555555555555\",\n name=\"Trusted office and VPN IPs\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.update(\"11111111-2222-3333-4444-555555555555\", {\n name: \"Trusted office and VPN IPs\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsUpdateParams{\n\tName: didit.String(\"Trusted office and VPN IPs\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().update(\"11111111-2222-3333-4444-555555555555\", ListsUpdateParams.builder()\n .name(\"Trusted office and VPN IPs\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->update('11111111-2222-3333-4444-555555555555', [\n 'name' => 'Trusted office and VPN IPs',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.update(\n \"11111111-2222-3333-4444-555555555555\",\n name: \"Trusted office and VPN IPs\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new ListsUpdateParams\n{\n Name = \"Trusted office and VPN IPs\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La lista è stata aggiornata. Vengono restituiti solo i campi modificabili.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string", "description": "Il nome della lista dopo l'aggiornamento." }, "description": { "type": "string", "description": "La descrizione della lista dopo l'aggiornamento." } } }, "examples": { "Renamed": { "value": { "name": "Trusted office and VPN IPs", "description": "Office egress ranges" } } } } } }, "400": { "description": "La lista è una lista di sistema oppure il corpo non è valido.", "content": { "application/json": { "examples": { "System list": { "value": { "non_field_errors": [ "System lists cannot be modified." ] } }, "Duplicate name": { "value": { "name": [ "A list with this name already exists for this application." ] } }, "Blank name": { "value": { "name": [ "This field may not be blank." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: write` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Nessuna lista con questo UUID esiste nell'applicazione della chiave API, oppure è stata eliminata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No List matches the given query." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Elimina una lista", "description": "Elimina una lista consentita o una lista personalizzata insieme alle relative voci. L'eliminazione è irreversibile: la lista e le sue voci non compaiono più in alcuna lettura, e le condizioni delle regole del workflow e delle transazioni che fanno riferimento alla lista la valuteranno d'ora in poi come una lista vuota. Le sessioni e le transazioni già valutate mantengono i propri risultati, e il nome può essere riutilizzato per una nuova lista. Le liste di sistema non possono essere eliminate e restituiscono `400`; per svuotarne una, [elimina le relative voci](https://docs.didit.me/it/management-api/lists/delete-entry). Una chiave API con ambito limitato richiede `workflows: write`.", "operationId": "delete_list", "x-didit-sdk": { "resource": "lists", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID della lista, come restituito da List lists o Create a list.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.lists.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.lists.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Lists.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.lists().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "lists->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Lists.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "La lista e le relative voci sono state eliminate. Nessun corpo." }, "400": { "description": "La lista è una lista di sistema.", "content": { "application/json": { "examples": { "System list": { "value": { "detail": "System lists cannot be deleted." } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: write` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Nessuna lista con questo UUID esiste nell'applicazione della chiave API, oppure è già stata eliminata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No List matches the given query." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/entries/": { "get": { "summary": "Elenca le voci della lista", "description": "Restituisce le voci attuali di una lista, a partire dalla più recente. `search` individua corrispondenze con parte del `value` o del `display_label` di una voce senza distinzione tra maiuscole e minuscole, e `reference_session_id` restringe i risultati alle voci estratte da una singola sessione di verifica della persona. Gli URL delle immagini in `metadata` sono URL firmati di breve durata generati nuovamente a ogni chiamata; una chiave API con ambito limitato priva di `media: read` riceve `null` al loro posto. Una chiave API con ambito limitato richiede `workflows: read`.", "operationId": "list_list_entries", "x-didit-sdk": { "resource": "lists.entries", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID della lista, come restituito da List lists o Create a list.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "search", "in": "query", "required": false, "description": "Testo senza distinzione tra maiuscole e minuscole che il `value` o il `display_label` della voce deve contenere.", "schema": { "type": "string" } }, { "name": "reference_session_id", "in": "query", "required": false, "description": "Solo le voci ricavate da questa sessione di verifica della persona, ad esempio per verificare quali dei suoi volti sono già inclusi nell'elenco.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Dimensione della pagina. Il valore predefinito è 50. Un valore superiore a 1000000 restituisce `400`; zero, un valore negativo o non numerico utilizza 50 come valore predefinito.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 } }, { "name": "offset", "in": "query", "required": false, "description": "Indice in base zero del primo elemento da restituire. È preferibile seguire `next`. Un valore superiore a 1000000 restituisce `400`; un valore negativo o non numerico reimposta a 0.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/?search=example.com' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.lists.entries.list(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.lists.entries.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Lists.Entries.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.lists().entries().list(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "lists->entries->list('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.entries.list(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Lists.Entries.ListAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina di voci, dalla più recente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Numero totale di voci corrispondenti ai filtri." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceListEntry" } } } }, "examples": { "Entries": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "value": "X1234567", "display_label": "Jane Doe - X1234567", "comment": "", "added_by": "api", "reference_session_id": "33333333-4444-5555-6666-777777777777", "reference_session_number": 1042, "reference_session_type": "kyc", "reference_object_uuid": "66666666-7777-8888-9999-000000000000", "metadata": { "full_name": "Jane Doe", "issuing_state": "ESP", "document_type": "ID", "region": "", "document_number": "X1234567" }, "created_at": "2026-10-12T10:06:12.774915Z" }, { "uuid": "eeeeeeee-ffff-0000-1111-222222222222", "value": "y7654321", "display_label": "", "comment": "Reported by a partner", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": null, "metadata": null, "created_at": "2026-10-03T07:48:30.552810Z" } ] } } } } } }, "400": { "description": "Un parametro di query non è valido.", "content": { "application/json": { "examples": { "Invalid session id": { "value": { "reference_session_id": [ "Must be a valid UUID." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: read` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "404": { "description": "Nessuna lista con questo UUID esiste nell'applicazione della chiave API, oppure è stata eliminata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "List not found." } } } } } }, "429": { "description": "Il limite di lettura condiviso di 600 richieste al minuto per chiave API è stato superato. Rispetta `Retry-After` prima di riprovare.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea una voce nella lista", "description": "Aggiunge una voce a una lista in uno dei tre modi seguenti: tramite `value`; da una sessione di verifica con `reference_session_id`, dove Didit legge il valore dal record più recente della sessione per il tipo di voce della lista e vi collega la voce; oppure tramite `value` con un `reference_object_uuid` e `metadata.reference_type` che rimandano a una transazione, un utente o un'azienda. Nelle blocklist di sistema per volti, documenti, telefoni ed email, anche il record letto dalla sessione viene contrassegnato come inserito in blocklist, quindi le nuove sessioni corrispondenti vengono rifiutate; nelle blocklist di sistema per utenti e aziende, gli utenti o le aziende corrispondenti vengono impostati su `BLOCKED`. Le sessioni e le transazioni già completate non vengono modificate. Una chiave API con ambito limitato richiede `workflows: write`. Consulta [Crea una voce della lista](https://docs.didit.me/it/management-api/lists/create-entry) per ciascuna modalità.", "operationId": "create_list_entry", "x-didit-sdk": { "resource": "lists.entries", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID della lista a cui aggiungere l'elemento. Per un volto disponibile solo come immagine, usa invece Upload a face to a list.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Invia `value`, `reference_session_id` o entrambi. I campi applicabili dipendono dall'`entry_type` della lista.", "properties": { "value": { "type": "string", "description": "Il valore da inserire nell'elenco, validato rispetto all'`entry_type` della lista: `email` un indirizzo email valido; `phone` un numero internazionale valido, memorizzato in formato E.164; `ip_address` un indirizzo IP o un intervallo CIDR (ad esempio `10.0.0.0/8`); `device_fingerprint` almeno 8 caratteri tra lettere, cifre, `-`, `_`, `:` e `.` (una blocklist rifiuta un'impronta segnalata da diversi dispositivi distinti); `country` un codice ISO 3166-1 alpha-2 o alpha-3, memorizzato come alpha-3; `user` e `business` il `vendor_data`; qualsiasi altro tipo una stringa non vuota. Memorizzato in minuscolo tranne i numeri di telefono e i codici paese, e una lista contiene ciascun valore una sola volta (senza distinzione tra maiuscole e minuscole). Obbligatorio a meno che non venga inviato `reference_session_id`; deve essere lasciato vuoto con un `face_image_source` di acquisizione del documento." }, "reference_session_id": { "type": "string", "format": "uuid", "description": "Una sessione di verifica di una persona o di un'azienda della tua applicazione da cui acquisire il valore. Didit legge il record più recente della sessione corrispondente al tipo di voce della lista (`face`, `document`, `phone`, `email`, `ip_address` o `device_fingerprint`), collega la voce alla sessione e a quel record e compila `display_label` e `metadata` per i documenti. Per una blocklist di tipo `device_fingerprint`, una sessione che dispone solo di un'impronta di classe dispositivo, o che è stata completata su più dispositivi, viene rifiutata: invia l'impronta esatta come `value`. Per altri tipi di voce, o quando la sessione non contiene tale record, invia anche `value`; in tal caso, il tuo `value` viene memorizzato e la voce rimane comunque collegata alla sessione." }, "reference_object_uuid": { "type": "string", "format": "uuid", "description": "UUID del record rappresentato dalla voce quando non proviene da una sessione: un UUID di transazione oppure il `didit_internal_id` di un utente o di un'azienda. Abbinalo a `metadata.reference_type`. Sostituito dal record della sessione quando `reference_session_id` ne fornisce uno." }, "face_image_source": { "type": "string", "enum": [ "liveness", "front_image_camera_front", "back_image_camera_front" ], "default": "liveness", "description": "Elenchi di volti con `reference_session_id`: da quale delle immagini della sessione viene estratto il volto. `liveness` (impostazione predefinita) è il selfie di rilevamento della vitalità. `front_image_camera_front` e `back_image_camera_front` sono i selfie scattati dalla fotocamera anteriore mentre l'utente fotografava il fronte o il retro del proprio documento: accettati solo sulla blocklist di volti di sistema, con `reference_session_id` e un `value` vuoto. Ciascun selfie può essere aggiunto una sola volta e deve mostrare un unico volto ben visibile." }, "reference_node_id": { "type": "string", "nullable": true, "maxLength": 100, "description": "Con un `face_image_source` di acquisizione del documento: il nodo di verifica dell'identità di cui usare il selfie, per i workflow che ne contengono più di uno. Il valore predefinito è la verifica dell'identità più recente contenente tale immagine. Rifiutato con `liveness`." }, "display_label": { "type": "string", "maxLength": 512, "description": "Etichetta di facile lettura. Se vuota, Didit ne ricava una dalla sessione ove possibile (ad esempio il nome del titolare e il numero del documento)." }, "comment": { "type": "string", "description": "Nota in formato testo libero, ad esempio il motivo dell'inclusione nella lista." }, "metadata": { "type": "object", "additionalProperties": true, "description": "JSON a struttura libera memorizzato con la voce e restituito così come memorizzato. Usa `reference_type` e `reference_id` affinché la console rimandi alla fonte. `reference_image_url` e `front_image_url` sono impostati esclusivamente da Didit e vengono rimossi se li invii. Per una voce letta da una sessione, le chiavi di Didit vengono unite alle tue.", "properties": { "reference_type": { "type": "string", "enum": [ "transaction", "vendor_user", "vendor_business" ], "description": "A cosa punta `reference_object_uuid`." }, "reference_id": { "type": "string", "description": "Identificatore del record di origine." } } } } }, "examples": { "By value": { "value": { "value": "+14155552671", "comment": "Reported fraud" } }, "From a session": { "value": { "reference_session_id": "33333333-4444-5555-6666-777777777777" } }, "Face from a document-capture selfie": { "value": { "reference_session_id": "33333333-4444-5555-6666-777777777777", "face_image_source": "front_image_camera_front" } }, "From a transaction": { "value": { "value": "0x52908400098527886E0F7030069857D2E4169EE7", "reference_object_uuid": "55555555-6666-7777-8888-999999999999", "comment": "Linked to a chargeback", "metadata": { "reference_type": "transaction", "reference_id": "55555555-6666-7777-8888-999999999999" } } }, "Country": { "value": { "value": "PRK", "comment": "Sanctioned jurisdiction" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"value\": \"+14155552671\", \"comment\": \"Reported fraud\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.entries.create(\n \"11111111-2222-3333-4444-555555555555\",\n value=\"+14155552671\",\n comment=\"Reported fraud\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.entries.create(\"11111111-2222-3333-4444-555555555555\", {\n value: \"+14155552671\",\n comment: \"Reported fraud\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesCreateParams{\n\tValue: didit.String(\"+14155552671\"),\n\tComment: didit.String(\"Reported fraud\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsEntriesCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().entries().create(\"11111111-2222-3333-4444-555555555555\", ListsEntriesCreateParams.builder()\n .value(\"+14155552671\")\n .comment(\"Reported fraud\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->entries->create('11111111-2222-3333-4444-555555555555', [\n 'value' => '+14155552671',\n 'comment' => 'Reported fraud',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.entries.create(\n \"11111111-2222-3333-4444-555555555555\",\n value: \"+14155552671\",\n comment: \"Reported fraud\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.Entries.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new ListsEntriesCreateParams\n{\n Value = \"+14155552671\",\n Comment = \"Reported fraud\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "La voce è stata creata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceListEntry" }, "examples": { "By value": { "value": { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "value": "+14155552671", "display_label": "", "comment": "Reported fraud", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": null, "metadata": null, "created_at": "2026-10-12T10:04:51.220391Z" } }, "Document from a session": { "value": { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "value": "X1234567", "display_label": "Jane Doe - X1234567", "comment": "", "added_by": "api", "reference_session_id": "33333333-4444-5555-6666-777777777777", "reference_session_number": 1042, "reference_session_type": "kyc", "reference_object_uuid": "66666666-7777-8888-9999-000000000000", "metadata": { "full_name": "Jane Doe", "issuing_state": "ESP", "document_type": "ID", "region": "", "document_number": "X1234567" }, "created_at": "2026-10-12T10:06:12.774915Z" } }, "From a transaction": { "value": { "uuid": "dddddddd-eeee-ffff-0000-111111111111", "value": "0x52908400098527886e0f7030069857d2e4169ee7", "display_label": "", "comment": "Linked to a chargeback", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": "55555555-6666-7777-8888-999999999999", "metadata": { "reference_type": "transaction", "reference_id": "55555555-6666-7777-8888-999999999999" }, "created_at": "2026-10-12T10:20:40.117062Z" } } } } } }, "400": { "description": "Il corpo non è valido, il valore è già presente nella lista o la sessione non può fornire il valore.", "content": { "application/json": { "examples": { "Nothing to list": { "value": { "value": [ "Either 'value' or 'reference_session_id' must be provided." ] } }, "Duplicate value": { "value": { "value": [ "An entry with this value already exists in this list." ] } }, "Invalid phone": { "value": { "value": [ "Invalid phone number. Provide a valid international number (e.g. +1234567890)." ] } }, "Invalid IP": { "value": { "value": [ "Invalid IP address or CIDR range (e.g. 192.168.1.1 or 10.0.0.0/24)." ] } }, "Invalid country": { "value": { "value": [ "Invalid country code: XX. Provide a valid ISO 3166-1 alpha-2 or alpha-3 country code." ] } }, "Device-class fingerprint": { "value": { "value": [ "This value is a device-class fingerprint: several distinct devices have reported it, so blocklisting it would decline unrelated people. Block the user by document, face, email or phone instead." ] } }, "Unknown session": { "value": { "reference_session_id": [ "Session not found or does not belong to this application." ] } }, "No data in session": { "value": { "value": [ "Either provide a 'value' or ensure the session contains data for this entry type." ] } }, "Selfie on another list": { "value": { "face_image_source": [ "A document-capture selfie can only be added to the face blocklist." ] } }, "No clear face in selfie": { "value": { "face_image_source": [ "No clear face was found in this selfie, so it cannot be blocklisted." ] } }, "Selfie already listed": { "value": { "face_image_source": [ "This selfie is already in the blocklist." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: write` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Nessuna lista con questo UUID esiste nell'applicazione della chiave API, oppure è stata eliminata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "List not found." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" }, "503": { "description": "L'analisi facciale di un selfie acquisito durante l'acquisizione del documento è temporaneamente non disponibile. Non è stato aggiunto nulla; riprova più tardi.", "content": { "application/json": { "examples": { "Unavailable": { "value": { "detail": "Service temporarily unavailable. Please try again later." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/entries/{entry_uuid}/": { "delete": { "summary": "Elimina una voce della lista", "description": "Elimina una voce da una lista, incluse le liste di sistema. La voce non produce più corrispondenze immediatamente e l'eliminazione è irreversibile: per inserire nuovamente il valore nella lista, crea una nuova voce. In una blocklist di sistema per volti, documenti, telefoni o email, il record rappresentato dalla voce non è più contrassegnato come inserito in blocklist; nella blocklist di sistema per utenti o aziende, gli utenti o le aziende dell'applicazione il cui `vendor_data` corrisponde al valore della voce (o il cui `didit_internal_id` corrisponde al suo `reference_object_uuid`) e che sono `BLOCKED` tornano a `ACTIVE`. Le sessioni e le transazioni già completate mantengono il loro stato. Una chiave API con ambito limitato richiede `workflows: write`.", "operationId": "delete_list_entry", "x-didit-sdk": { "resource": "lists.entries", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID della lista che contiene la voce.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "entry_uuid", "in": "path", "required": true, "description": "UUID della voce, come restituito da List list entries o Create a list entry.", "schema": { "type": "string", "format": "uuid" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.lists.entries.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.lists.entries.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Lists.Entries.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.lists().entries().delete(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");" }, { "lang": "php", "label": "PHP", "source": "lists->entries->delete('11111111-2222-3333-4444-555555555555', 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.entries.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Lists.Entries.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");" } ], "responses": { "204": { "description": "La voce è stata eliminata. Nessun corpo." }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: write` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Nessuna voce con questo UUID esiste in questa lista, la lista non si trova nell'applicazione della chiave API o è stata eliminata, oppure la voce è già stata eliminata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No ListEntry matches the given query." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/entries/face-upload/": { "post": { "summary": "Carica un volto in un elenco", "description": "Aggiunge un volto a una blocklist o allowlist di volti da un'immagine JPEG o PNG con codifica base64, nei casi in cui non si disponga di una sessione di verifica a cui fare riferimento. Didit rileva i volti nell'immagine, utilizza quello più grande e crea una voce i cui `value` e `reference_object_uuid` corrispondono all'UUID del nuovo volto. Un volto presente nella blocklist fa rifiutare le nuove sessioni il cui volto corrisponde; un volto presente nell'allowlist salta l'azione per volto duplicato e non sovrascrive mai una corrispondenza nella blocklist. In un'applicazione sandbox l'immagine non viene analizzata e la voce non corrisponde a nulla. Una chiave API con ambito limitato richiede `workflows: write`. Per inserire in lista un volto da una sessione esistente, utilizza invece [Crea una voce dell'elenco](https://docs.didit.me/it/management-api/lists/create-entry) con `reference_session_id`.", "operationId": "upload_list_entry_face", "x-didit-sdk": { "resource": "lists.entries", "method": "upload_face", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "UUID di una lista con `entry_type: face` e `list_type: blocklist` o `allowlist`.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "format": "byte", "description": "JPEG o PNG codificato in Base64, di massimo 2 MB una volta decodificato, che mostra un volto chiaramente visibile. Invia la stringa base64 pura, senza il prefisso `data:image/...;base64,`." }, "comment": { "type": "string", "default": "", "description": "Nota opzionale a testo libero, ad esempio il motivo dell'inserimento in elenco." } } }, "examples": { "Face image": { "value": { "image": "/9j/4AAQSkZJRgABAQAAAQABAAD...", "comment": "Known fraud attempt" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/face-upload/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"image\\\": \\\"$(base64 < face.jpg | tr -d '\\n')\\\", \\\"comment\\\": \\\"Known fraud attempt\\\"}\"" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.entries.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image=\"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n comment=\"Known fraud attempt\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.entries.uploadFace(\"11111111-2222-3333-4444-555555555555\", {\n image: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n comment: \"Known fraud attempt\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n\tComment: didit.String(\"Known fraud attempt\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsEntriesUploadFaceParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().entries().uploadFace(\"11111111-2222-3333-4444-555555555555\", ListsEntriesUploadFaceParams.builder()\n .image(\"/9j/4AAQSkZJRgABAQAAAQABAAD...\")\n .comment(\"Known fraud attempt\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->entries->uploadFace('11111111-2222-3333-4444-555555555555', [\n 'image' => '/9j/4AAQSkZJRgABAQAAAQABAAD...',\n 'comment' => 'Known fraud attempt',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.entries.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n comment: \"Known fraud attempt\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.Entries.UploadFaceAsync(\"11111111-2222-3333-4444-555555555555\", new ListsEntriesUploadFaceParams\n{\n Image = \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n Comment = \"Known fraud attempt\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "La voce del volto è stata creata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceListEntry" }, "examples": { "Uploaded face": { "value": { "uuid": "cccccccc-dddd-eeee-ffff-000000000000", "value": "44444444-5555-6666-7777-888888888888", "display_label": "Manually uploaded face", "comment": "Known fraud attempt", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": "44444444-5555-6666-7777-888888888888", "metadata": { "reference_image_url": "https://media.example.com/faces/reference.jpg?expires=1760263938&signature=3f9a1c" }, "created_at": "2026-10-12T10:12:18.904467Z" } }, "Sandbox application": { "value": { "uuid": "cccccccc-dddd-eeee-ffff-000000000000", "value": "44444444-5555-6666-7777-888888888888", "display_label": "Sandbox face entry", "comment": "Known fraud attempt", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": "44444444-5555-6666-7777-888888888888", "metadata": { "sandbox": true }, "created_at": "2026-10-12T10:12:18.904467Z" } } } } } }, "400": { "description": "La lista non accetta caricamenti di volti, oppure l'immagine è mancante, non valida, troppo grande o non mostra un volto utilizzabile. Nessuna voce è stata creata.", "content": { "application/json": { "examples": { "Not a face list": { "value": { "detail": "Face upload is only available for face-type lists." } }, "Custom face list": { "value": { "detail": "Face upload is only available for face blocklists and allowlists." } }, "Missing image": { "value": { "image": [ "This field is required." ] } }, "Invalid base64": { "value": { "image": [ "Invalid base64 encoding." ] } }, "Too large": { "value": { "image": [ "Image exceeds maximum size of 2 MB." ] } }, "Unreadable image": { "value": { "image": "Invalid image. Provide a valid base64-encoded JPG or PNG." } }, "No face": { "value": { "image": "No face detected in the image. Please upload a clear photo with a visible face." } }, "No usable face": { "value": { "image": "Could not extract face embedding. Try a different image." } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: write` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "Nessuna lista con questo UUID esiste nell'applicazione della chiave API, oppure è stata eliminata.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "List not found." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" }, "503": { "description": "L'analisi facciale è temporaneamente non disponibile. Nessuna voce è stata creata; riprova più tardi.", "content": { "application/json": { "examples": { "Unavailable": { "value": { "detail": "Service temporarily unavailable. Please try again later." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/blocklist/": { "get": { "summary": "Elenca gli elementi nella blocklist", "description": "Restituisce un feed impaginato dei volti, documenti d'identità, numeri di telefono e indirizzi email delle sessioni di verifica dell'applicazione attualmente inseriti nella blocklist, a partire dal più recente in base a `blocklisted_at`; filtra con `item_type`. Gli elementi delle sessioni eliminate non sono inclusi. Il feed include i record inseriti nella blocklist a partire da una sessione (con [Aggiungi elementi della sessione alla blocklist](https://docs.didit.me/it/management-api/blocklist/add), dalla console o tramite una voce di lista creata da una sessione); i valori aggiunti manualmente a una lista, i volti caricati, i volti provenienti dal selfie dell'acquisizione del documento e gli altri tipi di voce vengono consultati con [Elenca le voci della lista](https://docs.didit.me/it/management-api/lists/list-entries). `face_image` e `front_image` sono URL firmati di breve durata, e una chiave API con ambito limitato priva di `media: read` riceve `null`. Una chiave API con ambito limitato richiede `workflows: read`.", "operationId": "list_blocklist_items", "x-didit-sdk": { "resource": "blocklist", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Blocklist" ], "parameters": [ { "name": "item_type", "in": "query", "required": false, "description": "Solo elementi di questo tipo. Se omesso, vengono restituiti tutti i tipi.", "schema": { "type": "string", "enum": [ "face", "document", "phone", "email" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Dimensione della pagina. Il valore predefinito è 50. Un valore superiore a 1000000 restituisce `400`; zero, un valore negativo o non numerico utilizza 50 come valore predefinito.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 } }, { "name": "offset", "in": "query", "required": false, "description": "Indice in base zero del primo elemento da restituire. È preferibile seguire `next`. Un valore superiore a 1000000 restituisce `400`; un valore negativo o non numerico reimposta a 0.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/blocklist/?item_type=document' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.blocklist.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.blocklist.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Blocklist.ListAutoPaging(ctx, didit.BlocklistListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.blocklist().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "blocklist->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.blocklist.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Blocklist.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina di elementi inseriti nella blocklist, dal più recente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Numero totale di elementi in blocklist corrispondenti ai filtri." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BlocklistedItem" } } } }, "examples": { "Mixed feed": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "type": "document", "session_id": "33333333-4444-5555-6666-777777777777", "session_number": 1042, "blocklisted_at": "2026-10-12T10:06:12.701553Z", "face_image": null, "document_type": "ID", "document_number": "X1234567", "front_image": "https://media.example.com/documents/front.jpg?expires=1760263938&signature=8b2e47", "phone_number": null, "country_code": null, "email": null }, { "type": "phone", "session_id": "77777777-8888-9999-0000-111111111111", "session_number": 1017, "blocklisted_at": "2026-10-08T15:31:09.400127Z", "face_image": null, "document_type": null, "document_number": null, "front_image": null, "phone_number": "+14155552671", "country_code": "US", "email": null } ] } } } } } }, "400": { "description": "Un parametro di query non è valido.", "content": { "application/json": { "examples": { "Unknown item type": { "value": { "item_type": [ "\"wallet\" is not a valid choice." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: read` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "429": { "description": "Il limite di lettura condiviso di 600 richieste al minuto per chiave API è stato superato. Rispetta `Retry-After` prima di riprovare.", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/blocklist/add/": { "post": { "summary": "Aggiungi gli elementi della sessione alla blocklist", "description": "Aggiunge alla blocklist il volto, il documento d'identità, il numero di telefono o l'indirizzo email di una sessione di verifica di una persona dell'applicazione. Per ogni tipo selezionato, Didit prende il record più recente della sessione, lo contrassegna come inserito nella blocklist e aggiunge una voce collegata alla sessione alla blocklist di sistema corrispondente (`added_by: \"api\"`), in modo che le nuove sessioni con volto, numero di documento, numero di telefono o indirizzo email corrispondenti vengano rifiutate. Ogni elemento selezionato viene prima verificato: se ne manca uno, nulla viene inserito nella blocklist; ripetendo la chiamata per un elemento già presente nella lista viene mantenuta la voce singola e aggiornato `blocklisted_at`. La sessione stessa e le sessioni già concluse non vengono modificate. Una chiave API con ambito limitato richiede `workflows: write`.", "operationId": "add_to_blocklist", "x-didit-sdk": { "resource": "blocklist", "method": "add", "auth": "api_key", "server": true }, "tags": [ "Blocklist" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "description": "Almeno un flag `blocklist_*` deve essere `true`.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Una sessione di verifica di una persona della tua applicazione. Le sessioni eliminate vengono rifiutate." }, "blocklist_face": { "type": "boolean", "default": false, "description": "Aggiungi alla blocklist il volto della sessione." }, "blocklist_document": { "type": "boolean", "default": false, "description": "Aggiungi alla blocklist il documento d'identità della sessione. Il documento necessita di stato di emissione, tipo di documento, numero di documento e nome completo." }, "blocklist_phone": { "type": "boolean", "default": false, "description": "Aggiungi alla blocklist il numero di telefono della sessione." }, "blocklist_email": { "type": "boolean", "default": false, "description": "Aggiungi alla blocklist l'indirizzo email della sessione." } } }, "examples": { "Face and document": { "value": { "session_id": "33333333-4444-5555-6666-777777777777", "blocklist_face": true, "blocklist_document": true } }, "Phone only": { "value": { "session_id": "33333333-4444-5555-6666-777777777777", "blocklist_phone": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/blocklist/add/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"session_id\": \"33333333-4444-5555-6666-777777777777\",\n \"blocklist_face\": true,\n \"blocklist_document\": true\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.blocklist.add(\n session_id=\"33333333-4444-5555-6666-777777777777\",\n blocklist_face=True,\n blocklist_document=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.blocklist.add({\n session_id: \"33333333-4444-5555-6666-777777777777\",\n blocklist_face: true,\n blocklist_document: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Blocklist.Add(ctx, didit.BlocklistAddParams{\n\tSessionID: \"33333333-4444-5555-6666-777777777777\",\n\tBlocklistFace: didit.Bool(true),\n\tBlocklistDocument: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BlocklistAddParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.blocklist().add(BlocklistAddParams.builder()\n .sessionId(\"33333333-4444-5555-6666-777777777777\")\n .blocklistFace(true)\n .blocklistDocument(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "blocklist->add([\n 'session_id' => '33333333-4444-5555-6666-777777777777',\n 'blocklist_face' => true,\n 'blocklist_document' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.blocklist.add(\n session_id: \"33333333-4444-5555-6666-777777777777\",\n blocklist_face: true,\n blocklist_document: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Blocklist.AddAsync(new BlocklistAddParams\n{\n SessionId = \"33333333-4444-5555-6666-777777777777\",\n BlocklistFace = true,\n BlocklistDocument = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Gli elementi selezionati sono stati inseriti nella blocklist.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Sempre `Successfully updated blocklist.`" } } }, "examples": { "Blocklisted": { "value": { "message": "Successfully updated blocklist." } } } } } }, "400": { "description": "Il corpo non è valido, la sessione non è una sessione di verifica di questa applicazione oppure non contiene record del tipo selezionato. Nessun elemento è stato inserito nella blocklist.", "content": { "application/json": { "examples": { "Unknown session": { "value": { "non_field_errors": [ "Session not found" ] } }, "No item selected": { "value": { "non_field_errors": [ "Must specify at least one item to blocklist" ] } }, "No face record": { "value": { "non_field_errors": [ "Session does not have a face record" ] } }, "Incomplete document": { "value": { "non_field_errors": [ "To blocklist a document, the document must have an issuing state, document type, document number and full name" ] } }, "Invalid session id": { "value": { "session_id": [ "Must be a valid UUID." ] } }, "Missing session id": { "value": { "session_id": [ "This field is required." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: write` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/blocklist/remove/": { "post": { "summary": "Rimuovi elementi della sessione dalla blocklist", "description": "Rimuove il blocco su volto, documento d'identità, numero di telefono o indirizzo email di una sessione di verifica della persona dell'applicazione. Per ogni tipo selezionato, Didit recupera il record più recente della sessione, rimuove il contrassegno di inserimento in blocklist ed elimina le voci della blocklist di sistema create a partire da tale record, evitando così che nuove sessioni vengano rifiutate. Le voci aggiunte a una lista per valore non vengono modificate: cercale con [List list entries](https://docs.didit.me/it/management-api/lists/list-entries) ed eliminale con [Delete a list entry](https://docs.didit.me/it/management-api/lists/delete-entry). Lo sblocco di un record non presente in blocklist va a buon fine senza apportare modifiche, e le sessioni già terminate non subiscono variazioni. Una chiave API con ambito limitato richiede `workflows: write`.", "operationId": "remove_from_blocklist", "x-didit-sdk": { "resource": "blocklist", "method": "remove", "auth": "api_key", "server": true }, "tags": [ "Blocklist" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "description": "Almeno un flag `unblock_*` deve essere `true`.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Una sessione di verifica di una persona della tua applicazione. Le sessioni eliminate vengono rifiutate." }, "unblock_face": { "type": "boolean", "default": false, "description": "Rimuove il blocco sul volto della sessione." }, "unblock_document": { "type": "boolean", "default": false, "description": "Rimuove il blocco sul documento d'identità della sessione." }, "unblock_phone": { "type": "boolean", "default": false, "description": "Rimuove il blocco sul numero di telefono della sessione." }, "unblock_email": { "type": "boolean", "default": false, "description": "Rimuove il blocco sull'indirizzo email della sessione." } } }, "examples": { "Face and document": { "value": { "session_id": "33333333-4444-5555-6666-777777777777", "unblock_face": true, "unblock_document": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/blocklist/remove/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"session_id\": \"33333333-4444-5555-6666-777777777777\",\n \"unblock_face\": true,\n \"unblock_document\": true\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.blocklist.remove(\n session_id=\"33333333-4444-5555-6666-777777777777\",\n unblock_face=True,\n unblock_document=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.blocklist.remove({\n session_id: \"33333333-4444-5555-6666-777777777777\",\n unblock_face: true,\n unblock_document: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Blocklist.Remove(ctx, didit.BlocklistRemoveParams{\n\tSessionID: \"33333333-4444-5555-6666-777777777777\",\n\tUnblockFace: didit.Bool(true),\n\tUnblockDocument: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BlocklistRemoveParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.blocklist().remove(BlocklistRemoveParams.builder()\n .sessionId(\"33333333-4444-5555-6666-777777777777\")\n .unblockFace(true)\n .unblockDocument(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "blocklist->remove([\n 'session_id' => '33333333-4444-5555-6666-777777777777',\n 'unblock_face' => true,\n 'unblock_document' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.blocklist.remove(\n session_id: \"33333333-4444-5555-6666-777777777777\",\n unblock_face: true,\n unblock_document: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Blocklist.RemoveAsync(new BlocklistRemoveParams\n{\n SessionId = \"33333333-4444-5555-6666-777777777777\",\n UnblockFace = true,\n UnblockDocument = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il blocco sugli elementi selezionati è stato revocato.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Sempre `Successfully removed from blocklist.`" } } }, "examples": { "Unblocked": { "value": { "message": "Successfully removed from blocklist." } } } } } }, "400": { "description": "Il corpo non è valido, la sessione non è una sessione di verifica di questa applicazione oppure non contiene record del tipo selezionato. Non è stato modificato nulla.", "content": { "application/json": { "examples": { "Unknown session": { "value": { "non_field_errors": [ "Session not found" ] } }, "No item selected": { "value": { "non_field_errors": [ "Must specify at least one item to unblock" ] } }, "No email record": { "value": { "non_field_errors": [ "Session does not have an email record" ] } }, "Invalid session id": { "value": { "session_id": [ "Must be a valid UUID." ] } }, "Missing session id": { "value": { "session_id": [ "This field is required." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Altri errori di autenticazione restituiscono `403`.", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "L'intestazione `x-api-key` è mancante (una chiave errata, revocata o scaduta riceve `401`), oppure una chiave API con ambito limitato non dispone di `workflows: write` o viene utilizzata da un indirizzo IP non presente nella sua allowlist.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/": { "get": { "summary": "Recupera configurazione webhook", "description": "Restituisce le impostazioni webhook dell'applicazione in un'unica chiamata: ogni [destinazione webhook](https://docs.didit.me/it/management-api/webhook/list-destinations) con il rispettivo segreto di firma, i tipi di evento a cui una destinazione può iscriversi, l'URL webhook a livello di applicazione (legacy), la versione e il segreto, la politica di conservazione dei dati e dei modelli biometrici e gli host di ritorno del wallet Digital ID. Didit consegna i webhook alle destinazioni, ciascuno firmato con la propria `secret_shared_key`; i campi di primo livello `webhook_url`, `webhook_version` e `secret_shared_key` vengono utilizzati solo finché non è abilitata alcuna destinazione, e in tal caso unicamente per `status.updated` e `data.updated`. La risposta contiene segreti di firma, pertanto non includerla nei log né nel codice lato client. Una chiave API con ambito richiede `webhooks: read`.", "operationId": "get_webhook_config", "x-didit-sdk": { "resource": "webhooks", "method": "retrieve_config", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.retrieve_config()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.retrieveConfig();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.RetrieveConfig(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().retrieveConfig();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->retrieveConfig();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.retrieve_config\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.RetrieveConfigAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La configurazione del webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" }, "examples": { "One destination": { "value": { "webhook_url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy10aGUtYXBwLWxldmVsLXNlY3JldC0wMDA", "capture_method": "MOBILE", "data_retention_months": 24, "face_retention_policy": "delete_with_session", "face_retention_days": null, "biometric_consent_mode": "auto", "available_events": [ { "value": "status.updated", "label": "Session status updated" }, { "value": "data.updated", "label": "Session data updated" }, { "value": "user.status.updated", "label": "User status updated" }, { "value": "user.data.updated", "label": "User data updated" }, { "value": "business.status.updated", "label": "Business status updated" }, { "value": "business.data.updated", "label": "Business data updated" }, { "value": "activity.created", "label": "Activity created" }, { "value": "transaction.created", "label": "Transaction created" }, { "value": "transaction.status.updated", "label": "Transaction status updated" }, { "value": "travel_rule.status.updated", "label": "Travel Rule Status Updated" }, { "value": "workflow.compliance_changed", "label": "Workflow Compliance Changed" } ], "allowed_return_hosts": [ "shop.example.com" ], "endpoints": [ { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC0wMDAwMDA", "subscribed_events": [ "status.updated", "data.updated" ], "created_at": "2026-01-04T08:00:00.000000Z", "updated_at": "2026-04-22T14:09:11.523671Z" } ] } } } } } }, "401": { "description": "La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave `x-api-key` mancante, non valida o revocata restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite di frequenza superato: più di 600 richieste GET nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Richieste consentite nell'intervallo di un minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Ora Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome del budget superato.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "Aggiorna la configurazione del webhook", "description": "Aggiorna parzialmente le impostazioni a livello di applicazione: l'URL, la versione e il segreto del webhook legacy, i criteri di conservazione dei dati e dei modelli biometrici, e gli host di ritorno del wallet Digital ID. Invia solo i campi da modificare; la risposta contiene la configurazione completa, con la stessa struttura di `GET /v3/webhook/`. Le destinazioni non sono gestite qui: per crearle, aggiornarle ed eliminarle usa gli endpoint `/v3/webhook/destinations/`, e non inviare un campo `endpoints` a questo endpoint. Una modifica a `data_retention_months` si applica anche alle sessioni esistenti, e le sessioni che elimina non possono essere ripristinate; leggi prima [Conservazione dei dati](https://docs.didit.me/it/console/data-retention). Una chiave API con restrizioni di ambito richiede `webhooks: write`.", "operationId": "update_webhook_config", "x-didit-sdk": { "resource": "webhooks", "method": "update_config", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Invia solo i campi da modificare. Le destinazioni non vengono gestite qui.", "properties": { "webhook_url": { "type": "string", "format": "uri", "nullable": true, "maxLength": 2000, "description": "URL del webhook legacy a livello di applicazione. Didit lo usa solo quando l'applicazione non ha alcuna destinazione abilitata, e solo per `status.updated` e `data.updated`. Non crea una destinazione, e la successiva creazione, aggiornamento o eliminazione di una destinazione lo sostituisce. Per ricevere webhook, crea invece una destinazione con `POST /v3/webhook/destinations/`." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versione del payload del `webhook_url` legacy." }, "rotate_secret_key": { "type": "boolean", "default": false, "description": "`true` sostituisce immediatamente la `secret_shared_key` a livello di applicazione con un nuovo valore casuale; il nuovo valore è presente nella risposta. I segreti di destinazione non vengono modificati. Ogni chiamata con `true` genera un nuovo segreto, pertanto non è idempotente." }, "capture_method": { "type": "string", "enum": [ "MOBILE", "MOBILE_AND_DESKTOP" ], "description": "Impostazione legacy dell'applicazione. Il flusso di verifica non la legge." }, "data_retention_months": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 120, "description": "Intervallo di eliminazione automatica in mesi (un mese equivale a 30 giorni), oppure `null` per nessuna eliminazione automatica. Una modifica si applica anche alle sessioni esistenti: ogni sessione di verifica degli utenti più vecchia del nuovo intervallo viene eliminata automaticamente, e tale eliminazione è irreversibile." }, "face_retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "Cosa succede all'embedding facciale di una sessione quando la sessione viene eliminata. `retain_until_user_deleted` richiede `face_retention_days` nella stessa richiesta o già impostato. Una modifica si applica alle eliminazioni di sessioni da quel momento in poi; non crea né elimina alcun modello biometrico esistente." }, "face_retention_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 3650, "description": "Periodo di conservazione, in giorni, dei modelli biometrici secondo `retain_until_user_deleted`." }, "biometric_consent_mode": { "type": "string", "enum": [ "auto", "always", "never" ], "description": "Quando il flusso ospitato e gli SDK nativi richiedono alla persona il consenso biometrico esplicito prima dell'acquisizione del volto. `auto` (predefinito) lo richiede solo quando si applica un trigger: uno stato dichiarato, l'IP della persona o l'emittente del documento d'identità si trova in Illinois, Texas o Colorado, oppure la persona sembra trovarsi negli Stati Uniti senza uno stato noto. `always` lo richiede a ogni persona il cui workflow acquisisce un volto. `never` non mostra mai il passaggio, e raccogli tu stesso il consenso prima del selfie. Ogni modifica viene registrata nel registro di audit. Consulta [Consenso biometrico](https://docs.didit.me/it/getting-started/biometric-consent)." }, "allowed_return_hosts": { "type": "array", "maxItems": 20, "description": "Sostituisce l'intero elenco di host di ritorno del wallet Digital ID. Solo hostname semplici, come ad esempio `shop.example.com`: nessuno schema, porta, percorso o carattere jolly. I valori vengono convertiti in minuscolo e i duplicati vengono rimossi. Invia `[]` per cancellare l'elenco.", "items": { "type": "string", "maxLength": 253 } }, "allowed_domains": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 }, "description": "Sostituisce l'intero elenco delle origini consentite. Origini (ad esempio `https://app.example.com`; `http` solo per `localhost`) in cui il flusso di verifica ospitato può essere incorporato e a cui può reindirizzare l'utente con una callback di sessione. Le chiamate server-to-server non sono interessate. Un elenco vuoto indica nessuna restrizione. Didit memorizza ciascuna origine in lettere minuscole senza una porta predefinita. Una voce non valida genera un errore `400` su `allowed_domains`. Invia `[]` per rimuovere la restrizione.", "example": [ "https://app.example.com" ] } } }, "examples": { "Enable biometric template retention": { "value": { "face_retention_policy": "retain_until_user_deleted", "face_retention_days": 365, "biometric_consent_mode": "auto" } }, "Rotate the legacy secret": { "value": { "rotate_secret_key": true } }, "Set data retention": { "value": { "data_retention_months": 24 } }, "Register return hosts": { "value": { "allowed_return_hosts": [ "shop.example.com", "app.example.com" ] } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/webhook/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"face_retention_policy\": \"retain_until_user_deleted\", \"face_retention_days\": 365}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.update_config(\n face_retention_policy=\"retain_until_user_deleted\",\n face_retention_days=365,\n biometric_consent_mode=\"auto\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.updateConfig({\n face_retention_policy: \"retain_until_user_deleted\",\n face_retention_days: 365,\n biometric_consent_mode: \"auto\",\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WebhooksUpdateConfigParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().updateConfig(WebhooksUpdateConfigParams.builder()\n .faceRetentionPolicy(WebhooksUpdateConfigParams.FaceRetentionPolicy.of(\"retain_until_user_deleted\"))\n .faceRetentionDays(365L)\n .biometricConsentMode(WebhooksUpdateConfigParams.BiometricConsentMode.of(\"auto\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->updateConfig([\n 'face_retention_policy' => 'retain_until_user_deleted',\n 'face_retention_days' => 365,\n 'biometric_consent_mode' => 'auto',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.update_config(\n face_retention_policy: \"retain_until_user_deleted\",\n face_retention_days: 365,\n biometric_consent_mode: \"auto\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.UpdateConfigAsync(new WebhooksUpdateConfigParams\n{\n FaceRetentionPolicy = new WebhooksUpdateConfigParamsFaceRetentionPolicy(\"retain_until_user_deleted\"),\n FaceRetentionDays = 365,\n BiometricConsentMode = new WebhooksUpdateConfigParamsBiometricConsentMode(\"auto\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La configurazione completa dopo l'aggiornamento, con la stessa struttura di `GET /v3/webhook/`. Se hai ruotato il segreto, memorizza la nuova `secret_shared_key` prima di eliminare la risposta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" }, "examples": { "Retention enabled": { "value": { "webhook_url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy10aGUtYXBwLWxldmVsLXNlY3JldC0wMDA", "capture_method": "MOBILE", "data_retention_months": 24, "face_retention_policy": "retain_until_user_deleted", "face_retention_days": 365, "biometric_consent_mode": "auto", "available_events": [ { "value": "status.updated", "label": "Session status updated" }, { "value": "data.updated", "label": "Session data updated" }, { "value": "user.status.updated", "label": "User status updated" }, { "value": "user.data.updated", "label": "User data updated" }, { "value": "business.status.updated", "label": "Business status updated" }, { "value": "business.data.updated", "label": "Business data updated" }, { "value": "activity.created", "label": "Activity created" }, { "value": "transaction.created", "label": "Transaction created" }, { "value": "transaction.status.updated", "label": "Transaction status updated" }, { "value": "travel_rule.status.updated", "label": "Travel Rule Status Updated" }, { "value": "workflow.compliance_changed", "label": "Workflow Compliance Changed" } ], "allowed_return_hosts": [ "shop.example.com" ], "endpoints": [ { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC0wMDAwMDA", "subscribed_events": [ "status.updated", "data.updated" ], "created_at": "2026-01-04T08:00:00.000000Z", "updated_at": "2026-04-22T14:09:11.523671Z" } ] } } } } } }, "400": { "description": "Validazione non riuscita: ogni campo non valido è mappato su un elenco di messaggi e nulla viene modificato. Un body che non è JSON valido restituisce `{\"detail\": \"JSON parse error - ...\"}`.", "content": { "application/json": { "schema": { "type": "object", "description": "Ciascun campo non valido associato a un elenco di messaggi.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Retention days missing": { "value": { "face_retention_days": [ "A finite retention duration is required when face retention is enabled." ], "biometric_consent_mode": "auto" } }, "Retention window out of range": { "value": { "data_retention_months": [ "Ensure this value is less than or equal to 120." ] } }, "Invalid return host": { "value": { "allowed_return_hosts": [ "'https://shop.example.com' is not a hostname. Register the bare host (e.g. shop.example.com): no scheme, port, path or wildcard." ] } }, "Invalid choice": { "value": { "face_retention_policy": [ "\"forever\" is not a valid choice." ] } } } } } }, "401": { "description": "La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave `x-api-key` mancante, non valida o revocata restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks write": { "value": { "detail": "This API key has no write access to webhooks." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite di frequenza superato: più di 300 richieste di scrittura (POST, PATCH, PUT, DELETE) nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Richieste consentite nell'intervallo di un minuto (300).", "schema": { "type": "integer", "example": 300 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Ora Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome del budget superato.", "schema": { "type": "string", "example": "generic-write" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/analytics/": { "get": { "summary": "Recupera analisi della destinazione webhook", "description": "Totali di consegna, tasso di fallimento e tempi di risposta per una destinazione webhook, sull'intero intervallo (`summary`) e per giorno UTC (`points`). Ogni tentativo conta come una consegna: il primo invio di un evento, ogni [nuovo tentativo](https://docs.didit.me/it/integration/webhooks#politica-di-nuovo-tentativo) automatico e ogni reinvio. Una consegna è fallita quando lo stato HTTP registrato è 400 o superiore, quindi i timeout (registrati come `504`) e gli errori di connessione (`503`) contano come falliti; una consegna ancora in coda conta solo in `total_deliveries`. I record di consegna sono disponibili per circa 30 giorni. Una chiave API con ambito richiede `webhooks: read`.", "operationId": "get_webhook_destination_analytics", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "retrieve_analytics", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID della destinazione (lo `uuid` restituito da `GET /v3/webhook/destinations/`).", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "date_from", "in": "query", "required": false, "description": "Primo giorno UTC da includere, in formato `YYYY-MM-DD` (incluso). Omettere per iniziare dalla consegna disponibile più datata. Viene accettato `dateFrom` come alias.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "date_to", "in": "query", "required": false, "description": "Ultimo giorno UTC da includere, nel formato `YYYY-MM-DD` (incluso). Non deve essere precedente a `date_from`. `dateTo` è accettato come alias.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-16" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/analytics/?date_from=2026-10-01&date_to=2026-10-16' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.retrieve_analytics(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.retrieveAnalytics(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.RetrieveAnalytics(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsRetrieveAnalyticsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().retrieveAnalytics(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->retrieveAnalytics('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.retrieve_analytics(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.RetrieveAnalyticsAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Statistiche di consegna per la destinazione.", "content": { "application/json": { "schema": { "type": "object", "required": [ "summary", "points" ], "properties": { "summary": { "type": "object", "description": "Totali per l'intervallo richiesto.", "required": [ "total_deliveries", "failed_deliveries", "min_response_time_ms", "avg_response_time_ms", "max_response_time_ms", "error_rate_percentage" ], "properties": { "total_deliveries": { "type": "integer", "minimum": 0, "description": "Tentativi di consegna, inclusi quelli in coda." }, "failed_deliveries": { "type": "integer", "minimum": 0, "description": "Tentativi il cui stato HTTP registrato è 400 o superiore." }, "min_response_time_ms": { "type": "integer", "nullable": true, "description": "Tentativo più rapido in millisecondi, oppure `null` se nessun tentativo ha un tempo registrato." }, "avg_response_time_ms": { "type": "integer", "nullable": true, "description": "Tempo medio dei tentativi in millisecondi, arrotondato, o `null` se nessun tentativo ha un tempo registrato." }, "max_response_time_ms": { "type": "integer", "nullable": true, "description": "Tentativo più lento in millisecondi, o `null` quando nessun tentativo ha un tempo registrato." }, "error_rate_percentage": { "type": "integer", "minimum": 0, "maximum": 100, "description": "`failed_deliveries` / `total_deliveries` x 100, arrotondato a un numero intero. `0` quando non ci sono consegne." } } }, "points": { "type": "array", "description": "Una voce per ogni giorno UTC in cui ci sono state consegne, a partire dal più vecchio. I giorni senza consegne sono omessi, quindi riempi gli intervalli con zeri quando li rappresenti in un grafico.", "items": { "type": "object", "required": [ "date", "total_deliveries", "failed_deliveries", "min_response_time_ms", "avg_response_time_ms", "max_response_time_ms" ], "properties": { "date": { "type": "string", "format": "date", "description": "Giorno UTC, `YYYY-MM-DD`." }, "total_deliveries": { "type": "integer", "minimum": 0, "description": "Tentativi di consegna, inclusi quelli in coda." }, "failed_deliveries": { "type": "integer", "minimum": 0, "description": "Tentativi il cui stato HTTP registrato è 400 o superiore." }, "min_response_time_ms": { "type": "integer", "nullable": true, "description": "Tentativo più rapido in millisecondi, oppure `null` se nessun tentativo ha un tempo registrato." }, "avg_response_time_ms": { "type": "integer", "nullable": true, "description": "Tempo medio dei tentativi in millisecondi, arrotondato, o `null` se nessun tentativo ha un tempo registrato." }, "max_response_time_ms": { "type": "integer", "nullable": true, "description": "Tentativo più lento in millisecondi, o `null` quando nessun tentativo ha un tempo registrato." } } } } } }, "examples": { "Three days of deliveries": { "value": { "summary": { "total_deliveries": 1250, "failed_deliveries": 12, "min_response_time_ms": 38, "avg_response_time_ms": 164, "max_response_time_ms": 5004, "error_rate_percentage": 1 }, "points": [ { "date": "2026-10-14", "total_deliveries": 410, "failed_deliveries": 0, "min_response_time_ms": 38, "avg_response_time_ms": 152, "max_response_time_ms": 911 }, { "date": "2026-10-15", "total_deliveries": 395, "failed_deliveries": 12, "min_response_time_ms": 41, "avg_response_time_ms": 190, "max_response_time_ms": 5004 }, { "date": "2026-10-16", "total_deliveries": 445, "failed_deliveries": 0, "min_response_time_ms": 40, "avg_response_time_ms": 151, "max_response_time_ms": 1220 } ] } }, "No deliveries in range": { "value": { "summary": { "total_deliveries": 0, "failed_deliveries": 0, "min_response_time_ms": null, "avg_response_time_ms": null, "max_response_time_ms": null, "error_rate_percentage": 0 }, "points": [] } } } } } }, "400": { "description": "`date_from` o `date_to` non è una data in formato `YYYY-MM-DD`, oppure `date_to` è precedente a `date_from`.", "content": { "application/json": { "schema": { "type": "object", "description": "Ciascun campo non valido associato a un elenco di messaggi.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Malformed date": { "value": { "date_from": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Reversed range": { "value": { "date_to": [ "date_to must be greater than or equal to date_from." ] } } } } } }, "401": { "description": "La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave `x-api-key` mancante, non valida o revocata restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Nessuna destinazione con questo UUID esiste per l'applicazione, oppure è stata eliminata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite di frequenza superato: più di 600 richieste GET nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Richieste consentite nell'intervallo di un minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Ora Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome del budget superato.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/deliveries/": { "get": { "summary": "Elenca le consegne della destinazione webhook", "description": "Sfoglia ogni tentativo di consegna verso una destinazione webhook, a partire dal più recente. Il primo invio di ciascun evento, ogni [nuovo tentativo](https://docs.didit.me/it/integration/webhooks#politica-di-nuovo-tentativo) automatico e ogni reinvio costituiscono voci distinte. Le voci includono lo stato HTTP e il tempo di risposta ma non il payload: recupera una singola consegna per leggerne le intestazioni e il corpo. `count` è esatto fino a 100 e riporta 100 al di sopra di tale valore, quindi segui `next` finché non diventa `null`. I record di consegna sono disponibili per circa 30 giorni. Una chiave API con ambito limitato richiede `webhooks: read` e `decisions: read`; una chiave limitata ad alcuni workflow o a sessioni approvate non può utilizzare questo endpoint.", "operationId": "list_webhook_destination_deliveries", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "list_deliveries", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID della destinazione (lo `uuid` restituito da `GET /v3/webhook/destinations/`).", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "limit", "in": "query", "required": false, "description": "Numero massimo di consegne per pagina. Il valore predefinito è 50. Un valore che non è un numero intero positivo viene reimpostato su 50; un valore superiore a 1000000 restituisce `400`.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "Numero di consegne da saltare. Il valore predefinito è 0. È preferibile seguire gli URL `next` e `previous` della risposta.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 0 }, { "name": "date_from", "in": "query", "required": false, "description": "Primo giorno UTC da includere, in formato `YYYY-MM-DD` (incluso). Omettere per iniziare dalla consegna disponibile più datata. Viene accettato `dateFrom` come alias.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "date_to", "in": "query", "required": false, "description": "Ultimo giorno UTC da includere, nel formato `YYYY-MM-DD` (incluso). Non deve essere precedente a `date_from`. `dateTo` è accettato come alias.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-16" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/deliveries/?limit=50&date_from=2026-10-01' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.webhooks.destinations.list_deliveries(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.webhooks.destinations.listDeliveries(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Webhooks.Destinations.ListDeliveriesAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsListDeliveriesParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.webhooks().destinations().listDeliveries(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->listDeliveries('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.webhooks.destinations.list_deliveries(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Webhooks.Destinations.ListDeliveriesAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina di consegne, dalla più recente alla meno recente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "Consegne corrispondenti, esatte fino a 100 e limitate a 100 al di sopra di tale soglia. Usa `next` per sapere se esistono altre pagine." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDestinationDelivery" } } } }, "examples": { "Failed delivery, its retry and a queued event": { "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "66666666-7777-8888-9999-000000000003", "session_id": null, "request_url": "https://yourapp.com/webhooks/didit", "response_status": null, "response_time_ms": null, "status": "APPROVED", "webhook_type": "transaction.created", "created_at": "2026-10-15T09:23:02.871190Z" }, { "uuid": "66666666-7777-8888-9999-000000000002", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "response_time_ms": 143, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-15T09:22:19.104233Z" }, { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "response_time_ms": 412, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-15T09:21:18.412345Z" } ] } } } } } }, "400": { "description": "`date_from` o `date_to` non è una data in formato `YYYY-MM-DD`, `date_to` è precedente a `date_from`, oppure `limit` o `offset` è superiore a 1000000 (questo errore è un array JSON di messaggi).", "content": { "application/json": { "examples": { "Malformed date": { "value": { "date_from": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Reversed range": { "value": { "date_to": [ "date_to must be greater than or equal to date_from." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave `x-api-key` mancante, non valida o revocata restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.` Una chiave limitata ad alcuni workflow o a sessioni approvate restituisce `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Nessuna destinazione con questo UUID esiste per l'applicazione, oppure è stata eliminata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "Limite di frequenza superato: più di 600 richieste GET nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Richieste consentite nell'intervallo di un minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Ora Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome del budget superato.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/deliveries/{delivery_uuid}/": { "get": { "summary": "Recupera consegna della destinazione webhook", "description": "Recupera un tentativo di consegna a una destinazione webhook con le intestazioni di richiesta esatte e il corpo JSON inviati da Didit, lo stato HTTP restituito dal tuo endpoint e il tempo di risposta. `request_header` e `request_body` sono testo JSON: analizzali per leggere le intestazioni di firma e il payload, ad esempio per verificare la tua [verifica della firma](https://docs.didit.me/it/integration/webhooks#verifica-della-firma) rispetto a `secret_shared_key` della destinazione. Una consegna non contiene mai il segreto di firma e Didit non registra il corpo della risposta del tuo endpoint. Una chiave API con scope richiede `webhooks: read` e `decisions: read`; una chiave limitata ad alcuni workflow o a sessioni approvate non può utilizzare questo endpoint.", "operationId": "get_webhook_destination_delivery", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "retrieve_delivery", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID della destinazione a cui è stata inviata la consegna.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "delivery_uuid", "in": "path", "required": true, "description": "UUID della consegna: lo `uuid` di una voce restituita da `GET /v3/webhook/destinations/{destination_uuid}/deliveries/`.", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/deliveries/66666666-7777-8888-9999-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.retrieve_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.retrieveDelivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.RetrieveDelivery(ctx, \"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().retrieveDelivery(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->retrieveDelivery('11111111-2222-3333-4444-555555555555', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.retrieve_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.RetrieveDeliveryAsync(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La consegna, con le intestazioni e il corpo della richiesta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationDeliveryDetail" }, "examples": { "Connection failure": { "value": { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "response_time_ms": 412, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-15T09:21:18.412345Z", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"a5e02a03404e1337a0198e6be15d34abbd053c658a0e51e5d0e78554213ef29b\", \"X-Signature-V2\": \"927e7cb770c94ce745939bff73f04aa200015f3bc64795ba46c2aaf78a6cedc5\", \"X-Signature-Simple\": \"e37b0d4c716c72bb5ae7127b9cc455d28ab4686e9e22312b4ec2327409a73302\", \"X-Timestamp\": \"1792056078\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056078,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}" } } } } } }, "401": { "description": "La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave `x-api-key` mancante, non valida o revocata restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.` Una chiave limitata ad alcuni workflow o a sessioni approvate restituisce `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La destinazione non esiste per l'applicazione o è stata eliminata, oppure la consegna non esiste, appartiene a un'altra destinazione o non è più disponibile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } }, "Delivery not found": { "value": { "detail": "Webhook delivery not found." } } } } } }, "429": { "description": "Limite di frequenza superato: più di 600 richieste GET nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Richieste consentite nell'intervallo di un minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Ora Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome del budget superato.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/deliveries/{delivery_uuid}/resend/": { "post": { "summary": "Reinvia la consegna alla destinazione webhook", "description": "Invia nuovamente una consegna precedente, ad esempio dopo che il tuo endpoint non era disponibile. Didit prende il payload memorizzato, imposta un nuovo `timestamp`, lo firma nuovamente con il `secret_shared_key` corrente della destinazione (`X-Signature`, `X-Signature-V2`, `X-Signature-Simple` e `X-Timestamp`) e lo invia tramite POST all'URL `request_url` della consegna, anche se l'URL della destinazione è cambiato nel frattempo o la destinazione è disabilitata. L'identificativo `event_id` e il resto del payload restano invariati, pertanto esegui la deduplicazione su `event_id`. La chiamata attende fino a 5 secondi il tuo endpoint e restituisce la nuova consegna con codice `200` indipendentemente da cosa abbia risposto il tuo endpoint: controlla `response_status`. Un nuovo invio non viene ritentato automaticamente, ogni chiamata esegue un nuovo invio e crea una nuova consegna, e la richiesta non ha corpo. Una chiave API con restrizioni d'ambito necessita di `webhooks: write` e `decisions: read`; una chiave limitata ad alcuni workflow o a sessioni approvate non può utilizzare questo endpoint.", "operationId": "resend_webhook_destination_delivery", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "resend_delivery", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "UUID della destinazione a cui è stata inviata la consegna.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "delivery_uuid", "in": "path", "required": true, "description": "UUID della consegna da reinviare: lo `uuid` di una voce restituita da `GET /v3/webhook/destinations/{destination_uuid}/deliveries/`.", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/deliveries/66666666-7777-8888-9999-000000000001/resend/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.resend_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.resendDelivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.ResendDelivery(ctx, \"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().resendDelivery(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->resendDelivery('11111111-2222-3333-4444-555555555555', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.resend_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.ResendDeliveryAsync(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La nuova consegna, già tentata. `response_status` è la risposta del tuo endpoint in questo tentativo (`504` timeout, `503` errore di connessione). La consegna originale rimane invariata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationDeliveryDetail" }, "examples": { "Accepted on resend": { "value": { "uuid": "66666666-7777-8888-9999-000000000004", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "response_time_ms": 151, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-16T14:05:42.330981Z", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"b8eb1e376517ee0cad8ba98ff7f8fd35fc72eca231000963a96a335f82328835\", \"X-Signature-V2\": \"9efd2ce9ed1303e1d05273ef9608a59363ed9789a05253db4748b3e8e50cb109\", \"X-Signature-Simple\": \"bf3a9dc04b2c20ab539203b0cd5cca2a10f630bf62d8feb6d68d82af80f64774\", \"X-Timestamp\": \"1792159542\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792159542,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}" } } } } } }, "400": { "description": "Impossibile firmare nuovamente la consegna salvata. Non viene inviato nulla.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." }, "code": { "type": "string", "description": "Codice di errore stabile leggibile da macchina. Basa la logica su questo, non su `detail`." } } }, "examples": { "Unsignable delivery": { "value": { "detail": "Invalid webhook data format", "code": "invalid_webhook_payload" } } } } } }, "401": { "description": "La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave `x-api-key` mancante, non valida o revocata restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.` Una chiave limitata ad alcuni workflow o a sessioni approvate restituisce `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks write": { "value": { "detail": "This API key has no write access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La destinazione non esiste per l'applicazione o è stata eliminata, oppure la consegna non esiste, appartiene a un'altra destinazione o non è più disponibile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } }, "Delivery not found": { "value": { "detail": "Webhook delivery not found." } } } } } }, "429": { "description": "Limite di frequenza superato: più di 300 richieste di scrittura (POST, PATCH, PUT, DELETE) nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Richieste consentite nell'intervallo di un minuto (300).", "schema": { "type": "integer", "example": 300 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Ora Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome del budget superato.", "schema": { "type": "string", "example": "generic-write" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/": { "get": { "summary": "Elenca gli eventi di monitoraggio", "description": "Elenca gli eventi di monitoraggio memorizzati per la tua applicazione, dal più recente `occurred_at`, con filtri opzionali combinati con AND. I filtri a più valori (`event_category`, `action_type`, `status`, `retention_class`) ripetono il parametro e corrispondono a uno qualsiasi dei valori; gli altri filtri prevedono corrispondenze esatte e i valori sconosciuti semplicemente non restituiscono eventi. Ciascun risultato è un riepilogo: chiama `GET /v3/events/{event_uuid}/` per il payload, il contesto del dispositivo, l'arricchimento IP e le evidenze della regola, e preferisci `GET /v3/events/subjects/{vendor_data}/` per la cronologia di un singolo soggetto. Le letture funzionano indipendentemente dal fatto che l'ingestione degli eventi sia abilitata o meno. Una chiave API con ambito limitato richiede `transactions: read`. Vedi [Ingestione eventi](https://docs.didit.me/it/transaction-monitoring/events).", "operationId": "list_monitoring_events", "x-didit-sdk": { "resource": "monitoring_events", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Numero massimo di eventi per pagina. Il valore predefinito è 50. I valori superiori a 1000000 restituiscono `400`; un valore non numerico, pari a zero o negativo viene reimpostato su 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "Numero di eventi da saltare. Il valore predefinito è 0. È preferibile seguire l'URL `next` della risposta.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 0 }, { "name": "event_category", "in": "query", "required": false, "description": "Solo gli eventi in queste categorie. Ripeti il parametro per più valori (`?event_category=payment&event_category=dispute`); viene restituito un evento corrispondente a uno qualsiasi di essi.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] } }, "example": [ "payment", "dispute" ] }, { "name": "action_type", "in": "query", "required": false, "description": "Solo gli eventi con questi tipi di azione (esatti, con distinzione tra maiuscole e minuscole). Ripeti per più valori.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "deposit_completed", "chargeback_opened" ] }, { "name": "status", "in": "query", "required": false, "description": "Solo gli eventi con questi stati. Ripeti per più valori.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ] } }, "example": [ "IN_REVIEW", "DECLINED" ] }, { "name": "retention_class", "in": "query", "required": false, "description": "Solo gli eventi in queste classi di conservazione. Ripeti per più valori.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ] } }, "example": [ "risk_relevant" ] }, { "name": "subject_vendor_data", "in": "query", "required": false, "description": "Corrispondenza esatta sul `vendor_data` del soggetto. Lo stesso ID può identificare sia una persona fisica che un'azienda; aggiungi `subject_entity_type` per sceglierne uno, oppure usa `GET /v3/events/subjects/{vendor_data}/`.", "schema": { "type": "string" }, "example": "user-42" }, { "name": "subject_entity_type", "in": "query", "required": false, "description": "`company` restituisce solo gli eventi dei soggetti aziendali; qualsiasi altro valore non vuoto (ad esempio `individual`) restituisce solo gli eventi delle persone fisiche. Omettilo per restituire entrambi.", "schema": { "type": "string", "enum": [ "individual", "company" ] }, "example": "individual" }, { "name": "business_vendor_data", "in": "query", "required": false, "description": "Corrispondenza esatta sul `business.vendor_data` inviato con l'evento.", "schema": { "type": "string" }, "example": "merchant-7" }, { "name": "session_id", "in": "query", "required": false, "description": "Corrispondenza esatta su `session.session_id`.", "schema": { "type": "string" }, "example": "web-session-abc" }, { "name": "device_fingerprint", "in": "query", "required": false, "description": "Corrispondenza esatta su `device_context.fingerprint`.", "schema": { "type": "string" }, "example": "fp-a8c1" }, { "name": "ip_address", "in": "query", "required": false, "description": "Corrispondenza esatta sull'indirizzo IP dell'evento.", "schema": { "type": "string" }, "example": "203.0.113.42" }, { "name": "game_id", "in": "query", "required": false, "description": "Corrispondenza esatta su `game_id` promosso.", "schema": { "type": "string" }, "example": "poker-holdem-01" }, { "name": "round_id", "in": "query", "required": false, "description": "Corrispondenza esatta su `round_id` promosso.", "schema": { "type": "string" }, "example": "round-88231" }, { "name": "affiliate_code", "in": "query", "required": false, "description": "Corrispondenza esatta su `affiliate_code` promosso.", "schema": { "type": "string" }, "example": "aff-summer" }, { "name": "payment_reference_id", "in": "query", "required": false, "description": "Corrispondenza esatta sul riferimento di pagamento (da `transaction_context.payment_reference_id` o `payload.payment_reference_id`).", "schema": { "type": "string" }, "example": "dep_735" }, { "name": "counterparty_vendor_data", "in": "query", "required": false, "description": "Corrispondenza esatta su `counterparty_vendor_data` promosso.", "schema": { "type": "string" }, "example": "user-77" }, { "name": "matched_only", "in": "query", "required": false, "description": "`true` (anche `1` o `yes`, senza distinzione tra maiuscole e minuscole) restituisce solo gli eventi a cui corrisponde almeno una regola (`rules_matched_count` maggiore di 0). Qualsiasi altro valore viene ignorato.", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "occurred_from", "in": "query", "required": false, "description": "Solo gli eventi con `occurred_at` pari o successivo a questo istante (incluso). Invia un valore ISO 8601: `2026-10-01T00:00:00Z`, un offset esplicito con il `+` codificato in percentuale (`2026-10-01T02:00:00%2B02:00`; un `+` non codificato viene decodificato come spazio e il valore non risulta più analizzabile), oppure solo una data (`2026-10-01`), che indica le 00:00:00 UTC di quel giorno. Un valore privo di offset viene interpretato come UTC. I valori in qualsiasi altro formato non sono accettati.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "occurred_to", "in": "query", "required": false, "description": "Solo gli eventi con `occurred_at` pari o antecedente a questo istante (incluso). Una data da sola indica l'inizio di quel giorno, quindi `occurred_to=2026-10-15` esclude il resto del 15 ottobre; invia `2026-10-15T23:59:59Z` per includerlo. Invia un valore ISO 8601: `2026-10-01T00:00:00Z`, un offset esplicito con il `+` codificato in percentuale (`2026-10-01T02:00:00%2B02:00`; un `+` non codificato viene decodificato come spazio e il valore non risulta più analizzabile), oppure solo una data (`2026-10-01`), che indica le 00:00:00 UTC di quel giorno. Un valore privo di offset viene interpretato come UTC. I valori in qualsiasi altro formato non sono accettati.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-17T23:59:59Z" }, { "name": "search", "in": "query", "required": false, "description": "Corrispondenza di sottostringhe senza distinzione tra maiuscole e minuscole su `event_id`, `action_type`, `subject_vendor_data` o `counterparty_vendor_data`.", "schema": { "type": "string" }, "example": "chargeback" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true&occurred_from=2026-10-01T00:00:00Z&limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.monitoring_events.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.monitoringEvents.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.MonitoringEvents.ListAutoPaging(ctx, didit.MonitoringEventsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.monitoringEvents().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.monitoring_events.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.MonitoringEvents.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina di riepiloghi degli eventi.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventPage" }, "examples": { "Payment and dispute events": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "event_uuid": "11111111-2222-3333-4444-555555555555", "event_id": "chargeback-2026-10-16-000318", "event_category": "dispute", "action_type": "chargeback_opened", "occurred_at": "2026-10-16T14:02:11Z", "received_at": "2026-10-16T14:02:12.418230Z", "status": "IN_REVIEW", "score": 60, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": null, "device_fingerprint": null, "ip_address": null, "ip_country": null, "amount": "250.000000000000000000", "currency": "EUR", "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": "dep_735", "retention_class": "monetary_or_compliance", "rules_matched_count": 1, "correlation_pending": false, "is_droppable": false }, { "event_uuid": "22222222-3333-4444-5555-666666666666", "event_id": "login-2026-10-15-000912", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-15T08:30:00.120000Z", "received_at": "2026-10-15T08:30:00.734512Z", "status": "ACCEPTED", "score": 0, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": "web-session-abc", "device_fingerprint": "fp-a8c1", "ip_address": "203.0.113.42", "ip_country": "ES", "amount": null, "currency": null, "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": null, "retention_class": "standard", "rules_matched_count": 0, "correlation_pending": false, "is_droppable": true } ] } } } } } }, "400": { "description": "`limit` o `offset` è maggiore di 1000000. Il corpo è un array JSON con un messaggio. Un `limit` non numerico o non positivo utilizza il valore predefinito di 50 invece di fallire.", "content": { "application/json": { "examples": { "limit too large": { "summary": "limit superiore a 1000000", "value": [ "limit must not exceed 1000000." ] }, "offset too large": { "summary": "offset superiore a 1000000", "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Solo una chiave scaduta riceve `401`; una chiave mancante o non valida riceve `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Intestazione `x-api-key` mancante (una chiave errata, revocata o scaduta restituisce `401`), una chiave con ambito priva di `transactions: read`, una chiave limitata ad alcuni workflow o a sessioni approvate (tale chiave non accede mai ai dati di monitoraggio delle transazioni), oppure una richiesta proveniente dall'esterno dell'allowlist IP della chiave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite di frequenza superato: le richieste `GET` condividono un budget di 600 richieste al minuto per chiave API. Attendi `Retry-After` secondi, quindi riprova.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea evento di monitoraggio", "description": "Invia un evento non monetario (login, session, gameplay, bonus, affiliate, payment, dispute, security, responsible gambling o custom) dal tuo backend. L'evento viene convalidato rispetto al contratto della sua categoria, memorizzato, arricchito con dati IP una volta per indirizzo pubblico univoco e valutato dalle tue regole sugli eventi in tempo reale prima della restituzione della risposta; le regole tra soggetti diversi e su finestre temporali ampie vengono eseguite in modo asincrono (`correlation_pending: true`), mentre in un'applicazione sandbox non viene eseguita alcuna regola. `event_id` è la chiave di idempotenza: lo stesso `event_id` con gli stessi `event_category`, `action_type`, `occurred_at`, `subject.vendor_data` e `payload` restituisce `200` con `idempotent_replay: true` e l'esito memorizzato (gli altri campi dell'involucro non vengono confrontati), mentre valori diversi restituiscono `409`. L'ingestione degli eventi è facoltativa (opt-in) per applicazione: finché non viene attivata, questo endpoint restituisce `403` con `code: event_monitoring_disabled` e non memorizza nulla. Una chiave API con ambito limitato richiede `transactions: write`. Consulta [Ingestione degli eventi](https://docs.didit.me/it/transaction-monitoring/events) e [Regole sugli eventi](https://docs.didit.me/it/transaction-monitoring/event-rules); per inviare eventi da un browser o da un'app, usa [Invio di eventi tramite SDK](https://docs.didit.me/it/transaction-monitoring/sdk-event-submission).", "operationId": "create_monitoring_event", "x-didit-sdk": { "resource": "monitoring_events", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventCreateRequest" }, "examples": { "Login": { "value": { "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481Z", "time_zone": "Europe/Madrid", "subject": { "vendor_data": "user-42", "entity_type": "individual" }, "session": { "session_id": "web-session-abc", "sequence": 142 }, "device_context": { "fingerprint": "fp-a8c1", "network_context": { "ip_address": "203.0.113.42" } }, "payload": { "method": "password" }, "custom_values": { "vip_tier": "gold" } } }, "Deposit completed": { "value": { "event_id": "deposit-2026-10-17-000002", "event_category": "payment", "action_type": "deposit_completed", "occurred_at": "2026-10-17T09:16:40Z", "subject": { "vendor_data": "user-42" }, "transaction_context": { "amount": "100.00", "currency": "EUR", "direction": "inbound", "payment_reference_id": "dep_736" }, "payload": { "payment_method": "card", "status": "completed" } } }, "Chargeback opened": { "value": { "event_id": "chargeback-2026-10-16-000318", "event_category": "dispute", "action_type": "chargeback_opened", "occurred_at": "2026-10-16T14:02:11Z", "subject": { "vendor_data": "user-42" }, "payload": { "payment_reference_id": "dep_735", "chargeback_id": "cb_5521", "amount": "250.00", "currency": "EUR", "reason_code": "fraud" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/events/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"event_id\": \"login-2026-10-17-000001\",\n \"event_category\": \"auth\",\n \"action_type\": \"login\",\n \"occurred_at\": \"2026-10-17T09:15:02.481Z\",\n \"subject\": {\"vendor_data\": \"user-42\", \"entity_type\": \"individual\"},\n \"session\": {\"session_id\": \"web-session-abc\", \"sequence\": 142},\n \"device_context\": {\n \"fingerprint\": \"fp-a8c1\",\n \"network_context\": {\"ip_address\": \"203.0.113.42\"}\n },\n \"payload\": {\"method\": \"password\"}\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.create(\n event_id=\"login-2026-10-17-000001\",\n event_category=\"auth\",\n action_type=\"login\",\n occurred_at=\"2026-10-17T09:15:02.481Z\",\n time_zone=\"Europe/Madrid\",\n subject={\n \"vendor_data\": \"user-42\",\n \"entity_type\": \"individual\",\n },\n session={\n \"session_id\": \"web-session-abc\",\n \"sequence\": 142,\n },\n device_context={\n \"fingerprint\": \"fp-a8c1\",\n \"network_context\": {\n \"ip_address\": \"203.0.113.42\",\n },\n },\n payload={\"method\": \"password\"},\n custom_values={\"vip_tier\": \"gold\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.create({\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n time_zone: \"Europe/Madrid\",\n subject: {\n vendor_data: \"user-42\",\n entity_type: \"individual\",\n },\n session: {\n session_id: \"web-session-abc\",\n sequence: 142,\n },\n device_context: {\n fingerprint: \"fp-a8c1\",\n network_context: {\n ip_address: \"203.0.113.42\",\n },\n },\n payload: { method: \"password\" },\n custom_values: { vip_tier: \"gold\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Create(ctx, didit.MonitoringEventCreateRequest{\n\tEventID: \"login-2026-10-17-000001\",\n\tEventCategory: \"auth\",\n\tActionType: \"login\",\n\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\tTimeZone: didit.String(\"Europe/Madrid\"),\n\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\tVendorData: \"user-42\",\n\t\tEntityType: didit.String(\"individual\"),\n\t},\n\tSession: didit.Some(didit.MonitoringEventCreateRequestSession{\n\t\tSessionID: didit.String(\"web-session-abc\"),\n\t\tSequence: didit.Int(142),\n\t}),\n\tDeviceContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContext{\n\t\tFingerprint: didit.String(\"fp-a8c1\"),\n\t\tNetworkContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContextNetworkContext{\n\t\t\tIPAddress: didit.String(\"203.0.113.42\"),\n\t\t}),\n\t}),\n\tPayload: didit.Some(map[string]any{\"method\": \"password\"}),\n\tCustomValues: didit.Some(map[string]any{\"vip_tier\": \"gold\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.MonitoringEventCreateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().create(MonitoringEventCreateRequest.builder()\n .eventId(\"login-2026-10-17-000001\")\n .eventCategory(MonitoringEventCreateRequest.EventCategory.of(\"auth\"))\n .actionType(\"login\")\n .occurredAt(OffsetDateTime.parse(\"2026-10-17T09:15:02.481Z\"))\n .timeZone(\"Europe/Madrid\")\n .subject(MonitoringEventCreateRequest.Subject.builder()\n .vendorData(\"user-42\")\n .entityType(\"individual\")\n .build())\n .session(MonitoringEventCreateRequest.Session.builder()\n .sessionId(\"web-session-abc\")\n .sequence(142L)\n .build())\n .deviceContext(MonitoringEventCreateRequest.DeviceContext.builder()\n .fingerprint(\"fp-a8c1\")\n .networkContext(MonitoringEventCreateRequest.DeviceContext.NetworkContext.builder()\n .ipAddress(\"203.0.113.42\")\n .build())\n .build())\n .payload(Map.of(\"method\", \"password\"))\n .customValues(Map.of(\"vip_tier\", MonitoringEventCreateRequest.CustomValuesValue.ofString(\"gold\")))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->create([\n 'event_id' => 'login-2026-10-17-000001',\n 'event_category' => 'auth',\n 'action_type' => 'login',\n 'occurred_at' => '2026-10-17T09:15:02.481Z',\n 'time_zone' => 'Europe/Madrid',\n 'subject' => [\n 'vendor_data' => 'user-42',\n 'entity_type' => 'individual',\n ],\n 'session' => [\n 'session_id' => 'web-session-abc',\n 'sequence' => 142,\n ],\n 'device_context' => [\n 'fingerprint' => 'fp-a8c1',\n 'network_context' => [\n 'ip_address' => '203.0.113.42',\n ],\n ],\n 'payload' => ['method' => 'password'],\n 'custom_values' => ['vip_tier' => 'gold'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.create(\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n time_zone: \"Europe/Madrid\",\n subject: {\n vendor_data: \"user-42\",\n entity_type: \"individual\",\n },\n session: {\n session_id: \"web-session-abc\",\n sequence: 142,\n },\n device_context: {\n fingerprint: \"fp-a8c1\",\n network_context: {\n ip_address: \"203.0.113.42\",\n },\n },\n payload: { method: \"password\" },\n custom_values: { vip_tier: \"gold\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.CreateAsync(new MonitoringEventCreateRequest\n{\n EventId = \"login-2026-10-17-000001\",\n EventCategory = \"auth\",\n ActionType = \"login\",\n OccurredAt = DateTimeOffset.Parse(\"2026-10-17T09:15:02.481Z\"),\n TimeZone = \"Europe/Madrid\",\n Subject = new()\n {\n VendorData = \"user-42\",\n EntityType = \"individual\",\n },\n Session = new MonitoringEventCreateRequestSession\n {\n SessionId = \"web-session-abc\",\n Sequence = 142,\n },\n DeviceContext = new MonitoringEventCreateRequestDeviceContext\n {\n Fingerprint = \"fp-a8c1\",\n NetworkContext = new MonitoringEventCreateRequestDeviceContextNetworkContext\n {\n IpAddress = \"203.0.113.42\",\n },\n },\n Payload = new Dictionary { [\"method\"] = \"password\" },\n CustomValues = new Dictionary { [\"vip_tier\"] = \"gold\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "L'evento è stato memorizzato e valutato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventIngestResult" }, "examples": { "Stored, no rule matched": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [] } }, "Rule matched, async rule pending": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "IN_REVIEW", "score": 40, "rules_evaluated_count": 6, "rules_matched_count": 1, "correlation_pending": true, "retention_class": "risk_relevant", "expires_at": "2027-01-15T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [ { "rule_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "library_key": null, "mode": "ACTIVE", "is_async": false } ] } } } } } }, "200": { "description": "Riproduzione idempotente: un evento con questo `event_id` e lo stesso contenuto è già memorizzato. Non è stato memorizzato o valutato nuovamente nulla; il corpo descrive l'evento memorizzato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventIngestResult" }, "examples": { "Replay": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": true, "rule_matches": [] } } } } } }, "400": { "description": "Validazione non riuscita. Il body è indicizzato per campo; i campi nidificati sono oggetti nidificati. Non viene memorizzato nulla.", "content": { "application/json": { "examples": { "Missing fields": { "value": { "event_id": [ "This field is required." ], "subject": [ "This field is required." ] } }, "Unknown category": { "value": { "event_category": [ "\"login\" is not a valid choice." ] } }, "occurred_at too old": { "value": { "occurred_at": [ "occurred_at is more than 7 days in the past. Use the batch import lane for backfills." ] } }, "occurred_at in the future": { "value": { "occurred_at": [ "occurred_at is more than 5 minutes in the future." ] } }, "Missing subject vendor_data": { "value": { "subject": { "vendor_data": [ "This field is required." ] } } }, "Missing required payload keys": { "value": { "payload": [ "payment.deposit_completed requires: payment_method, status." ] } }, "Missing one-of payload key": { "value": { "payload": [ "dispute.chargeback_opened requires one of: dispute_id, chargeback_id." ] } }, "Security change without changed_field": { "value": { "payload": [ "security.*_changed requires 'changed_field'." ] } }, "Payload too large": { "value": { "payload": [ "payload exceeds 16384 bytes. Summarise telemetry client-side." ] } }, "Too many custom_values": { "value": { "custom_values": [ "custom_values accepts at most 100 keys." ] } }, "Nested custom value": { "value": { "custom_values": [ "custom_values['limits'] must be a scalar - rule conditions cannot address nested values." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Solo una chiave scaduta riceve `401`; una chiave mancante o non valida riceve `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Intestazione `x-api-key` mancante (una chiave errata, revocata o scaduta restituisce `401`), una chiave con ambito priva di `transactions: write`, una chiave limitata ad alcuni workflow o a sessioni approvate (tale chiave non accede mai ai dati di monitoraggio delle transazioni), oppure una richiesta proveniente dall'esterno dell'allowlist IP della chiave. Restituito anche con `code: event_monitoring_disabled` quando l'ingestione degli eventi è disattivata per l'applicazione; in tal caso nulla viene memorizzato e il controllo viene eseguito prima della validazione del corpo.", "content": { "application/json": { "examples": { "Event monitoring disabled": { "value": { "detail": "Event monitoring is not enabled for this application. Turn on event ingestion in the transaction monitoring settings before submitting events.", "code": "event_monitoring_disabled" } }, "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "409": { "description": "`event_id` è già stato utilizzato per un evento con contenuto diverso (categoria, tipo di azione, `occurred_at`, `vendor_data` del soggetto o payload). Invia l'evento con un nuovo `event_id`.", "content": { "application/json": { "examples": { "event_id reused": { "value": { "event_id": "event_id 'login-2026-10-17-000001' already exists with a different payload." } } } } } }, "429": { "description": "Limite di frequenza superato: le creazioni di transazioni e l'ingestione di eventi (`POST /v3/transactions/`, `POST /v3/events/`, `POST /v3/events/batch/`) condividono un budget di 600 richieste al minuto per chiave API, separato dalle 300 condivise da tutte le altre richieste di scrittura. Attendi `Retry-After` secondi, quindi riprova.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di riprovare, arrotondati per eccesso in modo che il nuovo tentativo rientri nella finestra successiva.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Ingestion rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/batch/": { "post": { "summary": "Crea eventi di monitoraggio in batch", "description": "Invia da 1 a 500 eventi in un'unica richiesta, ciascuno nello stesso involucro di `POST /v3/events/`. Ogni elemento viene validato, memorizzato e valutato singolarmente e riceve il proprio esito (`accepted`, `replayed` o `rejected`), quindi un evento non valido non annulla mai gli altri: la risposta è `201` quando nessun elemento è stato rifiutato e `207` quando almeno uno lo è stato, ed entrambi indicano che la richiesta è stata elaborata. Invia `{\"events\": [...]}`; viene accettato anche un semplice array JSON di eventi. L'ingestione degli eventi deve essere abilitata per l'applicazione, altrimenti l'intera richiesta restituisce `403` con `code: event_monitoring_disabled` e non viene memorizzato nulla. Una chiave API con restrizioni di ambito richiede `transactions: write`. Consulta [Lotti](https://docs.didit.me/it/transaction-monitoring/events#batch).", "operationId": "create_monitoring_events_batch", "x-didit-sdk": { "resource": "monitoring_events", "method": "create_batch", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 500, "description": "Da 1 a 500 eventi. Ciascun elemento segue `MonitoringEventCreateRequest`, inclusa la finestra di 7 giorni nel passato e 5 minuti nel futuro su `occurred_at`.", "items": { "$ref": "#/components/schemas/MonitoringEventCreateRequest" } } } }, "example": { "events": [ { "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481Z", "subject": { "vendor_data": "user-42" } }, { "event_id": "deposit-2026-10-17-000002", "event_category": "payment", "action_type": "deposit_completed", "occurred_at": "2026-10-17T09:16:40Z", "subject": { "vendor_data": "user-42" }, "transaction_context": { "amount": "100.00", "currency": "EUR", "payment_reference_id": "dep_736" }, "payload": { "payment_method": "card", "status": "completed" } } ] } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/events/batch/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"events\": [\n {\"event_id\": \"login-2026-10-17-000001\", \"event_category\": \"auth\", \"action_type\": \"login\",\n \"occurred_at\": \"2026-10-17T09:15:02.481Z\", \"subject\": {\"vendor_data\": \"user-42\"}},\n {\"event_id\": \"deposit-2026-10-17-000002\", \"event_category\": \"payment\", \"action_type\": \"deposit_completed\",\n \"occurred_at\": \"2026-10-17T09:16:40.000Z\", \"subject\": {\"vendor_data\": \"user-42\"},\n \"transaction_context\": {\"amount\": \"100.00\", \"currency\": \"EUR\", \"payment_reference_id\": \"dep_736\"},\n \"payload\": {\"payment_method\": \"card\", \"status\": \"completed\"}}\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.create_batch(\n events=[{\n \"event_id\": \"login-2026-10-17-000001\",\n \"event_category\": \"auth\",\n \"action_type\": \"login\",\n \"occurred_at\": \"2026-10-17T09:15:02.481Z\",\n \"subject\": {\n \"vendor_data\": \"user-42\",\n },\n }, {\n \"event_id\": \"deposit-2026-10-17-000002\",\n \"event_category\": \"payment\",\n \"action_type\": \"deposit_completed\",\n \"occurred_at\": \"2026-10-17T09:16:40Z\",\n \"subject\": {\n \"vendor_data\": \"user-42\",\n },\n \"transaction_context\": {\n \"amount\": \"100.00\",\n \"currency\": \"EUR\",\n \"payment_reference_id\": \"dep_736\",\n },\n \"payload\": {\"payment_method\": \"card\", \"status\": \"completed\"},\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.createBatch({\n events: [{\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n }, {\n event_id: \"deposit-2026-10-17-000002\",\n event_category: \"payment\",\n action_type: \"deposit_completed\",\n occurred_at: \"2026-10-17T09:16:40Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n transaction_context: {\n amount: \"100.00\",\n currency: \"EUR\",\n payment_reference_id: \"dep_736\",\n },\n payload: { payment_method: \"card\", status: \"completed\" },\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.CreateBatch(ctx, didit.MonitoringEventsCreateBatchParams{\n\tEvents: []didit.MonitoringEventCreateRequest{{\n\t\tEventID: \"login-2026-10-17-000001\",\n\t\tEventCategory: \"auth\",\n\t\tActionType: \"login\",\n\t\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\t\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\t\tVendorData: \"user-42\",\n\t\t},\n\t}, {\n\t\tEventID: \"deposit-2026-10-17-000002\",\n\t\tEventCategory: \"payment\",\n\t\tActionType: \"deposit_completed\",\n\t\tOccurredAt: time.Date(2026, 10, 17, 9, 16, 40, 0, time.UTC),\n\t\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\t\tVendorData: \"user-42\",\n\t\t},\n\t\tTransactionContext: didit.Some(didit.MonitoringEventCreateRequestTransactionContext{\n\t\t\tAmount: didit.String(\"100.00\"),\n\t\t\tCurrency: didit.String(\"EUR\"),\n\t\t\tPaymentReferenceID: didit.String(\"dep_736\"),\n\t\t}),\n\t\tPayload: didit.Some(map[string]any{\"payment_method\": \"card\", \"status\": \"completed\"}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.MonitoringEventCreateRequest;\nimport me.didit.types.MonitoringEventsCreateBatchParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().createBatch(MonitoringEventsCreateBatchParams.builder()\n .events(List.of(\n MonitoringEventCreateRequest.builder()\n .eventId(\"login-2026-10-17-000001\")\n .eventCategory(MonitoringEventCreateRequest.EventCategory.of(\"auth\"))\n .actionType(\"login\")\n .occurredAt(OffsetDateTime.parse(\"2026-10-17T09:15:02.481Z\"))\n .subject(MonitoringEventCreateRequest.Subject.builder()\n .vendorData(\"user-42\")\n .build())\n .build(),\n MonitoringEventCreateRequest.builder()\n .eventId(\"deposit-2026-10-17-000002\")\n .eventCategory(MonitoringEventCreateRequest.EventCategory.of(\"payment\"))\n .actionType(\"deposit_completed\")\n .occurredAt(OffsetDateTime.parse(\"2026-10-17T09:16:40Z\"))\n .subject(MonitoringEventCreateRequest.Subject.builder()\n .vendorData(\"user-42\")\n .build())\n .transactionContext(MonitoringEventCreateRequest.TransactionContext.builder()\n .amount(\"100.00\")\n .currency(\"EUR\")\n .paymentReferenceId(\"dep_736\")\n .build())\n .payload(Map.of(\"payment_method\", \"card\", \"status\", \"completed\"))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->createBatch([\n 'events' => [[\n 'event_id' => 'login-2026-10-17-000001',\n 'event_category' => 'auth',\n 'action_type' => 'login',\n 'occurred_at' => '2026-10-17T09:15:02.481Z',\n 'subject' => [\n 'vendor_data' => 'user-42',\n ],\n ], [\n 'event_id' => 'deposit-2026-10-17-000002',\n 'event_category' => 'payment',\n 'action_type' => 'deposit_completed',\n 'occurred_at' => '2026-10-17T09:16:40Z',\n 'subject' => [\n 'vendor_data' => 'user-42',\n ],\n 'transaction_context' => [\n 'amount' => '100.00',\n 'currency' => 'EUR',\n 'payment_reference_id' => 'dep_736',\n ],\n 'payload' => ['payment_method' => 'card', 'status' => 'completed'],\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.create_batch(\n events: [{\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n }, {\n event_id: \"deposit-2026-10-17-000002\",\n event_category: \"payment\",\n action_type: \"deposit_completed\",\n occurred_at: \"2026-10-17T09:16:40Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n transaction_context: {\n amount: \"100.00\",\n currency: \"EUR\",\n payment_reference_id: \"dep_736\",\n },\n payload: { payment_method: \"card\", status: \"completed\" },\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.CreateBatchAsync(new MonitoringEventsCreateBatchParams\n{\n Events = new MonitoringEventCreateRequest[]\n {\n new()\n {\n EventId = \"login-2026-10-17-000001\",\n EventCategory = \"auth\",\n ActionType = \"login\",\n OccurredAt = DateTimeOffset.Parse(\"2026-10-17T09:15:02.481Z\"),\n Subject = new()\n {\n VendorData = \"user-42\",\n },\n },\n new()\n {\n EventId = \"deposit-2026-10-17-000002\",\n EventCategory = \"payment\",\n ActionType = \"deposit_completed\",\n OccurredAt = DateTimeOffset.Parse(\"2026-10-17T09:16:40Z\"),\n Subject = new()\n {\n VendorData = \"user-42\",\n },\n TransactionContext = new MonitoringEventCreateRequestTransactionContext\n {\n Amount = \"100.00\",\n Currency = \"EUR\",\n PaymentReferenceId = \"dep_736\",\n },\n Payload = new Dictionary { [\"payment_method\"] = \"card\", [\"status\"] = \"completed\" },\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Nessun elemento è stato rifiutato: ogni elemento è `accepted` o `replayed`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted_count", "replayed_count", "rejected_count", "results" ], "properties": { "accepted_count": { "type": "integer", "minimum": 0, "description": "Elementi memorizzati e valutati." }, "replayed_count": { "type": "integer", "minimum": 0, "description": "Elementi già memorizzati con lo stesso contenuto." }, "rejected_count": { "type": "integer", "minimum": 0, "description": "Elementi non memorizzati." }, "results": { "type": "array", "description": "Una voce per elemento, nell'ordine della richiesta.", "items": { "type": "object", "description": "Esito di un elemento. Gli elementi accettati e ripetuti includono anche ogni campo di `MonitoringEventIngestResult`; gli elementi rifiutati contengono invece `event_id` ed `errors`.", "required": [ "index", "outcome" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Posizione dell'elemento nel tuo array `events`." }, "outcome": { "type": "string", "enum": [ "accepted", "replayed", "rejected" ], "description": "`accepted`: memorizzato e valutato. `replayed`: già memorizzato con lo stesso contenuto. `rejected`: non memorizzato; vedi `errors`." }, "event_id": { "type": "string", "nullable": true, "description": "Il tuo `event_id`. Sugli elementi rifiutati dalla validazione viene letto dalla chiave snake_case `event_id` dell'elemento, quindi è null quando l'elemento lo ha omesso o ha inviato l'alias `eventId`." }, "errors": { "type": "object", "additionalProperties": true, "description": "Solo elementi rifiutati. Errori di validazione indicizzati per campo, nello stesso formato del `400` di `POST /v3/events/`; un `event_id` riutilizzato con contenuto diverso viene segnalato come stringa sotto `errors.event_id`." }, "event_uuid": { "type": "string", "format": "uuid", "description": "Solo elementi accettati e rieseguiti." }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "Solo elementi accettati e rieseguiti." }, "score": { "type": "integer", "description": "Solo elementi accettati e rieseguiti." }, "rules_evaluated_count": { "type": "integer", "description": "Solo elementi accettati e rieseguiti." }, "rules_matched_count": { "type": "integer", "description": "Solo elementi accettati e rieseguiti." }, "correlation_pending": { "type": "boolean", "description": "Solo elementi accettati e rieseguiti." }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "Solo elementi accettati e rieseguiti." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Solo elementi accettati e rieseguiti." }, "idempotent_replay": { "type": "boolean", "description": "Solo elementi accettati e rieseguiti." }, "rule_matches": { "type": "array", "description": "Solo elementi accettati e rieseguiti.", "items": { "type": "object", "required": [ "rule_id", "library_key", "mode", "is_async" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "description": "UUID della regola." }, "library_key": { "type": "string", "nullable": true, "description": "Chiave della libreria se la regola è stata installata dalla libreria di regole, altrimenti null." }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "Le regole `TEST` registrano la corrispondenza ma non applicano alcuna azione." }, "is_async": { "type": "boolean", "description": "`true` quando la corrispondenza proviene dal passaggio asincrono." } } } } } } } } }, "examples": { "All landed": { "value": { "accepted_count": 1, "replayed_count": 1, "rejected_count": 0, "results": [ { "index": 0, "outcome": "accepted", "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [] }, { "index": 1, "outcome": "replayed", "event_uuid": "11111111-2222-3333-4444-555555555555", "event_id": "deposit-2026-10-17-000002", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "monetary_or_compliance", "expires_at": null, "idempotent_replay": true, "rule_matches": [] } ] } } } } } }, "207": { "description": "Almeno un elemento è stato rifiutato. Gli altri elementi sono stati memorizzati; correggi e invia nuovamente solo quelli rifiutati (inviare nuovamente un elemento accettato è sicuro, restituisce `replayed`).", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted_count", "replayed_count", "rejected_count", "results" ], "properties": { "accepted_count": { "type": "integer", "minimum": 0, "description": "Elementi memorizzati e valutati." }, "replayed_count": { "type": "integer", "minimum": 0, "description": "Elementi già memorizzati con lo stesso contenuto." }, "rejected_count": { "type": "integer", "minimum": 0, "description": "Elementi non memorizzati." }, "results": { "type": "array", "description": "Una voce per elemento, nell'ordine della richiesta.", "items": { "type": "object", "description": "Esito di un elemento. Gli elementi accettati e ripetuti includono anche ogni campo di `MonitoringEventIngestResult`; gli elementi rifiutati contengono invece `event_id` ed `errors`.", "required": [ "index", "outcome" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Posizione dell'elemento nel tuo array `events`." }, "outcome": { "type": "string", "enum": [ "accepted", "replayed", "rejected" ], "description": "`accepted`: memorizzato e valutato. `replayed`: già memorizzato con lo stesso contenuto. `rejected`: non memorizzato; vedi `errors`." }, "event_id": { "type": "string", "nullable": true, "description": "Il tuo `event_id`. Sugli elementi rifiutati dalla validazione viene letto dalla chiave snake_case `event_id` dell'elemento, quindi è null quando l'elemento lo ha omesso o ha inviato l'alias `eventId`." }, "errors": { "type": "object", "additionalProperties": true, "description": "Solo elementi rifiutati. Errori di validazione indicizzati per campo, nello stesso formato del `400` di `POST /v3/events/`; un `event_id` riutilizzato con contenuto diverso viene segnalato come stringa sotto `errors.event_id`." }, "event_uuid": { "type": "string", "format": "uuid", "description": "Solo elementi accettati e rieseguiti." }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "Solo elementi accettati e rieseguiti." }, "score": { "type": "integer", "description": "Solo elementi accettati e rieseguiti." }, "rules_evaluated_count": { "type": "integer", "description": "Solo elementi accettati e rieseguiti." }, "rules_matched_count": { "type": "integer", "description": "Solo elementi accettati e rieseguiti." }, "correlation_pending": { "type": "boolean", "description": "Solo elementi accettati e rieseguiti." }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "Solo elementi accettati e rieseguiti." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Solo elementi accettati e rieseguiti." }, "idempotent_replay": { "type": "boolean", "description": "Solo elementi accettati e rieseguiti." }, "rule_matches": { "type": "array", "description": "Solo elementi accettati e rieseguiti.", "items": { "type": "object", "required": [ "rule_id", "library_key", "mode", "is_async" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "description": "UUID della regola." }, "library_key": { "type": "string", "nullable": true, "description": "Chiave della libreria se la regola è stata installata dalla libreria di regole, altrimenti null." }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "Le regole `TEST` registrano la corrispondenza ma non applicano alcuna azione." }, "is_async": { "type": "boolean", "description": "`true` quando la corrispondenza proviene dal passaggio asincrono." } } } } } } } } }, "examples": { "Partial success": { "value": { "accepted_count": 1, "replayed_count": 0, "rejected_count": 2, "results": [ { "index": 0, "outcome": "accepted", "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [] }, { "index": 1, "event_id": "deposit-2026-10-17-000002", "outcome": "rejected", "errors": { "payload": [ "payment.deposit_completed requires: payment_method, status." ] } }, { "index": 2, "event_id": "login-2026-10-16-000777", "outcome": "rejected", "errors": { "event_id": "event_id 'login-2026-10-16-000777' already exists with a different payload." } } ] } } } } } }, "400": { "description": "Il batch stesso non è valido: `events` è mancante o non è un array, è vuoto o contiene più di 500 elementi. Non viene memorizzato nulla; dividi i batch di grandi dimensioni.", "content": { "application/json": { "examples": { "Not a list": { "value": { "events": "Expected a list of events." } }, "Empty": { "value": { "events": "At least one event is required." } }, "Too many": { "value": { "events": "A batch accepts at most 500 events; received 612." } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Solo una chiave scaduta riceve `401`; una chiave mancante o non valida riceve `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Intestazione `x-api-key` mancante (una chiave errata, revocata o scaduta restituisce `401`), una chiave con ambito priva di `transactions: write`, una chiave limitata ad alcuni workflow o a sessioni approvate (tale chiave non accede mai ai dati di monitoraggio delle transazioni), oppure una richiesta proveniente dall'esterno dell'allowlist IP della chiave. Restituito anche con `code: event_monitoring_disabled` quando l'ingestione degli eventi è disattivata per l'applicazione; in tal caso nulla viene memorizzato e il controllo viene eseguito prima della validazione del corpo.", "content": { "application/json": { "examples": { "Event monitoring disabled": { "value": { "detail": "Event monitoring is not enabled for this application. Turn on event ingestion in the transaction monitoring settings before submitting events.", "code": "event_monitoring_disabled" } }, "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite di frequenza superato: le creazioni di transazioni e l'ingestione di eventi (`POST /v3/transactions/`, `POST /v3/events/`, `POST /v3/events/batch/`) condividono un budget di 600 richieste al minuto per chiave API, separato dalle 300 condivise da tutte le altre richieste di scrittura. Attendi `Retry-After` secondi, quindi riprova.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di riprovare, arrotondati per eccesso in modo che il nuovo tentativo rientri nella finestra successiva.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Ingestion rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/sdk-token/": { "post": { "summary": "Genera un token per l'SDK di monitoraggio", "description": "Genera una credenziale di dispositivo di breve durata associata a un singolo soggetto, consentendo alla tua applicazione web o mobile di inviare gli eventi di quell'utente direttamente a Didit senza una chiave API. L'applicazione invia il token `monitoring_token` restituito nell'intestazione `X-Monitoring-Token` al canale per dispositivi (`POST /v1/events/` e `POST /v1/events/batch/`), dove il soggetto viene sempre sovrascritto con questo `vendor_data`, gli eventi non inclusi in `allowed_event_categories` vengono rifiutati, ogni evento inviato consuma un utilizzo e qualsiasi richiesta il cui `Origin` non sia uguale a `bind_to_origin` viene rifiutata. Esegui la chiamata solo dal tuo backend; la generazione crea unicamente la credenziale (non viene creato alcun utente). L'ingestione degli eventi deve essere abilitata per l'applicazione, altrimenti questo endpoint restituisce `403` con `code: event_monitoring_disabled` invece di generare una credenziale che non potrebbe mai scrivere. Una chiave API con ambito limitato richiede `transactions: write`. Consulta [Invio di eventi tramite SDK](https://docs.didit.me/it/transaction-monitoring/sdk-event-submission).", "operationId": "create_monitoring_event_sdk_token", "x-didit-sdk": { "resource": "monitoring_events", "method": "create_sdk_token", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Sono accettati gli alias camelCase: `vendorData`, `entityType`, `allowedEventCategories`, `ttlSeconds`, `maxUses`, `bindToOrigin`.", "required": [ "vendor_data" ], "properties": { "vendor_data": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Il tuo ID per il soggetto a cui appartiene ogni evento inviato con questa credenziale." }, "entity_type": { "type": "string", "maxLength": 32, "default": "individual", "description": "`company` associa un soggetto aziendale; qualsiasi altro valore (predefinito `individual`) associa una persona fisica." }, "allowed_event_categories": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] }, "description": "Categorie che la credenziale può inviare. Omettilo o invia `[]` per consentire ogni categoria." }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 900, "description": "Durata della credenziale in secondi." }, "max_uses": { "type": "integer", "minimum": 1, "nullable": true, "default": 1000, "description": "Numero di eventi che la credenziale può inviare (un batch consuma un utilizzo per evento). Invia `null` per nessun limite massimo entro la durata di validità." }, "bind_to_origin": { "type": "string", "maxLength": 255, "nullable": true, "description": "Se impostato, l'intestazione del browser `Origin` di ogni richiesta del dispositivo deve corrispondere esattamente a questo valore; una richiesta senza `Origin` viene rifiutata." } } }, "example": { "vendor_data": "user-42", "allowed_event_categories": [ "auth", "session", "gameplay" ], "ttl_seconds": 900, "max_uses": 1000, "bind_to_origin": "https://app.example.com" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/events/sdk-token/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"vendor_data\": \"user-42\",\n \"allowed_event_categories\": [\"auth\", \"session\", \"gameplay\"],\n \"ttl_seconds\": 900,\n \"max_uses\": 1000,\n \"bind_to_origin\": \"https://app.example.com\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.create_sdk_token(\n vendor_data=\"user-42\",\n allowed_event_categories=[\"auth\", \"session\", \"gameplay\"],\n ttl_seconds=900,\n max_uses=1000,\n bind_to_origin=\"https://app.example.com\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.createSdkToken({\n vendor_data: \"user-42\",\n allowed_event_categories: [\"auth\", \"session\", \"gameplay\"],\n ttl_seconds: 900,\n max_uses: 1000,\n bind_to_origin: \"https://app.example.com\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.CreateSDKToken(ctx, didit.MonitoringEventsCreateSDKTokenParams{\n\tVendorData: \"user-42\",\n\tAllowedEventCategories: didit.Some([]didit.MonitoringEventsCreateSDKTokenParamsAllowedEventCategories{\"auth\", \"session\", \"gameplay\"}),\n\tTTLSeconds: didit.Int(900),\n\tMaxUses: didit.Int(1000),\n\tBindToOrigin: didit.String(\"https://app.example.com\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.MonitoringEventsCreateSdkTokenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().createSdkToken(MonitoringEventsCreateSdkTokenParams.builder()\n .vendorData(\"user-42\")\n .allowedEventCategories(List.of(MonitoringEventsCreateSdkTokenParams.AllowedEventCategories.of(\"auth\"), MonitoringEventsCreateSdkTokenParams.AllowedEventCategories.of(\"session\"), MonitoringEventsCreateSdkTokenParams.AllowedEventCategories.of(\"gameplay\")))\n .ttlSeconds(900L)\n .maxUses(1000L)\n .bindToOrigin(\"https://app.example.com\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->createSdkToken([\n 'vendor_data' => 'user-42',\n 'allowed_event_categories' => ['auth', 'session', 'gameplay'],\n 'ttl_seconds' => 900,\n 'max_uses' => 1000,\n 'bind_to_origin' => 'https://app.example.com',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.create_sdk_token(\n vendor_data: \"user-42\",\n allowed_event_categories: [\"auth\", \"session\", \"gameplay\"],\n ttl_seconds: 900,\n max_uses: 1000,\n bind_to_origin: \"https://app.example.com\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.CreateSdkTokenAsync(new MonitoringEventsCreateSdkTokenParams\n{\n VendorData = \"user-42\",\n AllowedEventCategories = new MonitoringEventsCreateSdkTokenParamsAllowedEventCategories[] { \"auth\", \"session\", \"gameplay\" },\n TtlSeconds = 900,\n MaxUses = 1000,\n BindToOrigin = \"https://app.example.com\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "La credenziale è stata generata. Fornisci `monitoring_token` all'app e consideralo segreto fino a `expires_at`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "monitoring_token", "expires_at", "allowed_event_categories", "max_uses", "bind_to_origin" ], "properties": { "monitoring_token": { "type": "string", "description": "La credenziale del dispositivo (un token URL-safe di 43 caratteri). Inviala nell'intestazione `X-Monitoring-Token`." }, "expires_at": { "type": "string", "format": "date-time", "description": "Data e ora in cui la credenziale smette di essere accettata." }, "allowed_event_categories": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] }, "description": "Categorie che la credenziale può inviare; `[]` indica ogni categoria." }, "max_uses": { "type": "integer", "nullable": true, "description": "Budget di eventi della credenziale; null indica nessun limite massimo." }, "bind_to_origin": { "type": "string", "nullable": true, "description": "Origine a cui è associata la credenziale, oppure null." } } }, "example": { "monitoring_token": "q7ZtR2xKp9VbN4mWc8LdH1sYfJ3gT6uEaQ0oPiXzBkC", "expires_at": "2026-10-17T09:30:02.481000Z", "allowed_event_categories": [ "auth", "session", "gameplay" ], "max_uses": 1000, "bind_to_origin": "https://app.example.com" } } } }, "400": { "description": "Validazione non riuscita: `vendor_data` mancante, `ttl_seconds` al di fuori dell'intervallo da 60 a 86400, `max_uses` inferiore a 1 o categoria sconosciuta (indicizzata in base alla sua posizione nell'array).", "content": { "application/json": { "examples": { "Missing vendor_data": { "value": { "vendor_data": [ "This field is required." ] } }, "ttl_seconds too short": { "value": { "ttl_seconds": [ "Ensure this value is greater than or equal to 60." ] } }, "Unknown category": { "value": { "allowed_event_categories": { "1": [ "\"login\" is not a valid choice." ] } } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Solo una chiave scaduta riceve `401`; una chiave mancante o non valida riceve `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Intestazione `x-api-key` mancante (una chiave errata, revocata o scaduta restituisce `401`), una chiave con ambito priva di `transactions: write`, una chiave limitata ad alcuni workflow o a sessioni approvate (tale chiave non accede mai ai dati di monitoraggio delle transazioni), oppure una richiesta proveniente dall'esterno dell'allowlist IP della chiave. Restituito anche con `code: event_monitoring_disabled` quando l'ingestione degli eventi è disattivata per l'applicazione; in tal caso nulla viene memorizzato e il controllo viene eseguito prima della validazione del corpo.", "content": { "application/json": { "examples": { "Event monitoring disabled": { "value": { "detail": "Event monitoring is not enabled for this application. Turn on event ingestion in the transaction monitoring settings before submitting events.", "code": "event_monitoring_disabled" } }, "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite di frequenza superato: le richieste di scrittura (`POST`, `PATCH`, `DELETE`) condividono un budget di 300 richieste al minuto per chiave API. Attendi `Retry-After` secondi, quindi riprova.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/{event_uuid}/": { "get": { "summary": "Recupera evento di monitoraggio", "description": "Recupera un evento di monitoraggio con tutto ciò che restituisce l'elenco, oltre a payload, valori personalizzati, contesto del dispositivo, provenienza dei campi (`field_sources`), campi di dominio promossi, `expires_at`, ogni esecuzione di regola corrispondente con le relative prove, l'arricchimento IP e i tag allegati dalle regole. Quando `correlation_pending` è `true`, una regola asincrona deve ancora essere eseguita; rileggi l'evento dopo qualche minuto per ottenere i valori definitivi di `status`, `score` e `rule_runs`. Le letture funzionano indipendentemente dal fatto che l'ingestione degli eventi sia abilitata o meno. Una chiave API con scope richiede `transactions: read`. Vedi [Evidenze](https://docs.didit.me/it/transaction-monitoring/event-rules#evidenze) e [Arricchimento IP](https://docs.didit.me/it/transaction-monitoring/ip-enrichment).", "operationId": "get_monitoring_event", "x-didit-sdk": { "resource": "monitoring_events", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "event_uuid", "in": "path", "required": true, "description": "Identificatore Didit dell'evento (`event_uuid` dalla risposta di creazione, batch, elenco o timeline), non il tuo `event_id`.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "L'evento con le relative prove.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventDetail" }, "examples": { "Login from a VPN, in review": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481000Z", "received_at": "2026-10-17T09:15:02.903114Z", "status": "IN_REVIEW", "score": 40, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": "web-session-abc", "device_fingerprint": "fp-a8c1", "ip_address": "203.0.113.42", "ip_country": "ES", "amount": null, "currency": null, "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": null, "retention_class": "risk_relevant", "rules_matched_count": 1, "correlation_pending": false, "is_droppable": true, "payload": { "method": "password" }, "custom_values": { "vip_tier": "gold", "vpn_or_proxy_detected": true }, "device_context": { "fingerprint": "fp-a8c1", "network_context": { "ip_address": "203.0.113.42", "ip_country": "Spain", "ip_country_code": "ES", "ip_city": "Madrid", "asn_number": 64500, "asn_organization": "Example Networks", "is_vpn_or_tor": true, "is_data_center": false } }, "field_sources": { "subject.vendor_data": "customer", "event_category": "customer", "action_type": "customer", "occurred_at": "customer", "received_at": "server", "payload.method": "customer", "session.session_id": "customer", "session.sequence": "customer", "device_context.fingerprint": "customer", "device_context.network_context.ip_address": "customer", "device_context.network_context.ip_country": "server", "device_context.network_context.ip_country_code": "server", "device_context.network_context.ip_city": "server", "device_context.network_context.asn_number": "server", "device_context.network_context.asn_organization": "server", "device_context.network_context.is_vpn_or_tor": "server", "device_context.network_context.is_data_center": "server" }, "session_sequence": 142, "table_id": null, "hand_id": null, "match_id": null, "market_id": null, "side": null, "role": null, "net_result_amount": null, "payment_fingerprint": null, "instrument_reference_hash": null, "withdrawal_address_hash": null, "dispute_id": null, "chargeback_id": null, "changed_field": null, "identity_match_ref": null, "schema_version": 1, "expires_at": "2027-01-15T09:15:02.481000Z", "rules_evaluated_count": 6, "rule_runs": [ { "rule_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "rule_title": "Login from VPN or Tor", "library_key": null, "matched": true, "mode": "ACTIVE", "is_async": false, "severity": "MEDIUM", "score_delta": 40, "action_summary": "score +40; add_tag:VPN_LOGIN", "matched_payload": [ { "field": "event.ip.is_vpn_or_tor", "operator": "eq", "expected_value": true, "current_value": true, "matched": true, "group_index": null, "group_logic": "AND", "field_source": "server" } ], "created_at": "2026-10-17T09:15:02.951207Z" } ], "ip_enrichment": { "ip_country_code": "ES", "ip_city": "Madrid", "asn_number": 64500, "asn_organization": "Example Networks", "is_vpn_or_tor": true, "is_data_center": false, "proxy_type": null, "last_enriched_at": "2026-10-17T09:15:02.910442Z" }, "subject_profile": null, "tags": [ "VPN_LOGIN" ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Solo una chiave scaduta riceve `401`; una chiave mancante o non valida riceve `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Intestazione `x-api-key` mancante (una chiave errata, revocata o scaduta restituisce `401`), una chiave con ambito priva di `transactions: read`, una chiave limitata ad alcuni workflow o a sessioni approvate (tale chiave non accede mai ai dati di monitoraggio delle transazioni), oppure una richiesta proveniente dall'esterno dell'allowlist IP della chiave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Nessun evento con questo `event_uuid` esiste nell'applicazione: non è mai stato memorizzato, è stato eliminato o appartiene a un'altra applicazione. Un segmento di percorso che non sia un UUID non corrisponde alla route e restituisce anch'esso `404`.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No MonitoringEvent matches the given query." } } } } } }, "429": { "description": "Limite di frequenza superato: le richieste `GET` condividono un budget di 600 richieste al minuto per chiave API. Attendi `Retry-After` secondi, quindi riprova.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/subjects/{vendor_data}/": { "get": { "summary": "Recupera cronologia degli eventi del soggetto", "description": "Elenca ogni evento di monitoraggio di un singolo soggetto, dal più recente in base a `occurred_at`. Un `vendor_data` è univoco solo all'interno dello stesso tipo di entità, per cui lo stesso id può indicare una persona fisica e un'azienda: `entity_type` seleziona la cronologia da visualizzare e il valore predefinito è `individual`, quindi per gli eventi di un'azienda è necessario `entity_type=company`. I filtri di `GET /v3/events/` si applicano in aggiunta e un `vendor_data` senza eventi restituisce una pagina vuota anziché `404`. Una chiave API con ambito limitato richiede `transactions: read`. Vedi [Lettura degli eventi registrati](https://docs.didit.me/it/transaction-monitoring/events#lettura-degli-eventi).", "operationId": "get_monitoring_event_subject_timeline", "x-didit-sdk": { "resource": "monitoring_events", "method": "retrieve_subject_timeline", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "description": "Il tuo ID per il soggetto (`subject.vendor_data` dei suoi eventi). Codificalo in formato URL; un valore contenente `/` non può essere indirizzato da questo endpoint.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "user-42" }, { "name": "entity_type", "in": "query", "required": false, "description": "`company` restituisce l'azienda con questo `vendor_data`; qualsiasi altro valore, o nessuno, restituisce la persona fisica. `subject_entity_type` viene accettato come alias quando `entity_type` è assente.", "schema": { "type": "string", "enum": [ "individual", "company" ], "default": "individual" }, "example": "individual" }, { "name": "limit", "in": "query", "required": false, "description": "Numero massimo di eventi per pagina. Il valore predefinito è 50. I valori superiori a 1000000 restituiscono `400`; un valore non numerico, pari a zero o negativo viene reimpostato su 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "Numero di eventi da saltare. Il valore predefinito è 0. È preferibile seguire l'URL `next` della risposta.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 0 }, { "name": "event_category", "in": "query", "required": false, "description": "Solo gli eventi in queste categorie. Ripeti il parametro per più valori (`?event_category=payment&event_category=dispute`); viene restituito un evento corrispondente a uno qualsiasi di essi.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] } }, "example": [ "payment", "dispute" ] }, { "name": "action_type", "in": "query", "required": false, "description": "Solo gli eventi con questi tipi di azione (esatti, con distinzione tra maiuscole e minuscole). Ripeti per più valori.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "deposit_completed", "chargeback_opened" ] }, { "name": "status", "in": "query", "required": false, "description": "Solo gli eventi con questi stati. Ripeti per più valori.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ] } }, "example": [ "IN_REVIEW", "DECLINED" ] }, { "name": "retention_class", "in": "query", "required": false, "description": "Solo gli eventi in queste classi di conservazione. Ripeti per più valori.", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ] } }, "example": [ "risk_relevant" ] }, { "name": "business_vendor_data", "in": "query", "required": false, "description": "Corrispondenza esatta sul `business.vendor_data` inviato con l'evento.", "schema": { "type": "string" }, "example": "merchant-7" }, { "name": "session_id", "in": "query", "required": false, "description": "Corrispondenza esatta su `session.session_id`.", "schema": { "type": "string" }, "example": "web-session-abc" }, { "name": "device_fingerprint", "in": "query", "required": false, "description": "Corrispondenza esatta su `device_context.fingerprint`.", "schema": { "type": "string" }, "example": "fp-a8c1" }, { "name": "ip_address", "in": "query", "required": false, "description": "Corrispondenza esatta sull'indirizzo IP dell'evento.", "schema": { "type": "string" }, "example": "203.0.113.42" }, { "name": "game_id", "in": "query", "required": false, "description": "Corrispondenza esatta su `game_id` promosso.", "schema": { "type": "string" }, "example": "poker-holdem-01" }, { "name": "round_id", "in": "query", "required": false, "description": "Corrispondenza esatta su `round_id` promosso.", "schema": { "type": "string" }, "example": "round-88231" }, { "name": "affiliate_code", "in": "query", "required": false, "description": "Corrispondenza esatta su `affiliate_code` promosso.", "schema": { "type": "string" }, "example": "aff-summer" }, { "name": "payment_reference_id", "in": "query", "required": false, "description": "Corrispondenza esatta sul riferimento di pagamento (da `transaction_context.payment_reference_id` o `payload.payment_reference_id`).", "schema": { "type": "string" }, "example": "dep_735" }, { "name": "counterparty_vendor_data", "in": "query", "required": false, "description": "Corrispondenza esatta su `counterparty_vendor_data` promosso.", "schema": { "type": "string" }, "example": "user-77" }, { "name": "matched_only", "in": "query", "required": false, "description": "`true` (anche `1` o `yes`, senza distinzione tra maiuscole e minuscole) restituisce solo gli eventi a cui corrisponde almeno una regola (`rules_matched_count` maggiore di 0). Qualsiasi altro valore viene ignorato.", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "occurred_from", "in": "query", "required": false, "description": "Solo gli eventi con `occurred_at` pari o successivo a questo istante (incluso). Invia un valore ISO 8601: `2026-10-01T00:00:00Z`, un offset esplicito con il `+` codificato in percentuale (`2026-10-01T02:00:00%2B02:00`; un `+` non codificato viene decodificato come spazio e il valore non risulta più analizzabile), oppure solo una data (`2026-10-01`), che indica le 00:00:00 UTC di quel giorno. Un valore privo di offset viene interpretato come UTC. I valori in qualsiasi altro formato non sono accettati.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "occurred_to", "in": "query", "required": false, "description": "Solo gli eventi con `occurred_at` pari o antecedente a questo istante (incluso). Una data da sola indica l'inizio di quel giorno, quindi `occurred_to=2026-10-15` esclude il resto del 15 ottobre; invia `2026-10-15T23:59:59Z` per includerlo. Invia un valore ISO 8601: `2026-10-01T00:00:00Z`, un offset esplicito con il `+` codificato in percentuale (`2026-10-01T02:00:00%2B02:00`; un `+` non codificato viene decodificato come spazio e il valore non risulta più analizzabile), oppure solo una data (`2026-10-01`), che indica le 00:00:00 UTC di quel giorno. Un valore privo di offset viene interpretato come UTC. I valori in qualsiasi altro formato non sono accettati.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-17T23:59:59Z" }, { "name": "search", "in": "query", "required": false, "description": "Corrispondenza di sottostringhe senza distinzione tra maiuscole e minuscole su `event_id`, `action_type`, `subject_vendor_data` o `counterparty_vendor_data`.", "schema": { "type": "string" }, "example": "chargeback" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/subjects/user-42/?entity_type=individual&limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.monitoring_events.retrieve_subject_timeline(\n \"user-42\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.monitoringEvents.retrieveSubjectTimeline(\"user-42\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.MonitoringEvents.RetrieveSubjectTimelineAutoPaging(ctx, \"user-42\", didit.MonitoringEventsRetrieveSubjectTimelineParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.monitoringEvents().retrieveSubjectTimeline(\"user-42\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->retrieveSubjectTimeline('user-42') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.monitoring_events.retrieve_subject_timeline(\"user-42\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.MonitoringEvents.RetrieveSubjectTimelineAsync(\"user-42\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina degli eventi del soggetto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventPage" }, "examples": { "Individual timeline": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "event_uuid": "11111111-2222-3333-4444-555555555555", "event_id": "chargeback-2026-10-16-000318", "event_category": "dispute", "action_type": "chargeback_opened", "occurred_at": "2026-10-16T14:02:11Z", "received_at": "2026-10-16T14:02:12.418230Z", "status": "IN_REVIEW", "score": 60, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": null, "device_fingerprint": null, "ip_address": null, "ip_country": null, "amount": "250.000000000000000000", "currency": "EUR", "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": "dep_735", "retention_class": "monetary_or_compliance", "rules_matched_count": 1, "correlation_pending": false, "is_droppable": false }, { "event_uuid": "22222222-3333-4444-5555-666666666666", "event_id": "login-2026-10-15-000912", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-15T08:30:00.120000Z", "received_at": "2026-10-15T08:30:00.734512Z", "status": "ACCEPTED", "score": 0, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": "web-session-abc", "device_fingerprint": "fp-a8c1", "ip_address": "203.0.113.42", "ip_country": "ES", "amount": null, "currency": null, "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": null, "retention_class": "standard", "rules_matched_count": 0, "correlation_pending": false, "is_droppable": true } ] } }, "No events": { "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "400": { "description": "`limit` o `offset` è maggiore di 1000000. Il corpo è un array JSON con un messaggio. Un `limit` non numerico o non positivo utilizza il valore predefinito di 50 invece di fallire.", "content": { "application/json": { "examples": { "limit too large": { "summary": "limit superiore a 1000000", "value": [ "limit must not exceed 1000000." ] }, "offset too large": { "summary": "offset superiore a 1000000", "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Solo una chiave scaduta riceve `401`; una chiave mancante o non valida riceve `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Intestazione `x-api-key` mancante (una chiave errata, revocata o scaduta restituisce `401`), una chiave con ambito priva di `transactions: read`, una chiave limitata ad alcuni workflow o a sessioni approvate (tale chiave non accede mai ai dati di monitoraggio delle transazioni), oppure una richiesta proveniente dall'esterno dell'allowlist IP della chiave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite di frequenza superato: le richieste `GET` condividono un budget di 600 richieste al minuto per chiave API. Attendi `Retry-After` secondi, quindi riprova.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/enrichment-metrics/": { "get": { "summary": "Recupera metriche di arricchimento eventi", "description": "Restituisce i contatori di acquisizione degli eventi e di arricchimento IP della tua applicazione per un determinato periodo, sommati su ogni canale (server, batch e dispositivo), consentendoti di monitorare il volume degli eventi e confermare che l'arricchimento venga eseguito una sola volta per indirizzo univoco anziché per ogni evento. Il periodo include la data odierna più i `days` giorni precedenti, calcolati in base alla data di calendario UTC. I tre rapporti sono null quando il relativo denominatore è zero. Una chiave API con ambito limitato richiede `transactions: read`. Consulta [arricchimento IP](https://docs.didit.me/it/transaction-monitoring/events#arricchimento-ip).", "operationId": "get_monitoring_event_enrichment_metrics", "x-didit-sdk": { "resource": "monitoring_events", "method": "retrieve_enrichment_metrics", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "Durata del periodo in giorni. Il valore predefinito è 30; i valori sono limitati all'intervallo compreso tra 1 e 365, e un valore non intero torna a 30. Il valore applicato viene restituito come `period_days`.", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "example": 30 } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/enrichment-metrics/?days=30' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.retrieve_enrichment_metrics()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.retrieveEnrichmentMetrics();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.RetrieveEnrichmentMetrics(ctx, didit.MonitoringEventsRetrieveEnrichmentMetricsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().retrieveEnrichmentMetrics();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->retrieveEnrichmentMetrics();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.retrieve_enrichment_metrics\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.RetrieveEnrichmentMetricsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Contatori e rapporti per il periodo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "events_ingested", "events_rejected", "enrichment_lookups", "enrichment_cache_hits", "enrichment_provider_calls", "enrichment_skipped_low_value", "unique_ips_seen", "period_days", "cache_hit_rate", "unique_ip_ratio", "provider_calls_per_1k_events" ], "properties": { "events_ingested": { "type": "integer", "description": "Nuovi eventi memorizzati. I replay idempotenti non vengono conteggiati." }, "events_rejected": { "type": "integer", "description": "Elementi rifiutati all'interno di richieste in batch (lato server e lato dispositivo). Una richiesta per evento singolo rifiutata non viene conteggiata." }, "enrichment_lookups": { "type": "integer", "description": "Eventi il cui indirizzo IP pubblico è stato risolto, dalla cache o ex novo." }, "enrichment_cache_hits": { "type": "integer", "description": "Ricerche risposte dalla cache." }, "enrichment_provider_calls": { "type": "integer", "description": "Ricerche che hanno richiesto una nuova risoluzione dell'indirizzo." }, "enrichment_skipped_low_value": { "type": "integer", "description": "Eventi di telemetria di basso valore il cui indirizzo non era già noto. Non attivano mai una nuova risoluzione autonoma." }, "unique_ips_seen": { "type": "integer", "description": "Indirizzi che richiedevano una nuova risoluzione." }, "period_days": { "type": "integer", "description": "Il valore `days` applicato dopo l'applicazione dei limiti." }, "cache_hit_rate": { "type": "number", "nullable": true, "description": "`enrichment_cache_hits / enrichment_lookups`, arrotondato a 4 decimali. Null quando non ci sono state ricerche." }, "unique_ip_ratio": { "type": "number", "nullable": true, "description": "`unique_ips_seen / events_ingested`, arrotondato a 4 decimali. Null quando non è stato acquisito alcun evento." }, "provider_calls_per_1k_events": { "type": "number", "nullable": true, "description": "Risoluzioni recenti per 1000 eventi acquisiti, arrotondate a 2 decimali. Null se non è stato acquisito alcun evento." } } }, "examples": { "Last 30 days": { "value": { "events_ingested": 128450, "events_rejected": 214, "enrichment_lookups": 41230, "enrichment_cache_hits": 40118, "enrichment_provider_calls": 1112, "enrichment_skipped_low_value": 74320, "unique_ips_seen": 1112, "period_days": 30, "cache_hit_rate": 0.973, "unique_ip_ratio": 0.0087, "provider_calls_per_1k_events": 8.66 } }, "No events yet": { "value": { "events_ingested": 0, "events_rejected": 0, "enrichment_lookups": 0, "enrichment_cache_hits": 0, "enrichment_provider_calls": 0, "enrichment_skipped_low_value": 0, "unique_ips_seen": 0, "period_days": 30, "cache_hit_rate": null, "unique_ip_ratio": null, "provider_calls_per_1k_events": null } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Solo una chiave scaduta riceve `401`; una chiave mancante o non valida riceve `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Intestazione `x-api-key` mancante (una chiave errata, revocata o scaduta restituisce `401`), una chiave con ambito priva di `transactions: read`, una chiave limitata ad alcuni workflow o a sessioni approvate (tale chiave non accede mai ai dati di monitoraggio delle transazioni), oppure una richiesta proveniente dall'esterno dell'allowlist IP della chiave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Limite di frequenza superato: le richieste `GET` condividono un budget di 600 richieste al minuto per chiave API. Attendi `Retry-After` secondi, quindi riprova.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/{event_uuid}/delete/": { "delete": { "summary": "Elimina evento di monitoraggio", "description": "Elimina definitivamente un evento di monitoraggio insieme alle relative esecuzioni delle regole, note e collegamenti ai tag, ad esempio un evento inviato per errore. Dopo il `204` l'evento non è più presente in alcuna operazione di lettura (il recupero restituisce `404` e non compare più nell'elenco o nella cronologia del soggetto), l'eliminazione è irreversibile e il suo `event_id` può essere riutilizzato per un nuovo evento. Non sono interessati: l'utente o l'azienda a cui l'evento è stato associato, i casi aperti da una regola, le voci di elenco aggiunte da una regola e i punteggi e gli stati già applicati ad altri eventi. Per cancellare tutto ciò che riguarda una persona o un'azienda, elimina invece l'utente o l'azienda, eliminando così anche i relativi eventi. Una chiave API con ambito limitato richiede `transactions: write`.", "operationId": "delete_monitoring_event", "x-didit-sdk": { "resource": "monitoring_events", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "event_uuid", "in": "path", "required": true, "description": "Identificatore Didit dell'evento (`event_uuid` dalla risposta di creazione, batch, elenco o timeline), non il tuo `event_id`.", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/events/11111111-2222-3333-4444-555555555555/delete/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.monitoring_events.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.monitoringEvents.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.MonitoringEvents.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.monitoringEvents().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.monitoring_events.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.MonitoringEvents.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "L'evento è stato eliminato. Nessun payload." }, "401": { "description": "La chiave API con ambito è scaduta. Solo una chiave scaduta riceve `401`; una chiave mancante o non valida riceve `403`.", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Intestazione `x-api-key` mancante (una chiave errata, revocata o scaduta restituisce `401`), una chiave con ambito priva di `transactions: write`, una chiave limitata ad alcuni workflow o a sessioni approvate (tale chiave non accede mai ai dati di monitoraggio delle transazioni), oppure una richiesta proveniente dall'esterno dell'allowlist IP della chiave.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Nessun evento con questo `event_uuid` esiste nell'applicazione: non è mai stato memorizzato, è stato eliminato o appartiene a un'altra applicazione. Un segmento di percorso che non sia un UUID non corrisponde alla route e restituisce anch'esso `404`.", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No MonitoringEvent matches the given query." } } } } } }, "429": { "description": "Limite di frequenza superato: le richieste di scrittura (`POST`, `PATCH`, `DELETE`) condividono un budget di 300 richieste al minuto per chiave API. Attendi `Retry-After` secondi, quindi riprova.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/kyb/parties/{partyUuid}/regenerate/": { "post": { "summary": "Rigenera la sessione KYC di un soggetto Key People", "description": "Assegna a una controparte di tipo persona chiave in una sessione di Verifica aziendale (KYB) una nuova sessione KYC individuale dopo che la precedente è stata eliminata o è scaduta prima che la persona la avviasse, in modo che il controllo sulle persone chiave possa concludersi nuovamente; non inviare alcun corpo della richiesta. Funziona quando la sessione KYC della controparte è stata eliminata (`kyc_session_deleted: true`) o è scaduta prima che la persona la avviasse (`Expired`, mai avviata). Una sessione ancora in corso o terminata con qualsiasi altro stato (`Approved`, `Declined`, `In Review`, `Abandoned`, ...) restituisce `409` a meno che non sia stata eliminata. Una controparte che non ne ha mai avuta una o una controparte aziendale restituisce sempre `409`. Didit crea una nuova sessione KYC ospitata con il workflow con cui la controparte è stata verificata (la sua versione pubblicata più recente) o, quando non è più nota, il workflow assegnato al ruolo della controparte nelle impostazioni delle persone chiave, in modo che il relativo link rimanga valido per il tempo di scadenza della sessione di quel workflow KYC; invia il link via email alla controparte se è presente un indirizzo email registrato, azzera `is_skipped` e ricalcola il controllo sulle persone chiave e lo stato della sessione aziendale. Invia quindi un [webhook](https://docs.didit.me/it/integration/webhooks) `data.updated` per la sessione aziendale con trigger `console_key_people_regenerate`; per esentare invece la controparte, usa `PATCH /v3/session/{sessionId}/kyb/parties/{partyUuid}/`. Una chiave API con ambito limitato richiede `decisions: write` e senza `sessions: write` riceve `kyc_session_url` come `null`. Le sessioni eliminate sono idonee anche se la persona aveva già avviato o completato la verifica. Le sessioni importate non sono idonee tramite scadenza; devono essere state eliminate.", "operationId": "post_v3_session_kyb_party_regenerate", "x-didit-sdk": { "resource": "sessions", "method": "regenerate_kyb_party", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione padre di Verifica aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "partyUuid", "in": "path", "required": true, "description": "UUID della parte relativa alle persone chiave (`key_people_checks[].submitted.parties[].uuid` nella decisione della sessione aziendale). Deve appartenere alla sessione a cui fa riferimento `sessionId`.", "schema": { "type": "string", "format": "uuid", "example": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/session/33333333-4444-5555-6666-777777777777/kyb/parties/0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41/regenerate/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.regenerate_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.regenerateKybParty(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.RegenerateKYBParty(ctx, \"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().regenerateKybParty(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->regenerateKybParty('33333333-4444-5555-6666-777777777777', '0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.regenerate_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.RegenerateKybPartyAsync(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Nuova sessione KYC creata. Restituisce il soggetto aggiornato con la sua nuova sessione figlia, che scade dopo il tempo di scadenza della sessione del relativo workflow KYC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBKeyPeopleParty" }, "example": { "uuid": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41", "entity_type": "person", "source": "USER", "name": "Jane Smith", "first_name": "Jane", "last_name": "Smith", "company_name": null, "registration_number": null, "email": "user@example.com", "nationality": "GB", "phone_number": null, "date_of_birth": "1980-05-04", "position": "Director", "custom_fields": {}, "is_active": true, "is_skipped": false, "requires_verification": true, "roles": [ { "role": "director", "ownership_percent": null, "voting_percent": null } ], "kyc_session_id": "55555555-6666-7777-8888-999999999999", "kyc_session_status": "Not Started", "kyc_session_url": "https://verify.didit.me/session/abc123def456", "kyc_session_deleted": false, "kyb_sub_session_id": null, "kyb_sub_session_status": null, "kyb_sub_session_url": null, "kyb_sub_session_deleted": false, "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" } ], "didit_internal_id": null } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata o non rientra nei limiti di una chiave con ambito limitato; nessuna parte con questo UUID esiste nella tua applicazione; oppure la parte appartiene a un'altra sessione. Ogni caso ha il proprio `detail`. La ricerca della sessione viene eseguita prima della verifica delle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche senza una chiave valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID esiste, oppure è stata eliminata", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "La sessione non rientra nei limiti di workflow o di sola approvazione di una chiave con ambito limitato", "value": { "detail": "Session not found." } }, "Unknown party": { "summary": "Nessuna parte con questo UUID nella tua applicazione", "value": { "detail": "No BusinessParty matches the given query." } }, "Party of another session": { "summary": "partyUuid esiste ma appartiene a una sessione diversa", "value": { "detail": "Party does not belong to the given session." } } } } } }, "409": { "description": "La parte non ha alcuna sessione KYC idonea da sostituire. A meno che non sia stata eliminata, una sessione ancora in corso o una terminata con un altro stato (`Approved`, `Declined`, `In Review`, `Abandoned`, ...) non può essere rigenerata. Anche una parte che non ne ha mai avuta una o una parte di tipo aziendale restituisce `409`. Una sessione idonea è stata eliminata o è scaduta prima che la persona la avviasse. Le sessioni eliminate sono idonee anche se la persona aveva già avviato o completato la verifica. Le sessioni importate non sono idonee per effetto della scadenza; devono essere state eliminate. Gestisci il caso in base a `code`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." }, "code": { "type": "string", "enum": [ "kyb_party_kyc_session_not_deleted" ], "description": "Codice di errore stabile leggibile da macchina." } } }, "example": { "detail": "This party's KYC session is still live (it has neither been deleted nor expired without starting), so it cannot be regenerated.", "code": "kyb_party_kyc_session_not_deleted" } } } }, "429": { "description": "Limite di frequenza superato: 300 richieste di scrittura (POST, PATCH, DELETE) al minuto per chiave API. Attendi i secondi indicati in `Retry-After` prima di riprovare; le intestazioni `X-RateLimit-*` indicano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/{transaction_id}/notes/": { "get": { "summary": "Elenca le note della transazione", "description": "Elenca le note su una transazione monitorata, dalla più recente (`created_at` decrescente): note che aggiungi tramite l'API, note e modifiche di stato effettuate dai revisori nella Console, e note aggiunte automaticamente da Didit (l'azione `add_note` di una regola, o un problema durante la creazione della sessione di verifica dell'azione dell'utente), che riportano `actor_name` `Rule Engine`. `metadata` distingue i tipi di nota.\n\nPaginato con `limit` e `offset`. `count` è esatto fino a 100 e limitato a 100 oltre tale valore, quindi segui `next` finché non diventa `null` invece di calcolare le pagine da `count`. Questa è una lettura senza effetti collaterali.\n\nUna chiave API con ambito limitato richiede `transactions: read`; una chiave limitata ad alcuni workflow o a sessioni approvate non può chiamare questo endpoint. I revisori vedono lo stesso elenco sotto **Notes** nel [dettaglio della transazione](https://docs.didit.me/it/transaction-monitoring/console#dettaglio-della-transazione).", "operationId": "list_transaction_notes", "x-didit-sdk": { "resource": "transactions.notes", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID della transazione Didit: l'`uuid` restituito da `POST /v3/transactions/` e `GET /v3/transactions/`. Il tuo `txn_id` personale non è accettato.", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Numero di note per pagina. Il valore predefinito è 50. Un valore che non sia un numero intero positivo reimposta il valore a 50; un valore superiore a 1000000 restituisce `400`." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Posizione in base zero della prima nota da restituire. È preferibile seguire `next`. Un valore che non è un numero intero reimposta a 0; un valore superiore a 1000000 restituisce `400`." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.notes.list(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.notes.list(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Notes.ListAutoPaging(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsNotesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().notes().list(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->notes->list('abcdef12-3456-7890-abcd-ef1234567890') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.notes.list(\"abcdef12-3456-7890-abcd-ef1234567890\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.Notes.ListAsync(\"abcdef12-3456-7890-abcd-ef1234567890\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina di note, dalla più recente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Numero di note sulla transazione: esatto fino a 100, limitato a 100 al di sopra. Segui `next` invece di calcolare le pagine a partire da questo valore." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionNote" } } } }, "examples": { "API, Console and rule notes": { "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "c1111111-2222-4333-8444-555555555555", "note": "Customer confirmed the withdrawal by phone.", "actor_email": null, "actor_name": null, "metadata": { "mentioned_emails": [ "analyst@example.com" ] }, "created_at": "2026-10-16T10:05:12.481203Z" }, { "uuid": "c2222222-3333-4444-8555-666666666666", "note": "Status changed from IN_REVIEW to APPROVED. Reason: Source of funds verified", "actor_email": "reviewer@example.com", "actor_name": "Alex Reviewer", "metadata": { "type": "status_change", "previous_status": "IN_REVIEW", "new_status": "APPROVED", "reason_code": "SOF_VERIFIED", "reason_label": "Source of funds verified" }, "created_at": "2026-10-15T17:22:40.103911Z" }, { "uuid": "c3333333-4444-4555-8666-777777777777", "note": "Large withdrawal to a new wallet: check the source of funds.", "actor_email": null, "actor_name": "Rule Engine", "metadata": { "rule_uuid": "d1111111-2222-4333-8444-555555555555", "source": "rule_action" }, "created_at": "2026-10-15T08:42:12.004518Z" } ] } }, "No notes yet": { "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "400": { "description": "`limit` o `offset` è superiore a 1000000. Il corpo è un array JSON di messaggi, non un oggetto.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "Limit too large": { "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "La chiave API è scaduta. Solo una chiave creata con una data di scadenza può scadere; dopo tale data ogni richiesta inviata con essa risponde con `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave mancante riceve il messaggio generico; una chiave errata, revocata o scaduta riceve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without transactions read": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Nessuna transazione con questo UUID esiste nell'applicazione (mai creata, eliminata o di proprietà di un'altra applicazione). Un `transaction_id` che non è un UUID non raggiunge l'API: restituisce una pagina HTML `404` invece di questo corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "Più di 600 richieste GET al minuto con questa chiave API. Attendi il numero di secondi indicato in `Retry-After`, quindi riprova.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi fino al ripristino della finestra temporale corrente di un minuto.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Richieste consentite al minuto per questo budget.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Ora Unix in cui la finestra si azzera.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Crea nota della transazione", "description": "Aggiungi una nota in testo normale alla cronologia di revisione di una transazione monitorata, visibile ai revisori nella Console. Una nota fornisce contesto, non è una decisione: i valori `status`, `score` e gli alert della transazione non cambiano, non viene inviato alcun webhook e non viene addebitato nulla. Le `activities` della transazione ricevono una voce `TRANSACTION_NOTE_ADDED`.\n\nLe note create con una chiave API non hanno un autore: `actor_email` e `actor_name` sono `null`, quindi inserisci l'autore nel testo se necessario. Ogni indirizzo in `mentioned_emails` deve appartenere a un membro della tua organizzazione, altrimenti l'intera richiesta fallisce con `400`; le menzioni vengono salvate in minuscolo e deduplicate, e questo endpoint non invia notifiche ai membri menzionati.\n\nOgni chiamata crea una nuova nota, quindi ripetere una richiesta andata in timeout può aggiungerla due volte: elenca le note prima di riprovare. Non esiste un endpoint API per modificare o rimuovere una nota. Una chiave API con ambito limitato richiede `transactions: write`; una chiave limitata a determinati workflow o a sessioni approvate non può chiamare questo endpoint.", "operationId": "create_transaction_note", "x-didit-sdk": { "resource": "transactions.notes", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID della transazione Didit: l'`uuid` restituito da `POST /v3/transactions/` e `GET /v3/transactions/`. Il tuo `txn_id` personale non è accettato.", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "note" ], "properties": { "note": { "type": "string", "minLength": 1, "description": "Nota in testo normale. Gli spazi vuoti iniziali e finali vengono rimossi e una nota vuota viene rifiutata. Nessun limite di lunghezza." }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "default": [], "description": "Indirizzi email dei membri della tua organizzazione da menzionare. Ognuno deve essere un'email valida di un membro dell'organizzazione." } } }, "examples": { "Note with a mention": { "value": { "note": "Customer confirmed the withdrawal by phone.", "mentioned_emails": [ "analyst@example.com" ] } }, "Plain note": { "value": { "note": "Source of funds document requested by email." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"note\": \"Customer confirmed the withdrawal by phone.\", \"mentioned_emails\": [\"analyst@example.com\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.notes.create(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n note=\"Customer confirmed the withdrawal by phone.\",\n mentioned_emails=[\"analyst@example.com\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.notes.create(\"abcdef12-3456-7890-abcd-ef1234567890\", {\n note: \"Customer confirmed the withdrawal by phone.\",\n mentioned_emails: [\"analyst@example.com\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Notes.Create(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsNotesCreateParams{\n\tNote: \"Customer confirmed the withdrawal by phone.\",\n\tMentionedEmails: didit.Some([]string{\"analyst@example.com\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TransactionsNotesCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().notes().create(\"abcdef12-3456-7890-abcd-ef1234567890\", TransactionsNotesCreateParams.builder()\n .note(\"Customer confirmed the withdrawal by phone.\")\n .mentionedEmails(List.of(\"analyst@example.com\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->notes->create('abcdef12-3456-7890-abcd-ef1234567890', [\n 'note' => 'Customer confirmed the withdrawal by phone.',\n 'mentioned_emails' => ['analyst@example.com'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.notes.create(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n note: \"Customer confirmed the withdrawal by phone.\",\n mentioned_emails: [\"analyst@example.com\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Notes.CreateAsync(\"abcdef12-3456-7890-abcd-ef1234567890\", new TransactionsNotesCreateParams\n{\n Note = \"Customer confirmed the withdrawal by phone.\",\n MentionedEmails = new string[] { \"analyst@example.com\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "La nota è stata creata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionNote" }, "examples": { "Created": { "value": { "uuid": "c1111111-2222-4333-8444-555555555555", "note": "Customer confirmed the withdrawal by phone.", "actor_email": null, "actor_name": null, "metadata": { "mentioned_emails": [ "analyst@example.com" ] }, "created_at": "2026-10-16T10:05:12.481203Z" } } } } } }, "400": { "description": "Il corpo non è valido: `note` mancante, null o vuoto, un indirizzo non valido in `mentioned_emails` (errori indicizzati in base alla posizione nella lista) o un indirizzo menzionato che non è membro della tua organizzazione. Non è stato creato nulla.", "content": { "application/json": { "schema": { "type": "object", "description": "Errori di campo indicizzati per nome campo.", "additionalProperties": {} }, "examples": { "Missing note": { "value": { "note": [ "This field is required." ] } }, "Blank note": { "value": { "note": [ "This field may not be blank." ] } }, "Invalid email": { "value": { "mentioned_emails": { "0": [ "Enter a valid email address." ] } } }, "Not an organization member": { "value": { "mentioned_emails": [ "Mentioned users must belong to this organization and have access to this application." ] } } } } } }, "401": { "description": "La chiave API è scaduta. Solo una chiave creata con una data di scadenza può scadere; dopo tale data ogni richiesta inviata con essa risponde con `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave mancante riceve il messaggio generico; una chiave errata, revocata o scaduta riceve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without transactions write": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Nessuna transazione con questo UUID esiste nell'applicazione (mai creata, eliminata o di proprietà di un'altra applicazione). Un `transaction_id` che non è un UUID non raggiunge l'API: restituisce una pagina HTML `404` invece di questo corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "Più di 300 richieste di scrittura al minuto con questa chiave API. Attendi il numero di secondi indicato in `Retry-After`, quindi riprova.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi fino al ripristino della finestra temporale corrente di un minuto.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Richieste consentite al minuto per questo budget.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Ora Unix in cui la finestra si azzera.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/{transaction_id}/related/": { "get": { "summary": "Elenca le transazioni correlate", "description": "Elenca le altre transazioni nella tua applicazione che coinvolgono le stesse persone o aziende di questa. Una transazione è correlata quando una qualsiasi delle sue parti, in qualsiasi ruolo, ha lo stesso `vendor_data` di una delle parti di questa transazione. La transazione stessa non viene mai restituita e le parti senza `vendor_data` vengono ignorate: se nessuna delle parti di questa transazione ne ha uno, il risultato è sempre vuoto.\n\nI risultati utilizzano il formato di riepilogo di `GET /v3/transactions/`, dalla più recente alla meno recente (`txn_date`, poi `created_at`). Impaginati con `limit` e `offset`; `count` è esatto fino a 100 e limitato a un massimo di 100 oltre tale valore, quindi segui `next` fino a quando non è `null`.\n\nUna chiave API con ambito limitato richiede `transactions: read`; una chiave limitata ad alcuni workflow o a sessioni approvate non può chiamare questo endpoint. Invia lo stesso `vendor_data` per la stessa persona o azienda in ogni [transazione](https://docs.didit.me/it/transaction-monitoring/transactions#soggetto-e-controparte) per rendere completo questo elenco.", "operationId": "list_related_transactions", "x-didit-sdk": { "resource": "transactions", "method": "list_related", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "UUID della transazione Didit: l'`uuid` restituito da `POST /v3/transactions/` e `GET /v3/transactions/`. Il tuo `txn_id` personale non è accettato.", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "Numero di transazioni per pagina. Il valore predefinito è 50. Un valore che non sia un numero intero positivo reimposta il valore a 50; un valore superiore a 1000000 restituisce `400`." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "Posizione in base zero della prima transazione da restituire. È preferibile seguire `next`. Un valore che non è un numero intero reimposta a 0; un valore superiore a 1000000 restituisce `400`." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/related/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.list_related(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.listRelated(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.ListRelatedAutoPaging(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsListRelatedParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().listRelated(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->listRelated('abcdef12-3456-7890-abcd-ef1234567890') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.list_related(\"abcdef12-3456-7890-abcd-ef1234567890\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.ListRelatedAsync(\"abcdef12-3456-7890-abcd-ef1234567890\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina di transazioni correlate, dalla più recente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Numero di transazioni correlate: esatto fino a 100, limitato a 100 al di sopra. Segui `next` invece di calcolare le pagine a partire da questo valore." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina successiva, o `null` sull'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL assoluto della pagina precedente, o `null` sulla prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionSummary" } } } }, "examples": { "One related transaction": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "abcdef99-3456-4890-abcd-ef1234567890", "transaction_number": 4087, "txn_id": "your-txn-2026-10-02-017", "transaction_type": "finance", "action_type": "deposit", "status": "APPROVED", "source": "LIVE", "direction": "INBOUND", "amount": "250", "currency": "EUR", "currency_type": "fiat", "preferred_currency_amount": "270.08", "preferred_currency_code": "USD", "payment_details": "Card top-up", "txn_date": "2026-10-02T14:10:00Z", "created_at": "2026-10-02T14:10:03.512244Z", "score": 12, "severity": "LOW", "decision_reason_code": null, "decision_reason_label": null, "tags": [], "subject_name": "Maria Garcia", "subject_vendor_data": "user-12345", "subject_type": "user", "subject_uuid": "e1111111-2222-4333-8444-555555555555", "counterparty_name": null, "counterparty_vendor_data": null, "counterparty_country": null, "subject_country": "ESP", "assigned_to_name": null, "travel_rule_status": null, "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "application_name": "Production app", "organization_id": "11111111-2222-3333-4444-555555555555", "organization_name": "Example Org" } ] } }, "No party has vendor_data": { "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "400": { "description": "`limit` o `offset` è superiore a 1000000. Il corpo è un array JSON di messaggi, non un oggetto.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "Limit too large": { "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "La chiave API è scaduta. Solo una chiave creata con una data di scadenza può scadere; dopo tale data ogni richiesta inviata con essa risponde con `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Una chiave mancante riceve il messaggio generico; una chiave errata, revocata o scaduta riceve `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without transactions read": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Nessuna transazione con questo UUID esiste nell'applicazione (mai creata, eliminata o di proprietà di un'altra applicazione). Un `transaction_id` che non è un UUID non raggiunge l'API: restituisce una pagina HTML `404` invece di questo corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "Più di 600 richieste GET al minuto con questa chiave API. Attendi il numero di secondi indicato in `Retry-After`, quindi riprova.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi fino al ripristino della finestra temporale corrente di un minuto.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Richieste consentite al minuto per questo budget.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Ora Unix in cui la finestra si azzera.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/{business_session_id}/pdf/": { "get": { "summary": "Scarica un report PDF della sessione aziendale", "description": "Esegue il rendering del report PDF di una sessione di Verifica aziendale (KYB): dati del registro delle imprese, persone chiave e titolari effettivi, documenti, risultati AML e le altre funzionalità del workflow, oltre ai tag e all'attività di revisione della sessione. Con la personalizzazione white label attiva, il report include il tuo logo e l'URL dell'informativa sulla privacy. Il corpo della risposta è il PDF stesso (`application/pdf`), non JSON.\n\nLa sessione deve essere nello stato `Approved`, `Declined` o `In Review`; qualsiasi altro stato restituisce `403`, quindi attendi prima il [webhook](https://docs.didit.me/it/integration/webhooks) `status.updated`. Il report viene generato a ogni chiamata e non viene fatturato nulla, quindi archivia il file anziché recuperarlo ripetutamente. `GET /v3/session/{sessionId}/generate-pdf/` esegue il rendering dello stesso tipo di report utilizzando solo l'ID sessione.\n\nUn report PDF conta come media: una chiave API con ambito limitato necessita di `businesses: read` e `media: read`, e una chiave limitata ad alcuni workflow o a sessioni approvate non può chiamarlo.", "operationId": "get_business_session_pdf", "x-didit-sdk": { "resource": "businesses", "method": "generate_session_pdf", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione.", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione. Deve essere l'applicazione a cui appartiene la chiave API: una chiave utilizzata su qualsiasi altra applicazione riceve `403`.", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "business_session_id", "in": "path", "required": true, "description": "`session_id` della sessione di Verifica aziendale (KYB), come restituito alla creazione della sessione. Una sessione di un'altra applicazione restituisce `404`.", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl --fail -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/businesses/22222222-3333-4444-5555-666666666666/pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output business_report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\ncontent = client.businesses.generate_session_pdf(\n \"22222222-3333-4444-5555-666666666666\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst content = await didit.businesses.generateSessionPdf(\"22222222-3333-4444-5555-666666666666\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresp, err := client.Businesses.GenerateSessionPDF(ctx, \"22222222-3333-4444-5555-666666666666\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.businesses().generateSessionPdf(\"22222222-3333-4444-5555-666666666666\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "businesses->generateSessionPdf('22222222-3333-4444-5555-666666666666');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ncontent = didit.businesses.generate_session_pdf(\"22222222-3333-4444-5555-666666666666\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar content = await client.Businesses.GenerateSessionPdfAsync(\"22222222-3333-4444-5555-666666666666\");\nawait content.SaveToAsync(\"download.pdf\");" } ], "responses": { "200": { "description": "Il PDF renderizzato, restituito direttamente come binario `application/pdf`.", "headers": { "Content-Disposition": { "description": "Sempre `attachment; filename=business_{business_session_id}.pdf`.", "schema": { "type": "string", "example": "attachment; filename=business_22222222-3333-4444-5555-666666666666.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "La chiave API è scaduta. Solo una chiave creata con una data di scadenza può scadere; dopo tale data ogni richiesta inviata con essa risponde con `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita o la sessione non è terminata. Leggi `detail`: una sessione che non è `Approved`, `Declined` o `In Review`, una chiave API mancante (una chiave errata, revocata o scaduta riceve `401`), un `application_id` che non appartiene all'applicazione della chiave, una chiave con ambito senza `media: read` o `businesses: read`, una chiave limitata ai workflow o alle sessioni approvate, oppure una richiesta proveniente dall'esterno dell'elenco IP della chiave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Session not finished": { "value": { "detail": "You can only generate a PDF for sessions in review, declined or approved." } }, "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without media read": { "value": { "detail": "This API key has no read access to media." } }, "Scoped key without businesses read": { "value": { "detail": "This API key has no read access to companies." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Non esiste alcuna sessione aziendale con questo ID nell'applicazione (mai creata, eliminata o appartenente a un'altra applicazione). Un valore diverso da un UUID restituisce una pagina HTML `404` invece di questo corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "Business session not found." } } } } } }, "429": { "description": "Più di 600 richieste GET al minuto con questa chiave API. Attendi il numero di secondi indicato in `Retry-After`, quindi riprova.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi fino al ripristino della finestra temporale corrente di un minuto.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Richieste consentite al minuto per questo budget.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Ora Unix in cui la finestra si azzera.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/{transaction_uuid}/pdf/": { "get": { "summary": "Scarica un report PDF della transazione", "description": "Genera un report PDF per una transazione monitorata: panoramica e verdetto, parti e metodi di pagamento, proprietà personalizzate, alert ed esecuzioni delle regole, risultati dello screening e della Travel Rule, riepilogo della rete, dettaglio dei costi, fino a 50 transazioni correlate e le 20 voci di attività più recenti. Il corpo della risposta è il PDF stesso (`application/pdf`), non JSON.\n\nIl report viene generato a partire dai dati correnti della transazione a ogni chiamata, quindi richiedilo nuovamente dopo una modifica di stato. Non viene memorizzato nulla e non viene addebitato alcun costo. La generazione può richiedere alcuni secondi, quindi usa un timeout del client generoso.\n\nQuesto endpoint risiede su un percorso con ambito applicazione: inserisci nell'URL l'ID della tua organizzazione e l'ID dell'applicazione a cui appartiene la tua chiave API ([trova l'ID della tua organizzazione](https://docs.didit.me/it/getting-started/api-authentication#trovare-il-tuo-id-organizzazione)). Un report PDF è considerato un contenuto multimediale: una chiave API con ambito limitato deve avere le autorizzazioni `media: read` e `transactions: read`, e una chiave limitata ad alcuni workflow o a sessioni approvate non può chiamarlo.", "operationId": "get_transaction_pdf", "x-didit-sdk": { "resource": "transactions", "method": "generate_pdf", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Transactions" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione.", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione. Deve essere l'applicazione a cui appartiene la chiave API: una chiave utilizzata su qualsiasi altra applicazione riceve `403`.", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "transaction_uuid", "in": "path", "required": true, "description": "UUID della transazione Didit: l'`uuid` restituito da `POST /v3/transactions/` e `GET /v3/transactions/`. Il tuo `txn_id` personale non è accettato.", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl --fail -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/abcdef12-3456-7890-abcd-ef1234567890/pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output transaction_report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\ncontent = client.transactions.generate_pdf(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst content = await didit.transactions.generatePdf(\"abcdef12-3456-7890-abcd-ef1234567890\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresp, err := client.Transactions.GeneratePDF(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.transactions().generatePdf(\"abcdef12-3456-7890-abcd-ef1234567890\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "transactions->generatePdf('abcdef12-3456-7890-abcd-ef1234567890');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ncontent = didit.transactions.generate_pdf(\"abcdef12-3456-7890-abcd-ef1234567890\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar content = await client.Transactions.GeneratePdfAsync(\"abcdef12-3456-7890-abcd-ef1234567890\");\nawait content.SaveToAsync(\"download.pdf\");" } ], "responses": { "200": { "description": "Il PDF renderizzato, restituito direttamente come binario `application/pdf`.", "headers": { "Content-Disposition": { "description": "Sempre `attachment; filename=transaction_{transaction_uuid}.pdf`.", "schema": { "type": "string", "example": "attachment; filename=transaction_abcdef12-3456-7890-abcd-ef1234567890.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "La chiave API è scaduta. Solo una chiave creata con una data di scadenza può scadere; dopo tale data ogni richiesta inviata con essa risponde con `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Consulta `detail`: chiave API mancante (una chiave errata, revocata o scaduta restituisce `401`), un `application_id` diverso dall'applicazione della chiave, una chiave con ambito senza `media: read` o `transactions: read`, una chiave limitata a workflow o sessioni approvate, oppure una richiesta proveniente dall'esterno dell'elenco IP della chiave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without media read": { "value": { "detail": "This API key has no read access to media." } }, "Scoped key without transactions read": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "Nessuna transazione con questo UUID esiste nell'applicazione (mai creata, eliminata o di proprietà di un'altra applicazione). Un `transaction_uuid` che non è un UUID non raggiunge l'API: restituisce una pagina HTML `404` invece di questo corpo JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "Più di 600 richieste GET al minuto con questa chiave API. Attendi il numero di secondi indicato in `Retry-After`, quindi riprova.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi fino al ripristino della finestra temporale corrente di un minuto.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Richieste consentite al minuto per questo budget.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Ora Unix in cui la finestra si azzera.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/analytics/": { "get": { "summary": "Recupera le metriche dell'applicazione", "description": "Legge i dati numerici alla base della [dashboard di analisi](https://docs.didit.me/it/console/analytics) della Business Console per un intervallo di date. Senza `scope` e `widget_keys`, la risposta è il riepilogo della verifica degli utenti (KYC) (`ApplicationAnalyticsSummary`): conteggi giornalieri delle sessioni, totali per stato, tasso di conversione, le stesse metriche per il periodo precedente di pari durata, posizioni geografiche, dati demografici, dispositivi, funnel del workflow, tempo attivo di verifica, nuovi invii, avvisi e serie temporali. Con `scope` o `widget_keys`, restituisce i widget di una specifica scheda della dashboard (`ApplicationAnalyticsWidgetResponse`): `kyc`, `kyb`, `transactions` o `home`.\n\nI conteggi delle sessioni sono calcolati in base alla data di creazione della sessione (UTC) e riflettono lo stato corrente di ciascuna sessione. Provengono da aggregazioni giornaliere aggiornate in background, quindi l'attività più recente potrebbe richiedere qualche istante per comparire. Gli ID workflow e le versioni non validi vengono ignorati anziché rifiutati. Nessun costo viene fatturato.\n\nSolo una chiave API con accesso completo può chiamare questo endpoint: qualsiasi chiave con ambito limitato riceve `403`, indipendentemente dai permessi di cui dispone, così come la chiave di un'altra applicazione. Consulta [Chiavi API](https://docs.didit.me/it/console/api-keys).", "operationId": "get_application_analytics", "x-didit-sdk": { "resource": "analytics", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Analytics" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione.", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione. Deve essere l'applicazione a cui appartiene la chiave API: una chiave utilizzata su qualsiasi altra applicazione riceve `403`.", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-10-01" }, "description": "Primo giorno dell'intervallo, `YYYY-MM-DD`, incluso (UTC). Da inviare insieme a `end_date`: se uno dei due manca, entrambi vengono ignorati e l'intervallo copre dai 30 giorni precedenti a oggi fino a oggi." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-10-15" }, "description": "Ultimo giorno dell'intervallo, `YYYY-MM-DD`, incluso (UTC). Una data futura viene considerata come oggi. L'intervallo non può superare 730 giorni." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "home", "kyc", "kyb", "transactions" ] }, "description": "Scheda della dashboard per cui restituire i widget (senza distinzione tra maiuscole e minuscole). Omettila, insieme a `widget_keys`, per il riepilogo KYC. L'invio del solo `widget_keys` implica `kyc`. `home` accetta qualsiasi widget KYC, KYB o delle transazioni e usa come impostazione predefinita il layout della schermata iniziale salvato dell'applicazione." }, { "name": "widget_keys", "in": "query", "required": false, "schema": { "type": "string", "example": "tx_count_total,tx_count_daily" }, "description": "Chiavi dei widget separate da virgola, restituite in questo ordine. Le chiavi non accettate dall'ambito vengono scartate; se non ne rimane nessuna, vengono utilizzati i valori predefiniti dell'ambito. KYC: `kyc_sessions_volume`, `kyc_warning_insights`, `kyc_id_locations`, `kyc_ip_locations`, `kyc_workflow_funnel`, `kyc_average_verification_time`, `kyc_conversion_rate`, `kyc_conversion_by_country`, `kyc_resubmission_insights`, `kyc_original_status_distribution`, `kyc_database_validation_coverage`, `kyc_database_validation_latency`, `kyc_demographics`, `kyc_device_details`. KYB: `kyb_sessions_volume`, `kyb_workflow_funnel`, `kyb_average_verification_time`, `kyb_ip_locations`, `kyb_business_country_distribution`, `kyb_warning_insights`, `kyb_conversion_rate`, `kyb_conversion_by_country`, `kyb_industry_breakdown`, `kyb_resubmission_insights`, `kyb_original_status_distribution`, `kyb_registry_coverage`, `kyb_registry_data_completeness`, `kyb_device_details`. Transazioni: `tx_count_total`, `tx_count_daily`, `tx_volume_total_preferred_currency`, `tx_volume_daily_preferred_currency`, `tx_average_amount`, `tx_average_amount_daily`, `tx_transaction_category_breakdown`, `tx_action_type_breakdown`, `tx_status_volume_trend`, `tx_user_ip_or_country_distribution`, `tx_tag_breakdown`, `tx_top_rules_triggered`, `tx_team_member_performance`, `tx_score_histogram`." }, { "name": "workflow_ids", "in": "query", "required": false, "schema": { "type": "string", "example": "33333333-4444-5555-6666-777777777777" }, "description": "ID dei workflow separati da virgola. Limita il riepilogo KYC e i widget KYC e KYB a tali workflow. I valori che non sono UUID vengono ignorati; se nessuno è valido, il filtro viene ignorato. Il riepilogo accetta anche `workflow_id`." }, { "name": "versions", "in": "query", "required": false, "schema": { "type": "string", "example": "3,4" }, "description": "Numeri di versione dei workflow separati da virgola. Si applica solo insieme a `workflow_ids`; i valori che non sono numeri interi vengono ignorati. `version` è accettato come alias." }, { "name": "branch_path_ids", "in": "query", "required": false, "schema": { "type": "string", "example": "default" }, "description": "ID dei percorsi dei rami separati da virgole. Si applica solo insieme a `workflow_ids` e solo ai dati KYC. I dati sono attualmente registrati solo per `default` (tutti i percorsi combinati), quindi qualsiasi altro valore restituisce dati vuoti. `branch_path_id` è accettato come alias." }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Solo widget delle transazioni: UUID dei tag o nomi dei tag separati da virgole." }, { "name": "transaction_type", "in": "query", "required": false, "schema": { "type": "string", "example": "finance" }, "description": "Solo widget delle transazioni: categorie di transazione separate da virgole." }, { "name": "action_type", "in": "query", "required": false, "schema": { "type": "string", "example": "withdrawal" }, "description": "Solo widget delle transazioni: tipi di azione separati da virgole (senza distinzione tra maiuscole e minuscole)." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/analytics/?start_date=2026-10-01&end_date=2026-10-15' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.analytics.retrieve()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.analytics.retrieve();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Analytics.Retrieve(ctx, didit.AnalyticsRetrieveParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.analytics().retrieve();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "analytics->retrieve();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.analytics.retrieve\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Analytics.RetrieveAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il riepilogo KYC, oppure i widget richiesti quando viene inviato `scope` o `widget_keys`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApplicationAnalyticsSummary" }, { "$ref": "#/components/schemas/ApplicationAnalyticsWidgetResponse" } ] }, "examples": { "KYC summary": { "value": { "grouping_mode": "day", "data_points": [ { "rounded_date": "2026-10-14", "total": 12, "approved": 8, "declined": 1, "canceled": 1, "pending": 2, "in_review": 1, "expired": 1, "abandoned": 0, "in_progress": 1, "not_started": 0, "manually_approved": 1, "manually_declined": 0 }, { "rounded_date": "2026-10-15", "total": 10, "approved": 6, "declined": 2, "canceled": 0, "pending": 2, "in_review": 2, "expired": 0, "abandoned": 0, "in_progress": 0, "not_started": 0, "manually_approved": 0, "manually_declined": 1 } ], "request_breakdown": { "total_approved": 14, "total_in_review": 3, "total_declined": 3, "total_canceled": 1, "total_pending": 4, "total_expired": 1, "total_abandoned": 0, "total_in_progress": 1, "total_not_started": 0, "total_manually_approved": 1, "total_manually_declined": 1 }, "conversion_rate": 70.0, "location_stats": { "countries": [ { "session_count": 15, "country": "Spain", "country_code": "ES" }, { "session_count": 7, "country": "Portugal", "country_code": "PT" } ], "ip_countries": [ { "session_count": 15, "country": "Spain", "country_code": "ES" }, { "session_count": 7, "country": "Portugal", "country_code": "PT" } ], "id_countries": [ { "country": "Spain", "country_code": "ES", "session_count": 14 }, { "country": "Portugal", "country_code": "PT", "session_count": 6 } ], "conversion_by_country": [ { "country": "Spain", "country_code": "ES", "finished": 13, "approved": 10 }, { "country": "Portugal", "country_code": "PT", "finished": 6, "approved": 4 } ], "cities": [ { "session_count": 9, "location": "Madrid, Spain", "latitude": 40.4168, "longitude": -3.7038 } ] }, "demographic_stats": { "age_distribution": { "under_18": 0, "18_24": 5, "25_34": 8, "35_44": 4, "45_64": 2, "65_plus": 1 }, "gender_distribution": { "M": 11, "F": 9 } }, "device_details": { "device_models": [ { "device": "Apple", "count": 12 }, { "device": "Android", "count": 10 } ], "browsers": [ { "browser": "Safari", "count": 12 }, { "browser": "Chrome", "count": 10 } ], "operating_systems": [ { "os": "iOS", "count": 12 }, { "os": "Android", "count": 10 } ] }, "workflow_funnel_stats": { "33333333-4444-5555-6666-777777777777": { "total": 22, "steps": { "OCR": { "reached": 21 }, "LIVENESS": { "reached": 19 }, "FACE_MATCH": { "reached": 19 }, "AML": { "reached": 18 } } } }, "verification_time_stats": { "overall_avg_seconds": 64.0, "overall_count": 18, "per_feature": { "OCR": { "avg_seconds": 41.2, "total_seconds": 741.6, "count": 18 }, "LIVENESS": { "avg_seconds": 22.8, "total_seconds": 410.4, "count": 18 } }, "per_sub_step": { "OCR": { "front_id_photo": { "avg_seconds": 18.3, "total_seconds": 329.4, "count": 18 } } } }, "resubmission_stats": { "first_pass": 17, "second": 2, "third_plus": 1, "abandoned": 0 }, "warning_stats": { "ID_VERIFICATION": { "total": 21, "risks": { "DOCUMENT_EXPIRED": { "error": 1, "warning": 0, "information": 0 } } }, "LIVENESS": { "total": 19, "risks": { "LOW_LIVENESS_SCORE": { "error": 0, "warning": 2, "information": 0 } } } }, "original_status_stats": { "approved": 13, "in_review": 5, "declined": 2 }, "demographic_time_series": [ { "date": "2026-10-14", "age_distribution": { "under_18": 0, "18_24": 3, "25_34": 4, "35_44": 2, "45_64": 1, "65_plus": 0 }, "gender_distribution": { "M": 6, "F": 4 } }, { "date": "2026-10-15", "age_distribution": { "under_18": 0, "18_24": 2, "25_34": 4, "35_44": 2, "45_64": 1, "65_plus": 1 }, "gender_distribution": { "M": 5, "F": 5 } } ], "device_time_series": [ { "date": "2026-10-14", "devices": { "Apple": 7, "Android": 5 }, "browsers": { "Safari": 7, "Chrome": 5 }, "operating_systems": { "iOS": 7, "Android": 5 } }, { "date": "2026-10-15", "devices": { "Apple": 5, "Android": 5 }, "browsers": { "Safari": 5, "Chrome": 5 }, "operating_systems": { "iOS": 5, "Android": 5 } } ], "verification_time_time_series": [ { "date": "2026-10-14", "overall_avg": 66.1, "per_feature": { "OCR": 42.0, "LIVENESS": 24.1 } }, { "date": "2026-10-15", "overall_avg": 61.5, "per_feature": { "OCR": 40.2, "LIVENESS": 21.3 } } ], "resubmission_time_series": [ { "date": "2026-10-14", "first_pass": 9, "second": 1, "third_plus": 0, "abandoned": 0 }, { "date": "2026-10-15", "first_pass": 8, "second": 1, "third_plus": 1, "abandoned": 0 } ], "original_status_time_series": [ { "date": "2026-10-14", "approved": 7, "in_review": 3, "declined": 1 }, { "date": "2026-10-15", "approved": 6, "in_review": 2, "declined": 1 } ], "previous_data_points": [ { "rounded_date": "2026-10-12", "total": 9, "approved": 6, "declined": 1, "canceled": 1, "pending": 1 }, { "rounded_date": "2026-10-13", "total": 11, "approved": 7, "declined": 2, "canceled": 0, "pending": 2 } ], "previous_request_breakdown": { "total_approved": 13, "total_in_review": 2, "total_declined": 3, "total_canceled": 1, "total_pending": 3 } } }, "Transaction widgets": { "value": { "scope": "transactions", "available_widget_keys": [ "tx_count_total", "tx_count_daily", "tx_volume_total_preferred_currency", "tx_volume_daily_preferred_currency", "tx_average_amount", "tx_average_amount_daily", "tx_transaction_category_breakdown", "tx_action_type_breakdown", "tx_status_volume_trend", "tx_user_ip_or_country_distribution", "tx_tag_breakdown", "tx_top_rules_triggered", "tx_team_member_performance", "tx_score_histogram" ], "requested_widget_keys": [ "tx_count_total", "tx_count_daily" ], "widgets": { "tx_count_total": { "kind": "metric", "title": "Transaction count", "value": 42 }, "tx_count_daily": { "kind": "time_series", "title": "Transaction count", "items": [ { "date": "2026-10-14", "value": 20 }, { "date": "2026-10-15", "value": 22 } ], "previous_items": [ { "date": "2026-10-12", "value": 18 }, { "date": "2026-10-13", "value": 15 } ] } } } } } } } }, "400": { "description": "Intervallo di date o ambito non valido. Il corpo è un oggetto indicizzato per il parametro errato, con un messaggio di tipo stringa.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "examples": { "Bad date format": { "value": { "start_date": "Invalid date format. Use YYYY-MM-DD (e.g., 2024-01-15)." } }, "Start after end": { "value": { "start_date": "Start date must be before or equal to end date." } }, "Range too long": { "value": { "date_range": "Date range cannot exceed 730 days (2 years)." } }, "Unknown scope": { "value": { "scope": "Unsupported analytics scope." } } } } } }, "401": { "description": "La chiave API è scaduta. Solo una chiave creata con una data di scadenza può scadere; dopo tale data ogni richiesta inviata con essa risponde con `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Consulta `detail`: chiave API mancante (una chiave errata, revocata o scaduta restituisce `401`), chiave di un'altra applicazione, qualsiasi chiave con ambito o una richiesta proveniente dall'esterno dell'elenco IP della chiave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key": { "value": { "detail": "This API key has no access to this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Più di 600 richieste GET al minuto con questa chiave API. Attendi il numero di secondi indicato in `Retry-After`, quindi riprova.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi fino al ripristino della finestra temporale corrente di un minuto.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Richieste consentite al minuto per questo budget.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Ora Unix in cui la finestra si azzera.", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/analytics/today/": { "get": { "summary": "Recupera le verifiche odierne per ora", "operationId": "get_application_analytics_today", "x-didit-sdk": { "resource": "analytics", "method": "retrieve_today", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Analytics" ], "description": "Sessioni di verifica degli utenti (KYC) di oggi, a partire dalla mezzanotte locale in `tz`, conteggiate per ora locale di creazione, affiancate alle stesse ore dello stesso giorno della settimana precedente e suddivise in base all'esito attuale di ciascuna: approvata, in revisione o rifiutata. Questa è la scheda del volume nella Home della Business Console.\n\n`total` rappresenta la giornata odierna fino a questo momento. `previous_total_so_far` conteggia il giorno di confronto solo fino alla stessa ora locale, consentendo di confrontare la stessa porzione di entrambi i giorni. Le ore rimanenti della giornata odierna sono pari a `0`. Un giorno in cui cambia l'ora ha 23 o 25 ore: l'ora mancante rimane `0` e l'ora ripetuta le include entrambe.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione.", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione. Deve essere l'applicazione a cui appartiene la chiave API: una chiave utilizzata su qualsiasi altra applicazione riceve `403`.", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "tz", "in": "query", "required": false, "schema": { "type": "string", "default": "UTC", "example": "Europe/Madrid" }, "description": "Fuso orario IANA la cui mezzanotte dà inizio a oggi, ad esempio `Europe/Madrid` o `America/Mexico_City`. Omettilo per UTC." } ], "responses": { "200": { "description": "Verifiche di oggi per ora locale, quelle del giorno di confronto e gli esiti odierni.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationAnalyticsToday" }, "examples": { "Madrid, 14:00": { "value": { "time_zone": "Europe/Madrid", "date": "2026-10-30", "current_hour": 14, "previous_date": "2026-10-23", "hours": [ 3, 1, 0, 0, 1, 2, 4, 9, 14, 18, 21, 19, 22, 24, 27, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "previous_hours": [ 2, 1, 1, 0, 1, 3, 5, 8, 12, 16, 19, 18, 20, 22, 24, 26, 23, 19, 15, 12, 9, 7, 5, 3 ], "total": 165, "previous_total_so_far": 151, "outcomes": { "approved": 139, "in_review": 6, "declined": 18 } } } } } } }, "400": { "description": "Fuso orario sconosciuto. Il corpo è indicizzato per parametro, con un elenco di messaggi.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Unknown time zone": { "value": { "tz": [ "Unknown time zone: Europe/Atlantis." ] } } } } } }, "401": { "description": "La chiave API è scaduta. Solo una chiave creata con una data di scadenza può scadere; dopo tale data ogni richiesta inviata con essa risponde con `401`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. Consulta `detail`: chiave API mancante o non valida (mai `401`), chiave di un'altra applicazione, qualsiasi chiave con ambito o una richiesta proveniente dall'esterno dell'elenco IP della chiave.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key": { "value": { "detail": "This API key has no access to this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "Più di 600 richieste GET al minuto con questa chiave API. Attendi il numero di secondi indicato in `Retry-After`, quindi riprova.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi fino al ripristino della finestra temporale corrente di un minuto.", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "Richieste consentite al minuto per questo budget.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Ora Unix in cui la finestra si azzera.", "schema": { "type": "integer" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/analytics/today/?tz=Europe%2FMadrid' \\\n -H 'x-api-key: YOUR_API_KEY'" } ], "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/webhooks/": { "get": { "summary": "Elenca consegne dei webhook della sessione", "description": "Elenca ogni consegna webhook registrata da Didit per una sessione di verifica, utente (KYC) o azienda (KYB), dalla più recente, come array JSON semplice (non paginato). Ciascuna voce rappresenta un tentativo verso una destinazione: il primo invio, ogni [nuovo tentativo](https://docs.didit.me/it/integration/webhooks#politica-di-nuovo-tentativo) automatico e ogni reinvio sono voci separate con il rispettivo `uuid`, mentre i nuovi tentativi e i reinvii mantengono il valore `event_id` del payload. `request_header` e `request_body` sono in formato testo JSON; effettua il parsing per leggere le firme e il payload. I record di consegna sono disponibili per circa 30 giorni, quindi un array vuoto indica che non è stato ancora inviato alcun webhook per la sessione o che tutte le consegne sono più risalenti. Una chiave API con ambito limitato richiede `sessions: read` e `decisions: read`.", "operationId": "get_v3_session_webhooks", "x-didit-sdk": { "resource": "sessions.webhooks", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica, utente (KYC) o aziendale (KYB): il `session_id` restituito da `POST /v3/session/`. Il server lo risolve rispetto a entrambi i tipi di sessione.\n\n**Deve essere un UUID valido.** La route trova corrispondenza solo con UUID corretti, pertanto un valore non conforme viene rifiutato dal router degli URL prima dell'esecuzione del codice dell'applicazione e la risposta è una pagina **HTML** `404` anziché il wrapper JSON `{\"detail\": ...}` mostrato di seguito.", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/22222222-3333-4444-5555-666666666666/webhooks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.webhooks.list(\n \"22222222-3333-4444-5555-666666666666\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.webhooks.list(\"22222222-3333-4444-5555-666666666666\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Webhooks.List(ctx, \"22222222-3333-4444-5555-666666666666\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().webhooks().list(\"22222222-3333-4444-5555-666666666666\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->webhooks->list('22222222-3333-4444-5555-666666666666');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.webhooks.list(\"22222222-3333-4444-5555-666666666666\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Webhooks.ListAsync(\"22222222-3333-4444-5555-666666666666\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Ogni consegna registrata per la sessione, dalla più recente alla più vecchia.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionWebhookDelivery" } }, "examples": { "Failed delivery and its successful retry": { "value": [ { "uuid": "66666666-7777-8888-9999-000000000002", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"9188851d160b5b3aacfc946e4dde1f061b7e568662518942c927ddaf507f533d\", \"X-Signature-V2\": \"381236af514d3fb538579365ac5a24f2464ce1b8224c6e770c60d8201c43ecc5\", \"X-Signature-Simple\": \"4740131dc38f29e78a8508371979be74967d5307464494bd3148a03b4d6c8716\", \"X-Timestamp\": \"1792056139\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056139,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-15T09:22:19.104233Z" }, { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"a5e02a03404e1337a0198e6be15d34abbd053c658a0e51e5d0e78554213ef29b\", \"X-Signature-V2\": \"927e7cb770c94ce745939bff73f04aa200015f3bc64795ba46c2aaf78a6cedc5\", \"X-Signature-Simple\": \"e37b0d4c716c72bb5ae7127b9cc455d28ab4686e9e22312b4ec2327409a73302\", \"X-Timestamp\": \"1792056078\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056078,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-15T09:21:18.412345Z" } ] }, "No webhook sent yet": { "value": [] } } } } }, "401": { "description": "La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. L'assenza di `x-api-key`, o una chiave non valida o revocata, restituisce `Authentication credentials were not provided or are invalid.` La chiave di un'altra applicazione restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.` Un `sessionId` sconosciuto restituisce `404` prima della verifica delle credenziali.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Key of another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "value": { "detail": "This API key has no read access to sessions." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste o è stata eliminata (`Not found.`, restituito prima della verifica delle credenziali), oppure non rientra nei limiti di workflow o di stato di una chiave con ambito limitato (`Session not found.`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "value": { "detail": "Not found." } }, "Outside the key's limits": { "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite di frequenza superato: più di 600 richieste GET nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Richieste consentite nell'intervallo di un minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Ora Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome del budget superato.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/webhook/{webhook_uuid}": { "get": { "summary": "Recupera consegna del webhook della sessione", "description": "Recupera una consegna webhook di una sessione di verifica: l'URL a cui è stata inviata, lo stato HTTP restituito dal tuo endpoint e le intestazioni esatte e il corpo JSON inviati da Didit. `request_header` e `request_body` sono testo JSON; per controllare la tua [verifica della firma](https://docs.didit.me/it/integration/webhooks#verifica-della-firma), ricalcola `X-Signature-V2` dal corpo analizzato con il segreto della destinazione a cui è stata inviata (o il segreto a livello di applicazione per una consegna all'URL webhook legacy). Il percorso non ha uno slash finale: con uno slash restituisce `404`. Una chiave API con scope richiede `sessions: read` e `decisions: read`.", "operationId": "get_v3_session_webhook", "x-didit-sdk": { "resource": "sessions.webhooks", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica, utente (KYC) o aziendale (KYB): il `session_id` restituito da `POST /v3/session/`. Il server lo risolve rispetto a entrambi i tipi di sessione.\n\n**Deve essere un UUID valido.** La route trova corrispondenza solo con UUID corretti, pertanto un valore non conforme viene rifiutato dal router degli URL prima dell'esecuzione del codice dell'applicazione e la risposta è una pagina **HTML** `404` anziché il wrapper JSON `{\"detail\": ...}` mostrato di seguito.", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" }, { "name": "webhook_uuid", "in": "path", "required": true, "description": "UUID della consegna: lo `uuid` di una voce restituita da `GET /v3/session/{sessionId}/webhooks/`. Deve appartenere alla sessione indicata nel percorso.", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/22222222-3333-4444-5555-666666666666/webhook/66666666-7777-8888-9999-000000000001' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.webhooks.retrieve(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.webhooks.retrieve(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Webhooks.Retrieve(ctx, \"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().webhooks().retrieve(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->webhooks->retrieve('22222222-3333-4444-5555-666666666666', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.webhooks.retrieve(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Webhooks.RetrieveAsync(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La consegna, con le intestazioni e il corpo della richiesta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionWebhookDelivery" }, "examples": { "Connection failure": { "value": { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"a5e02a03404e1337a0198e6be15d34abbd053c658a0e51e5d0e78554213ef29b\", \"X-Signature-V2\": \"927e7cb770c94ce745939bff73f04aa200015f3bc64795ba46c2aaf78a6cedc5\", \"X-Signature-Simple\": \"e37b0d4c716c72bb5ae7127b9cc455d28ab4686e9e22312b4ec2327409a73302\", \"X-Timestamp\": \"1792056078\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056078,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-15T09:21:18.412345Z" } } } } } }, "401": { "description": "La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. L'assenza di `x-api-key`, o una chiave non valida o revocata, restituisce `Authentication credentials were not provided or are invalid.` La chiave di un'altra applicazione restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.` Un `sessionId` sconosciuto restituisce `404` prima della verifica delle credenziali.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Key of another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "value": { "detail": "This API key has no read access to sessions." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste o è stata eliminata (`Not found.`, restituito prima della verifica delle credenziali), oppure non rientra nei limiti di workflow o di stato di una chiave con ambito limitato (`Session not found.`). Una consegna che non esiste, appartiene a un'altra sessione o non è più disponibile restituisce `No WebhookLog matches the given query.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "value": { "detail": "Not found." } }, "Outside the key's limits": { "value": { "detail": "Session not found." } }, "Delivery not in this session": { "value": { "detail": "No WebhookLog matches the given query." } } } } } }, "429": { "description": "Limite di frequenza superato: più di 600 richieste GET nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Richieste consentite nell'intervallo di un minuto (600).", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Ora Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome del budget superato.", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/webhook/{webhook_uuid}/resend": { "post": { "summary": "Reinvia la consegna del webhook della sessione", "description": "Invia nuovamente un webhook di sessione registrato all'URL a cui era stato inviato inizialmente, con lo stesso payload ed `event_id` e un `timestamp`, un'intestazione `X-Timestamp` e firme aggiornati. Didit lo firma con il segreto attuale della destinazione a cui appartiene la consegna (o con il segreto a livello di applicazione per una consegna all'URL webhook legacy), attende fino a 5 secondi il tuo endpoint, registra il tentativo come una nuova consegna e lo restituisce con `200` indipendentemente dalla risposta del tuo endpoint: leggi `response_status`. Un reinvio non viene ritentato automaticamente e ogni chiamata invia nuovamente, quindi rendi il tuo endpoint idempotente su `event_id`. Il percorso non ha una barra finale e la richiesta non ha un corpo. Una chiave API con ambito limitato richiede `webhooks: write` e `decisions: read`.", "operationId": "post_v3_session_webhook_resend", "x-didit-sdk": { "resource": "sessions.webhooks", "method": "resend", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica, utente (KYC) o aziendale (KYB): il `session_id` restituito da `POST /v3/session/`. Il server lo risolve rispetto a entrambi i tipi di sessione.\n\n**Deve essere un UUID valido.** La route trova corrispondenza solo con UUID corretti, pertanto un valore non conforme viene rifiutato dal router degli URL prima dell'esecuzione del codice dell'applicazione e la risposta è una pagina **HTML** `404` anziché il wrapper JSON `{\"detail\": ...}` mostrato di seguito.", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" }, { "name": "webhook_uuid", "in": "path", "required": true, "description": "UUID della consegna da reinviare: lo `uuid` di una voce restituita da `GET /v3/session/{sessionId}/webhooks/`. Deve appartenere alla sessione indicata nel percorso.", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/session/22222222-3333-4444-5555-666666666666/webhook/66666666-7777-8888-9999-000000000001/resend' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.webhooks.resend(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.webhooks.resend(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Webhooks.Resend(ctx, \"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().webhooks().resend(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->webhooks->resend('22222222-3333-4444-5555-666666666666', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.webhooks.resend(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Webhooks.ResendAsync(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La nuova consegna, già tentata. `response_status` è la risposta del tuo endpoint in questo tentativo. La consegna originale rimane invariata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionWebhookDelivery" }, "examples": { "Accepted on resend": { "value": { "uuid": "66666666-7777-8888-9999-000000000004", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"b8eb1e376517ee0cad8ba98ff7f8fd35fc72eca231000963a96a335f82328835\", \"X-Signature-V2\": \"9efd2ce9ed1303e1d05273ef9608a59363ed9789a05253db4748b3e8e50cb109\", \"X-Signature-Simple\": \"bf3a9dc04b2c20ab539203b0cd5cca2a10f630bf62d8feb6d68d82af80f64774\", \"X-Timestamp\": \"1792159542\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792159542,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-16T14:05:42.330981Z" } } } } } }, "400": { "description": "Impossibile inviare nuovamente la consegna. Esegui una diramazione in base a `code`: `webhook_url_missing` indica che la consegna non ha un URL registrato e non viene inviato nulla; `webhook_resend_error` indica che la consegna archiviata non ha potuto essere firmata di nuovo o che il tentativo non ha potuto essere completato. Dopo `webhook_resend_error`, `detail` inizia con `Error processing webhook resend:` seguito da un testo diagnostico che può variare.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." }, "code": { "type": "string", "description": "Codice di errore stabile leggibile da macchina. Basa la logica su questo, non su `detail`." } } }, "examples": { "No recorded URL": { "value": { "detail": "The webhook delivery does not have a request URL configured", "code": "webhook_url_missing" } }, "Resend failed": { "value": { "detail": "Error processing webhook resend: Invalid webhook data format", "code": "webhook_resend_error" } } } } } }, "401": { "description": "La chiave API è scaduta: è stata creata con una data di scadenza ormai trascorsa. Anche una chiave errata o revocata riceve `401`; una chiave mancante riceve `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "La richiesta non è consentita. L'assenza di `x-api-key`, o una chiave non valida o revocata, restituisce `Authentication credentials were not provided or are invalid.` La chiave di un'altra applicazione restituisce `You do not have permission to perform this action.` Una chiave con ambito senza l'accesso richiesto da questo endpoint restituisce un messaggio che indica l'accesso mancante, mentre una chiave utilizzata al di fuori della sua allowlist IP restituisce `This API key can't be used from this IP address.` Un `sessionId` sconosciuto restituisce `404` prima della verifica delle credenziali.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Key of another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks write": { "value": { "detail": "This API key has no write access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste o è stata eliminata (`Not found.`, restituito prima della verifica delle credenziali), oppure non rientra nei limiti di workflow o di stato di una chiave con ambito limitato (`Session not found.`). Una consegna che non esiste, appartiene a un'altra sessione o non è più disponibile restituisce `Webhook log not found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "value": { "detail": "Not found." } }, "Outside the key's limits": { "value": { "detail": "Session not found." } }, "Delivery not in this session": { "value": { "detail": "Webhook log not found" } } } } } }, "429": { "description": "Limite di frequenza superato: più di 300 richieste di scrittura (POST, PATCH, PUT, DELETE) nella finestra corrente di un minuto per questa chiave API. Attendi `Retry-After` secondi prima di riprovare.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "Richieste consentite nell'intervallo di un minuto (300).", "schema": { "type": "integer", "example": 300 } }, "X-RateLimit-Remaining": { "description": "Richieste rimanenti nell'intervallo corrente.", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Ora Unix (secondi) in cui la finestra corrente si azzera.", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "Nome del budget superato.", "schema": { "type": "string", "example": "generic-write" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/events/": { "get": { "summary": "Elenca eventi della sessione", "description": "Legge la cronologia degli eventi di una sessione di verifica, dal più recente in base a `sent_at`: le schermate visualizzate dall'utente, pulsanti e caricamenti, tentativi non riusciti, variazioni di stato e dei passaggi delle funzionalità, nonché la traccia di instradamento del workflow. Funziona per gli ID di sessione di Verifica degli utenti (KYC) e Verifica aziendale (KYB). Gli eventi vengono archiviati in modo asincrono, pertanto la visualizzazione di un nuovo evento può richiedere alcuni secondi. I risultati sono impaginati con `limit` e `offset`; segui `next` finché non diventa `null`. Una chiave API con ambito limitato richiede `sessions: read` e `decisions: read` e, senza `media: read`, riceve `file_url` impostato su `null`. Gli eventi di instradamento sono descritti in [Recupera sessione](https://docs.didit.me/it/sessions-api/retrieve-session).", "operationId": "get_v3_session_events", "x-didit-sdk": { "resource": "sessions", "method": "list_events", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica (il `session_id` restituito da `POST /v3/session/`). Accetta sia ID di sessione di Verifica degli utenti (KYC) sia di Verifica aziendale (KYB): il server risolve l'ID per entrambi i tipi di sessione. Deve essere un UUID ben formato; un valore malformato non corrisponde alla route e restituisce una pagina HTML `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "limit", "in": "query", "required": false, "description": "Numero massimo di eventi per pagina. Il valore predefinito è 50. Un valore inferiore a 1 o non numerico viene reimpostato su 50; un valore superiore a 1,000,000 restituisce `400`.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000, "example": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Numero di risultati da saltare prima del primo restituito. Il valore predefinito è 0; un valore negativo o non numerico reimposta il valore a 0, un valore superiore a 1,000,000 restituisce `400`. È preferibile seguire gli URL `next` e `previous`.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000, "example": 0 } }, { "name": "ordering", "in": "query", "required": false, "description": "Criterio di ordinamento opzionale alternativo. L'ordine predefinito è `-sent_at`. Passa il nome di un campo dei risultati (ad esempio `sent_at`, `created_at`, `event_type`, `feature_step` o `step`) per ordinare in modo crescente, anteponi `-` per ordinare in modo decrescente e separa più campi con virgole. I campi sconosciuti vengono ignorati.", "schema": { "type": "string", "example": "sent_at" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/events/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.list_events(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.listEvents(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListEventsAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsListEventsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().listEvents(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->listEvents('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.list_events(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.ListEventsAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina degli eventi della sessione, dal più recente al meno recente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Numero totale di eventi della sessione." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina successiva, o `null` nell'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina precedente, o `null` nella prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SessionEvent" } } } }, "examples": { "Completed session": { "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "aaaaaaaa-1111-2222-3333-444444444444", "event_type": "SESSION_STATUS_CHANGED", "created_at": "2026-09-14T10:02:13.904512Z", "component": null, "feature_step": null, "step": null, "details": { "old_status": "In Progress", "current_status": "Approved" }, "ip_address": null, "user_agent": null, "device_info": null, "file_url": null, "sent_at": 1789380131482 }, { "uuid": "bbbbbbbb-1111-2222-3333-444444444444", "event_type": "FEATURE_STEP_CHANGED", "created_at": "2026-09-14T10:01:49.210377Z", "component": null, "feature_step": null, "step": null, "details": { "old_feature_step": "OCR", "current_feature_step": "LIVENESS" }, "ip_address": null, "user_agent": null, "device_info": null, "file_url": null, "sent_at": 1789380107103 }, { "uuid": "cccccccc-1111-2222-3333-444444444444", "event_type": "STEP_RENDERED", "created_at": "2026-09-14T10:01:00.581930Z", "component": "DocumentCapture", "feature_step": "OCR", "step": "DOCUMENT_CAPTURE_FRONT", "details": {}, "ip_address": "203.0.113.24", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1", "device_info": { "device_model": "iPhone" }, "file_url": null, "sent_at": 1789380058776 } ] } } } } } }, "400": { "description": "`limit` o `offset` è superiore a 1,000,000. Il corpo è un array JSON con un messaggio.", "content": { "application/json": { "examples": { "Limit too large": { "summary": "limit=2000000", "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "summary": "offset=2000000", "value": [ "offset must not exceed 1000000." ] } }, "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "summary": "La chiave con ambito non dispone di sessions: read", "value": { "detail": "This API key has no read access to sessions." } }, "Scoped key without decisions read": { "summary": "La chiave con ambito non dispone di decisions: read", "value": { "detail": "This API key has no read access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata o non rientra nei limiti di workflow o di sola approvazione di una chiave con ambito limitato. La ricerca della sessione viene eseguita prima della verifica delle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche senza una chiave valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID esiste, oppure è stata eliminata", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "La sessione non rientra nei limiti di workflow o di sola approvazione di una chiave con ambito limitato", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "Limite di frequenza superato: 600 richieste GET al minuto per chiave API. Attendi `Retry-After` secondi prima di riprovare; le intestazioni `X-RateLimit-*` mostrano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/aml-screening-history/": { "get": { "summary": "Elenca la cronologia dello screening AML", "description": "Elenca ogni nuovo screening completato per il monitoraggio continuo del controllo AML di una sessione, dal più recente in base a `completed_at`, comprese le esecuzioni in cui nulla è cambiato: alert, voci di attività e webhook vengono attivati solo quando un risultato cambia, pertanto questa cronologia costituisce la prova che un soggetto pulito era comunque sottoposto a screening. Funziona sia per ID di sessione KYC che KYB; passa `node_id` quando la sessione ha eseguito più di un passaggio AML. Vengono elencati solo i nuovi screening di monitoraggio continuo (il primo screening fa parte della decisione della sessione) e le esecuzioni precedenti all'introduzione di questa cronologia non vengono ricostruite, per cui una sessione senza monitoraggio continuo restituisce un elenco vuoto. `count` è esatto fino a 100 e limitato a 100 al di sopra di tale soglia, quindi segui `next` finché non diventa `null`. Passa `month` per leggere un mese di calendario alla volta. Una chiave API con ambito limitato richiede `decisions: read`; vedi [Monitoraggio AML continuo](https://docs.didit.me/it/core-technology/aml-screening/continuous-monitoring-aml-screening).", "operationId": "get_v3_session_aml_screening_history", "x-didit-sdk": { "resource": "sessions", "method": "list_aml_screening_history", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica (il `session_id` restituito da `POST /v3/session/`). Accetta sia ID di sessione di Verifica degli utenti (KYC) sia di Verifica aziendale (KYB): il server risolve l'ID per entrambi i tipi di sessione. Deve essere un UUID ben formato; un valore malformato non corrisponde alla route e restituisce una pagina HTML `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "ID del nodo del grafo del workflow relativo al controllo AML. Necessario solo se la sessione ha eseguito più di un passaggio AML; in sua assenza viene utilizzato il controllo AML più recente. Un nodo sconosciuto restituisce `404`.", "schema": { "type": "string", "example": "feature_aml_1" } }, { "name": "month", "in": "query", "required": false, "description": "Un mese di calendario UTC nel formato `YYYY-MM`. Vengono restituiti solo gli screening completati in quel mese; senza di esso vengono restituiti i dati di ogni mese. Un mese con formato errato restituisce `400`.", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } }, { "name": "limit", "in": "query", "required": false, "description": "Numero massimo di esecuzioni di screening per pagina. Il valore predefinito è 50. Un valore inferiore a 1 o non numerico viene reimpostato su 50; un valore superiore a 1,000,000 restituisce `400`.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000, "example": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Numero di risultati da saltare prima del primo restituito. Il valore predefinito è 0; un valore negativo o non numerico reimposta il valore a 0, un valore superiore a 1,000,000 restituisce `400`. È preferibile seguire gli URL `next` e `previous`.", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000, "example": 0 } }, { "name": "ordering", "in": "query", "required": false, "description": "Criterio di ordinamento opzionale alternativo. L'ordine predefinito è `-completed_at`. Passa il nome di un campo dei risultati (ad esempio `completed_at`, `started_at`, `outcome` o `score`) per ordinare in modo crescente, anteponi `-` per ordinare in modo decrescente e separa più campi con virgole. I campi sconosciuti vengono ignorati.", "schema": { "type": "string", "example": "completed_at" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/aml-screening-history/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.list_aml_screening_history(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.listAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListAMLScreeningHistoryAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsListAMLScreeningHistoryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().listAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->listAmlScreeningHistory('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.list_aml_screening_history(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.ListAmlScreeningHistoryAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina di esecuzioni di screening, dalla più recente alla meno recente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "maximum": 100, "description": "Numero di esecuzioni, esatto fino a 100 e limitato a 100 al di sopra." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina successiva, o `null` nell'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina precedente, o `null` nella prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AMLScreeningRun" } } } }, "examples": { "Monitored subject": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "dddddddd-1111-2222-3333-444444444444", "run_id": "aaaaaaaa-1111-2222-3333-444444444444", "completed_at": "2026-09-14T04:12:33.481207Z", "started_at": "2026-09-14T04:00:01.002311Z", "outcome": "NO_CHANGE", "trigger": "ONGOING_MONITORING", "provider": "aml_data_source", "status": "Approved", "score": 0.0, "total_hits": 0, "new_hits": 0, "entities_screened": 1, "dataset_freshness": { "captured_at": "2026-09-14T03:58:02.114820+00:00", "provider": "aml_data_source", "catalog_version": "2026-09-13", "sources": { "sanctions": { "last_updated_at": "2026-09-13T21:10:00+00:00", "oldest_updated_at": "2026-09-11T06:00:00+00:00", "dataset_count": 120, "dated_dataset_count": 120 }, "pep": { "last_updated_at": "2026-09-13T08:00:00+00:00", "oldest_updated_at": null, "dataset_count": 45, "dated_dataset_count": 44 }, "warnings": { "last_updated_at": "2026-09-12T18:45:00+00:00", "oldest_updated_at": "2026-09-01T00:00:00+00:00", "dataset_count": 30, "dated_dataset_count": 30 } } } }, { "uuid": "eeeeeeee-1111-2222-3333-444444444444", "run_id": "bbbbbbbb-1111-2222-3333-444444444444", "completed_at": "2026-09-13T04:11:58.020914Z", "started_at": "2026-09-13T04:00:00.871022Z", "outcome": "FAILED", "trigger": "ONGOING_MONITORING", "provider": "aml_data_source", "status": "Approved", "score": 0.0, "total_hits": 0, "new_hits": null, "entities_screened": 0, "dataset_freshness": null } ] } } } } } }, "400": { "description": "`limit` o `offset` è superiore a 1,000,000 (un array JSON con un messaggio), oppure `month` non è un mese di calendario `YYYY-MM` (un oggetto con chiave `month`).", "content": { "application/json": { "examples": { "Limit too large": { "summary": "limit=2000000", "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "summary": "offset=2000000", "value": [ "offset must not exceed 1000000." ] }, "Malformed month": { "summary": "month=2026-13", "value": { "month": [ "Not a calendar month. Use YYYY-MM." ] } } }, "schema": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "month": { "type": "array", "items": { "type": "string" } } } } ] } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions read": { "summary": "La chiave con ambito non dispone di decisions: read", "value": { "detail": "This API key has no read access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata o non rientra nei limiti di una chiave con ambito limitato, oppure non presenta alcun controllo AML (per il `node_id` specificato). La ricerca della sessione viene eseguita prima della verifica delle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche senza una chiave valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID esiste, oppure è stata eliminata", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "La sessione non rientra nei limiti di una chiave con ambito limitato (restituito anche per una sessione eliminata pochi istanti prima)", "value": { "detail": "Session not found." } }, "No AML check": { "summary": "La sessione non ha mai eseguito un passaggio AML", "value": { "detail": "The session does not have an AML check." } }, "No AML check for node": { "summary": "node_id non corrisponde a un controllo AML della sessione", "value": { "detail": "The session does not have an AML check for node 'feature_aml_2'." } } } } } }, "429": { "description": "Limite di frequenza superato: 600 richieste GET al minuto per chiave API. Attendi `Retry-After` secondi prima di riprovare; le intestazioni `X-RateLimit-*` mostrano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/aml-screening-history/export/": { "get": { "summary": "Esportare la cronologia dello screening AML in formato CSV", "description": "Scarica la stessa cronologia del monitoraggio continuo di `GET /v3/session/{sessionId}/aml-screening-history/` come file CSV, una riga per ogni nuovo screening completato, dalla più recente alla più vecchia, pronta da consegnare a un auditor. Il file viene trasmesso per intero (senza paginazione) e inizia con una riga di intestazione; una cella vuota indica un valore sconosciuto, le date dei dataset non vengono mai stimate e un valore che inizierebbe una formula di foglio di calcolo è preceduto da un apostrofo. Funziona per ID sessione KYC e KYB; passa `node_id` quando la sessione ha eseguito più di un passaggio AML. Passa `month` per esportare un mese di calendario. Gli errori vengono restituiti in formato JSON, non CSV. Una chiave API con ambito limitato richiede `decisions: read` e `media: read`: la risposta è un file, quindi una chiave senza `media: read` riceve `403`.", "operationId": "get_v3_session_aml_screening_history_export", "x-didit-sdk": { "resource": "sessions", "method": "export_aml_screening_history", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica (il `session_id` restituito da `POST /v3/session/`). Accetta sia ID di sessione di Verifica degli utenti (KYC) sia di Verifica aziendale (KYB): il server risolve l'ID per entrambi i tipi di sessione. Deve essere un UUID ben formato; un valore malformato non corrisponde alla route e restituisce una pagina HTML `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "ID del nodo del grafo del workflow relativo al controllo AML. Necessario solo se la sessione ha eseguito più di un passaggio AML; in sua assenza viene utilizzato il controllo AML più recente. Un nodo sconosciuto restituisce `404`.", "schema": { "type": "string", "example": "feature_aml_1" } }, { "name": "month", "in": "query", "required": false, "description": "Un mese di calendario UTC nel formato `YYYY-MM`. Vengono restituiti solo gli screening completati in quel mese; senza di esso vengono restituiti i dati di ogni mese. Un mese con formato errato restituisce `400`.", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/aml-screening-history/export/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -o aml-screening-history.csv" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.export_aml_screening_history(\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.csv\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.exportAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\");\nawait writeFile(\"download.csv\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.ExportAMLScreeningHistory(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsExportAMLScreeningHistoryParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.csv\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().exportAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.csv\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->exportAmlScreeningHistory('11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.csv');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.export_aml_screening_history(\"11111111-2222-3333-4444-555555555555\")\nFile.binwrite(\"download.csv\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.ExportAmlScreeningHistoryAsync(\"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.csv\");" } ], "responses": { "200": { "description": "Il file CSV, trasmesso in streaming come `text/csv` con interruzioni di riga CRLF. Colonne, nell'ordine: `screened_at` (quando è terminato il nuovo screening), `outcome` (`NO_CHANGE`, `CHANGED` o `FAILED`), `provider` (identificatore opaco della fonte dati AML; non basare logica condizionale su di esso), `aml_status`, `aml_score`, `total_hits`, `datasets_captured_at`, `datasets_sanctions_last_updated_at`, `datasets_pep_last_updated_at`, `datasets_warnings_last_updated_at`, `datasets_adverse_media_last_updated_at`, `datasets_catalog_version`, `run_id` (l'esecuzione del monitoraggio), `entities_screened` (`1`, o `0` per un'esecuzione non riuscita) e `new_hits` (vuoto se sconosciuto). Le date sono in formato ISO 8601 con offset UTC. Una sessione che non ha ancora nuovi screening restituisce solo la riga di intestazione.", "headers": { "Content-Disposition": { "description": "`attachment; filename=\"aml-screening-history-{sessionId}.csv\"`, oppure `aml-screening-history-{sessionId}-{month}.csv` quando viene passato `month`.", "schema": { "type": "string", "example": "attachment; filename=\"aml-screening-history-11111111-2222-3333-4444-555555555555.csv\"" } } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" }, "example": "screened_at,outcome,provider,aml_status,aml_score,total_hits,datasets_captured_at,datasets_sanctions_last_updated_at,datasets_pep_last_updated_at,datasets_warnings_last_updated_at,datasets_adverse_media_last_updated_at,datasets_catalog_version,run_id,entities_screened,new_hits\r\n2026-09-14T04:12:33.481207+00:00,NO_CHANGE,aml_data_source,Approved,0.0,0,2026-09-14T03:58:02.114820+00:00,2026-09-13T21:10:00+00:00,2026-09-13T08:00:00+00:00,2026-09-12T18:45:00+00:00,,2026-09-13,aaaaaaaa-1111-2222-3333-444444444444,1,0\r\n2026-09-13T04:11:58.020914+00:00,FAILED,aml_data_source,Approved,0.0,0,,,,,,,bbbbbbbb-1111-2222-3333-444444444444,0,\r\n" } } }, "400": { "description": "`month` non è un mese di calendario `YYYY-MM`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "array", "items": { "type": "string" } } } }, "examples": { "Malformed month": { "summary": "month=2026-13", "value": { "month": [ "Not a calendar month. Use YYYY-MM." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions read": { "summary": "La chiave con ambito non dispone di decisions: read", "value": { "detail": "This API key has no read access to decisions." } }, "Scoped key without media read": { "summary": "La chiave con ambito non dispone di media: read (la risposta è un file)", "value": { "detail": "This API key has no read access to media." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata o non rientra nei limiti di una chiave con ambito limitato, oppure non presenta alcun controllo AML (per il `node_id` specificato). La ricerca della sessione viene eseguita prima della verifica delle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche senza una chiave valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID esiste, oppure è stata eliminata", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "La sessione non rientra nei limiti di una chiave con ambito limitato (restituito anche per una sessione eliminata pochi istanti prima)", "value": { "detail": "Session not found." } }, "No AML check": { "summary": "La sessione non ha mai eseguito un passaggio AML", "value": { "detail": "The session does not have an AML check." } }, "No AML check for node": { "summary": "node_id non corrisponde a un controllo AML della sessione", "value": { "detail": "The session does not have an AML check for node 'feature_aml_2'." } } } } } }, "429": { "description": "Limite di frequenza superato: 600 richieste GET al minuto per chiave API. Attendi `Retry-After` secondi prima di riprovare; le intestazioni `X-RateLimit-*` mostrano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/add-images/": { "patch": { "summary": "Aggiungi un'immagine a una sessione", "description": "Allega un'immagine o un PDF aggiuntivo al risultato della verifica dell'identità (`model_type=kyc`) o della Prova di residenza (`model_type=poa`) di una sessione di Verifica degli utenti (KYC) conclusa, ad esempio prove raccolte al di fuori del workflow. La sessione deve essere `Approved`, `Declined`, `In Review` o `Kyc Expired` e includere il risultato indicato da `model_type`; le sessioni di Verifica aziendale (KYB) non sono supportate. Ogni chiamata aggiunge un file (al risultato più recente quando il passaggio è stato eseguito più di una volta), mantiene i file esistenti e registra una voce `FILE_ADDED` nel registro di attività della sessione; il caricamento non invia webhook e non modifica lo stato della sessione. Il file viene compresso durante il caricamento e viene restituito in `extra_files` della decisione della sessione. Questo endpoint è limitato a 10 richieste al minuto per chiave API. Una chiave API con ambito limitato richiede `sessions: write`, e senza `media: read` riceve i link di `extra_files` come `null`.", "operationId": "patch_v3_session_add_images", "x-didit-sdk": { "resource": "sessions", "method": "add_images", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica degli utenti (KYC) a cui aggiungere il file (il `session_id` restituito da `POST /v3/session/`). L'ID di una sessione di Verifica aziendale (KYB) restituisce `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "model_type" ], "properties": { "file": { "type": "string", "format": "binary", "description": "L'immagine o il PDF. Estensioni consentite: `jpg`, `jpeg`, `png`, `webp`, `tiff`, `pdf`. Al massimo 15 MB al caricamento; il file viene poi compresso e rifiutato con `400` se supera ancora i 2 MB (2.097.152 byte). I file vuoti vengono rifiutati." }, "model_type": { "type": "string", "enum": [ "kyc", "poa" ], "description": "`kyc` aggiunge il file al risultato della verifica dell'identità, `poa` al risultato della prova di residenza.", "example": "kyc" }, "file_password": { "type": "string", "description": "Password di un PDF crittografato. Senza di essa, o con una password errata, un PDF crittografato restituisce `400`." } } }, "example": { "file": "(binary)", "model_type": "kyc" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'file=@./back-of-id.jpg' \\\n -F 'model_type=kyc'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.add_images(\n \"11111111-2222-3333-4444-555555555555\",\n file=open(\"image.jpg\", \"rb\"),\n model_type=\"kyc\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.addImages(\"11111111-2222-3333-4444-555555555555\", {\n file: await fileFromPath(\"image.jpg\"),\n model_type: \"kyc\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.AddImages(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsAddImagesParams{\n\tFile: didit.FileFromPath(\"image.jpg\"),\n\tModelType: \"kyc\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.SessionsAddImagesParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().addImages(\"11111111-2222-3333-4444-555555555555\", SessionsAddImagesParams.builder()\n .file(Path.of(\"image.jpg\"))\n .modelType(SessionsAddImagesParams.ModelType.of(\"kyc\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->addImages('11111111-2222-3333-4444-555555555555', [\n 'file' => File::fromPath('image.jpg'),\n 'model_type' => 'kyc',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.add_images(\n \"11111111-2222-3333-4444-555555555555\",\n file: Pathname(\"image.jpg\"),\n model_type: \"kyc\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.AddImagesAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsAddImagesParams\n{\n File = FileUpload.FromPath(\"image.jpg\"),\n ModelType = \"kyc\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "File aggiunto. Restituisce tutti i file aggiuntivi di quel risultato, compreso quello nuovo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "extra_files" ], "properties": { "extra_files": { "type": "array", "description": "Link pre-firmati di breve durata a tutti i file extra del risultato indicato da `model_type`, dal più vecchio al più recente. Ciascun link è `null` per una chiave API con ambito limitato senza `media: read`. Leggi nuovi link in seguito dalla decisione della sessione.", "items": { "type": "string", "format": "uri", "nullable": true } } } }, "example": { "extra_files": [ "https://media.example.com/session/11111111-2222-3333-4444-555555555555/kyc-extra-files/66666666-7777-8888-9999-000000000000.jpg?expires=1789383731&signature=abc123" ] } } } }, "400": { "description": "Errore di validazione. Gli errori di campo arrivano come `{\"\": [\"\"]}`; gli errori per PDF crittografato come `{\"detail\": \"...\"}`.", "content": { "application/json": { "examples": { "Missing file": { "summary": "Nessuna parte di file nel modulo", "value": { "file": [ "No file was submitted." ] } }, "Missing model_type": { "summary": "model_type omesso", "value": { "model_type": [ "This field is required." ] } }, "Invalid model_type": { "summary": "model_type non è kyc o poa", "value": { "model_type": [ "\"passport\" is not a valid choice." ] } }, "File too large": { "summary": "Caricamento superiore a 15 MB", "value": { "file": [ "File size should not exceed 15 MB" ] } }, "Too large after compression": { "summary": "Ancora superiore a 2 MB dopo la compressione", "value": { "file": [ "File size is too big. Max allowed size is 2097152 bytes." ] } }, "Encrypted PDF": { "summary": "PDF crittografato senza file_password", "value": { "detail": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Wrong PDF password": { "summary": "file_password non apre il PDF", "value": { "detail": "The PDF password is incorrect. Please provide the correct password." } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions write": { "summary": "La chiave con ambito non dispone di sessions: write", "value": { "detail": "This API key has no write access to sessions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata o non rientra nei limiti di una chiave con ambito limitato; è una sessione KYB o non è in stato `Approved`, `Declined`, `In Review` o `Kyc Expired`; oppure non ha alcun risultato per il `model_type` richiesto (verificato prima della convalida del file). La ricerca della sessione viene eseguita prima della verifica delle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche senza una chiave valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID esiste, oppure è stata eliminata", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "La sessione non rientra nei limiti di workflow o di sola approvazione di una chiave con ambito limitato", "value": { "detail": "Session not found." } }, "Not eligible": { "summary": "Sessione non ancora terminata, oppure un ID di sessione KYB", "value": { "detail": "No Session matches the given query." } }, "No ID verification": { "summary": "model_type=kyc su una sessione senza verifica dell'identità", "value": { "detail": "The session does not have KYC data." } }, "No Proof of Address": { "summary": "model_type=poa su una sessione senza prova di residenza", "value": { "detail": "The session does not have POA data." } } } } } }, "429": { "description": "Limite di frequenza superato: 10 richieste di aggiunta di immagini al minuto per chiave API (vengono conteggiate anche le richieste respinte). Si applica inoltre il budget condiviso di 300 richieste di scrittura al minuto. Attendi i secondi indicati in `Retry-After` prima di riprovare; le intestazioni `X-RateLimit-*` indicano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "Session add-images rate limit exceeded. You can make up to 10 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/update-aml-status/": { "patch": { "summary": "Aggiorna lo stato di un controllo AML", "description": "Imposta lo stato del controllo di Screening AML di una sessione nel suo complesso (lo `status` di una voce `aml_screenings[]` nella decisione della sessione), ad esempio `Approved` dopo che il tuo team ha autorizzato ogni hit. Funziona per gli ID sessione KYC e KYB; passa `node_id` (parametro di query o campo del body) quando la sessione ha eseguito più di un passaggio AML, altrimenti viene aggiornato il controllo AML più recente. Quando lo stato cambia effettivamente, viene registrata una voce di attività `AML_STATUS_UPDATED` e viene inviato un [webhook](https://docs.didit.me/it/integration/webhooks) `data.updated`; l'invio dello stato attuale restituisce `200` e non modifica nulla. Lo stato della sessione non viene ricalcolato: usa `PATCH /v3/session/{sessionId}/update-status/` per la decisione della sessione e `PATCH /v3/session/{sessionId}/update-aml-hit-status/` per singoli hit. Una chiave API con ambito limitato richiede `decisions: write`.", "operationId": "patch_v3_session_update_aml_status", "x-didit-sdk": { "resource": "sessions", "method": "update_aml_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica (il `session_id` restituito da `POST /v3/session/`). Accetta sia ID di sessione di Verifica degli utenti (KYC) sia di Verifica aziendale (KYB): il server risolve l'ID per entrambi i tipi di sessione. Deve essere un UUID ben formato; un valore malformato non corrisponde alla route e restituisce una pagina HTML `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "ID del nodo del grafo del workflow relativo al controllo AML da aggiornare. Necessario solo se la sessione ha eseguito più di un passaggio AML. Ha la precedenza rispetto a `node_id` nel corpo.", "schema": { "type": "string", "example": "feature_aml_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Nuovo stato del controllo AML.", "example": "Approved" }, "node_id": { "type": "string", "description": "ID del nodo del grafo del workflow relativo al controllo AML, in alternativa al parametro di query.", "example": "feature_aml_1" } } }, "example": { "status": "Approved" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-aml-status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"status\": \"Approved\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_aml_status(\n \"11111111-2222-3333-4444-555555555555\",\n status=\"Approved\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateAmlStatus(\"11111111-2222-3333-4444-555555555555\", {\n status: \"Approved\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateAMLStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateAMLStatusParams{\n\tStatus: \"Approved\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateAmlStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateAmlStatus(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateAmlStatusParams.builder()\n .status(SessionsUpdateAmlStatusParams.Status.of(\"Approved\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateAmlStatus('11111111-2222-3333-4444-555555555555', [\n 'status' => 'Approved',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_aml_status(\n \"11111111-2222-3333-4444-555555555555\",\n status: \"Approved\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateAmlStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateAmlStatusParams\n{\n Status = \"Approved\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Stato del controllo AML impostato (o invariato se aveva già questo valore).", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "status", "previous_status" ], "properties": { "message": { "type": "string", "description": "Sempre `AML status updated successfully`." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato del controllo AML attuale." }, "previous_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato prima della chiamata. Uguale a `status` se nulla è cambiato." } } }, "example": { "message": "AML status updated successfully", "status": "Approved", "previous_status": "In Review" } } } }, "400": { "description": "Errore di validazione: `status` mancante o non compreso tra i valori consentiti. La ricerca del controllo AML viene eseguita per prima, quindi una sessione senza un controllo AML restituisce `404` anche con un corpo non valido.", "content": { "application/json": { "examples": { "Missing status": { "summary": "Corpo vuoto o nessuno stato", "value": { "status": [ "This field is required." ] } }, "Invalid status": { "summary": "status non è presente nell'enum", "value": { "status": [ "\"Cleared\" is not a valid choice." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata o non rientra nei limiti di una chiave con ambito limitato, oppure non presenta alcun controllo AML (per il `node_id` specificato). La ricerca della sessione viene eseguita prima della verifica delle credenziali, quindi un `sessionId` sconosciuto restituisce `404` anche senza una chiave valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Unknown session": { "summary": "Nessuna sessione con questo ID esiste, oppure è stata eliminata", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "La sessione non rientra nei limiti di una chiave con ambito limitato (restituito anche per una sessione eliminata pochi istanti prima)", "value": { "detail": "Session not found." } }, "No AML check": { "summary": "La sessione non ha mai eseguito un passaggio AML", "value": { "detail": "The session does not have an AML check." } }, "No AML check for node": { "summary": "node_id non corrisponde a un controllo AML della sessione", "value": { "detail": "The session does not have an AML check for node 'feature_aml_2'." } } } } } }, "429": { "description": "Limite di frequenza superato: 300 richieste di scrittura (POST, PATCH, DELETE) al minuto per chiave API. Attendi i secondi indicati in `Retry-After` prima di riprovare; le intestazioni `X-RateLimit-*` indicano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/status/": { "get": { "summary": "Recupera stato del servizio (pubblico, non autenticato)", "description": "Restituisce lo stato di ciascun servizio Didit (`operational`, `degraded` o `down`), lo stato complessivo (il peggiore tra essi) e gli incidenti in corso o risolti negli ultimi 7 giorni. Usalo per alimentare un widget di stato o per verificare lo stato di Didit dalla tua integrazione.\n\nPubblico: non inviare alcuna intestazione di autenticazione. La risposta non contiene dati dell'organizzazione ed è identica per ogni chiamante. Le risposte vengono memorizzate nella cache per 30 secondi, quindi non effettuare il polling più di una volta ogni 30 secondi.", "operationId": "get_v3_status", "tags": [ "Status" ], "security": [ {} ], "parameters": [], "responses": { "200": { "description": "Stato attuale del servizio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceStatusFeed" }, "examples": { "One service degraded": { "summary": "Un incidente in corso e uno risolto questa settimana", "value": { "status": "degraded", "updated_at": "2026-10-13T09:41:07.512345Z", "services": [ { "key": "service_id_verification", "name": "ID verification", "status": "operational" }, { "key": "service_liveness_face_match", "name": "Liveness and face match", "status": "operational" }, { "key": "service_aml_screening", "name": "AML screening", "status": "operational" }, { "key": "service_kyb_registries", "name": "KYB registries", "status": "operational" }, { "key": "service_database_validation", "name": "Database validation", "status": "degraded" }, { "key": "service_phone_delivery", "name": "Phone verification delivery", "status": "operational" }, { "key": "service_email_delivery", "name": "Email verification delivery", "status": "operational" }, { "key": "service_transaction_monitoring", "name": "Transaction monitoring", "status": "operational" } ], "incidents": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "service": "service_database_validation", "service_name": "Database validation", "state": "degraded", "status": "ongoing", "title": "Database validation is degraded in Brazil.", "body": "Checks against Brazil (CPF) may be slow or fail since 08:55 UTC.", "affected": "Brazil (CPF)", "country_name": "Brazil", "started_at": "2026-10-13T08:55:00Z", "resolved_at": null, "duration_minutes": null }, { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "service": "service_aml_screening", "service_name": "AML screening", "state": "down", "status": "resolved", "title": "AML screening is back to normal.", "body": "Recovered at 14:32 UTC after 17 minutes.", "affected": "", "country_name": "", "started_at": "2026-10-11T14:15:00Z", "resolved_at": "2026-10-11T14:32:00Z", "duration_minutes": 17 } ] } }, "All operational": { "summary": "Nessun incidente negli ultimi 7 giorni", "value": { "status": "operational", "updated_at": "2026-10-13T09:41:07.512345Z", "services": [ { "key": "service_id_verification", "name": "ID verification", "status": "operational" }, { "key": "service_liveness_face_match", "name": "Liveness and face match", "status": "operational" }, { "key": "service_aml_screening", "name": "AML screening", "status": "operational" }, { "key": "service_kyb_registries", "name": "KYB registries", "status": "operational" }, { "key": "service_database_validation", "name": "Database validation", "status": "operational" }, { "key": "service_phone_delivery", "name": "Phone verification delivery", "status": "operational" }, { "key": "service_email_delivery", "name": "Email verification delivery", "status": "operational" }, { "key": "service_transaction_monitoring", "name": "Transaction monitoring", "status": "operational" } ], "incidents": [] } } } } } }, "429": { "description": "Più di 600 richieste GET in un minuto dallo stesso indirizzo IP (o dalla stessa chiave API, se ne invii una). Rispetta `Retry-After` prima di riprovare.", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string" } } }, "example": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -fsS https://verification.didit.me/v3/status/" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresp = requests.get('https://verification.didit.me/v3/status/', timeout=5)\nresp.raise_for_status()\nfeed = resp.json()\nprint(feed['status'])\nfor service in feed['services']:\n if service['status'] != 'operational':\n print(service['key'], service['status'])" }, { "lang": "javascript", "label": "JavaScript", "source": "const feed = await fetch('https://verification.didit.me/v3/status/').then((r) => r.json());\nconsole.log(feed.status);\nconst affected = feed.services.filter((s) => s.status !== 'operational');\nconsole.log(affected.map((s) => `${s.key}: ${s.status}`));" } ], "x-didit-sdk": { "resource": "system", "method": "retrieve_status", "auth": "public", "server": false } } }, "/v3/organization/bank-verification-pricing/": { "get": { "summary": "Recupera i prezzi per la verifica bancaria (pubblico, non autenticato)", "description": "Restituisce il prezzo di listino di ciascun metodo di Bank Verification in ogni paese: accesso bancario con i relativi add-on di saldo e transazioni, e verifica del conto. Un metodo non attualmente offerto in un paese viene mostrato come non disponibile, senza alcun prezzo. Usalo per calcolare il preventivo di un passaggio bancario prima di creare un workflow, oppure per mostrare i prezzi bancari direttamente nel tuo prodotto.\n\nPubblico: non inviare alcuna intestazione di autenticazione. La risposta non contiene dati dell'organizzazione ed è identica per ogni chiamante. Viene memorizzata nella cache pubblica per un'ora ed è provvista di un `ETag`, quindi invia `If-None-Match` per ricevere un `304 Not Modified` qualora non vi siano modifiche.\n\nUn metodo risulta `available` solo dove Didit lo offre oggi in produzione, e il suo `price_usd` è `null` ovunque altrove, in modo che il feed non mostri mai un prezzo che non puoi acquistare. `available: false` include un paese senza un prezzo approvato, un metodo non supportato dal paese e un percorso non ancora attivato.\n\nQuesti sono prezzi di listino al lordo dello sconto del tuo piano. Lo sconto del tuo piano si applica all'intero prezzo bancario, e un prezzo negoziato o contrattuale sostituisce il prezzo di listino per la tua organizzazione.", "operationId": "get_v3_bank_verification_pricing", "tags": [ "Pricing" ], "security": [ {} ], "parameters": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -fsS https://verification.didit.me/v3/organization/bank-verification-pricing/" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# This call needs no API key.\nclient = Didit()\n\nresult = client.pricing.bank_verification()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// This call needs no API key.\nconst didit = new Didit();\n\nconst result = await didit.pricing.bankVerification();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// This call needs no API key.\nclient := didit.NewClient()\n\nresult, err := client.Pricing.BankVerification(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// This call needs no API key.\nDidit client = new Didit();\n\nvar result = client.pricing().bankVerification();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "pricing->bankVerification();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# This call needs no API key.\ndidit = Didit::Client.new\n\nresult = didit.pricing.bank_verification\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// This call needs no API key.\nusing var client = new DiditClient();\n\nvar result = await client.Pricing.BankVerificationAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "pricing", "method": "bank_verification", "auth": "none", "server": true }, "responses": { "200": { "description": "Prezzi di listino della verifica bancaria per paese.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankVerificationPricing" }, "examples": { "Two countries": { "summary": "Un paese con entrambi i metodi, uno con nessuno dei due", "value": { "currency": "USD", "statement_upload": { "price_usd": "0.0000", "included_after_charged_bank_attempt": true, "standalone_available": false }, "own_provider_fee_usd": "0.0200", "countries": { "GBR": { "name": "United Kingdom", "methods": { "open_banking": { "available": true, "market": "UK and EEA", "price_usd": "0.7900", "add_ons": { "balance": "0.3500", "transactions": "1.3000" } }, "account_lookup": { "available": true, "price_usd": "0.4000" } } }, "CAN": { "name": "Canada", "methods": { "open_banking": { "available": false, "market": null, "price_usd": null, "add_ons": {} }, "account_lookup": { "available": false, "price_usd": null } } } } } } } } } }, "304": { "description": "Non modificato: l'`ETag` inviato in `If-None-Match` corrisponde ancora. Nessun corpo." } } } }, "/v3/session/{sessionId}/simulate/": { "post": { "summary": "Simula lo stato di una sessione sandbox", "description": "Forza uno stato finale su una sessione sandbox a posteriori, dal tuo backend, senza eseguire il flusso. Solo applicazioni sandbox: una sessione di produzione restituisce `404`. Funziona per le sessioni di Verifica degli utenti (KYC) e Verifica aziendale (KYB).\n\nImposta `new_status` o lascia che sia `scenario` o `risk` a fornirlo. `risk` (o il primo rischio associato ai valori magici dello scenario) aggiunge quell'avviso alla sessione. La modifica viene registrata nell'attività della sessione.\n\n`send_webhooks` (valore predefinito `true`) invia esattamente gli stessi webhook inviati da un reale cambio di stato. Con `false` lo stato cambia comunque e la console continua ad aggiornarsi in tempo reale, ma nessun webhook viene registrato o inviato, il recupero dei webhook persi non invierà mai nuovamente quella decisione e il successivo cambio di stato invierà i webhook come di consueto. La risposta restituisce il valore applicato.\n\nRichiede il privilegio `write:sessions`; una chiave API con ambito limitato necessita dell'accesso in scrittura alle sessioni. Un `session_id` sconosciuto restituisce `404` e la sessione di un'altra applicazione restituisce `403`, in entrambi i casi prima che il corpo della richiesta venga letto; una sessione di produzione restituisce `404` solo dopo che il corpo della richiesta è stato validato. Per simulare dal flusso ospitato con il token della sessione stessa, usa `POST /v3/session/{sessionId}/sandbox/simulate/`. Consulta [Sandbox e dati di test](/it/integration/sandbox-testing) per il catalogo degli scenari.", "operationId": "post_v3_session_simulate", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica sandbox. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateRequest" }, "examples": { "Scenario Without Webhooks": { "summary": "Rifiuta tramite uno scenario senza inviare webhook", "value": { "scenario": "decline_aml_hit", "send_webhooks": false } }, "Status Only": { "summary": "Approva e invia i normali webhook", "value": { "new_status": "Approved" } } } } } }, "responses": { "200": { "description": "Lo stato è cambiato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateResponse" }, "examples": { "Simulated": { "summary": "Rifiutata tramite uno scenario, webhook non inviati", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "previous_status": "In Progress", "status": "Declined", "scenario": "decline_aml_hit", "risk": "POSSIBLE_MATCH_FOUND", "send_webhooks": false } } } } } }, "400": { "description": "Errore di validazione: uno scenario o un rischio sconosciuto, nessun `new_status` quando né `scenario` né `risk` ne forniscono uno, uno stato non impostato da questo endpoint, oppure la sessione ha già lo stato richiesto (un array JSON semplice).", "content": { "application/json": { "examples": { "Unknown Scenario": { "summary": "lo scenario non è presente nel catalogo", "value": { "scenario": [ "Unknown sandbox scenario: 'not-a-scenario'." ] } }, "Unknown Risk": { "summary": "risk non è presente nel catalogo", "value": { "risk": [ "Unknown sandbox risk case: 'NOT_A_RISK'." ] } }, "Missing new_status": { "summary": "Nessun new_status, scenario o rischio", "value": { "new_status": [ "This field is required." ] } }, "Invalid new_status": { "summary": "Uno stato che la simulazione non imposta", "value": { "new_status": [ "\"Resubmitted\" is not a valid choice." ] } }, "Same Status": { "summary": "La sessione ha già questo stato", "value": [ "The new status is the same as the current status." ] } } } } }, "401": { "description": "La chiave API con ambito è scaduta.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chiave API con ambito oltre la sua data di scadenza", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenziali mancanti, chiamante senza il privilegio `write:sessions`, chiave API con ambito limitato priva dell'accesso richiesto da questo endpoint, oppure un `session_id` che appartiene a un'altra applicazione.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "Il chiamante non dispone dell'autorizzazione write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chiave API con ambito priva di questo accesso", "value": { "detail": "This API key has no write access to sessions." } } } } } }, "404": { "description": "Nessuna sessione con questo `session_id` esiste, oppure si tratta di una sessione di produzione (non sandbox).", "content": { "application/json": { "examples": { "Not Found": { "summary": "Sessione sconosciuta o di produzione", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulate/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"scenario\": \"decline_aml_hit\", \"send_webhooks\": false}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.simulate(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n scenario=\"decline_aml_hit\",\n send_webhooks=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.simulate(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n scenario: \"decline_aml_hit\",\n send_webhooks: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Simulate(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.SandboxSimulateRequest{\n\tScenario: didit.String(\"decline_aml_hit\"),\n\tSendWebhooks: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SandboxSimulateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().simulate(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", SandboxSimulateRequest.builder()\n .scenario(\"decline_aml_hit\")\n .sendWebhooks(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->simulate('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'scenario' => 'decline_aml_hit',\n 'send_webhooks' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.simulate(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n scenario: \"decline_aml_hit\",\n send_webhooks: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.SimulateAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new SandboxSimulateRequest\n{\n Scenario = \"decline_aml_hit\",\n SendWebhooks = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "simulate", "auth": "api_key", "server": true } } }, "/v3/session/{sessionId}/sandbox/simulate/": { "post": { "summary": "Simula lo stato di una sessione sandbox dal client", "description": "La stessa simulazione di `POST /v3/session/{sessionId}/simulate/`, autenticata con il `Session-Token` della sessione stessa (restituito in `session_token` da [Create Session](/it/sessions-api/create-session)) invece che con la tua chiave API, in modo che un framework di test o il flusso ospitato possano chiamarla dal client. Il body, la risposta e `send_webhooks` si comportano esattamente come su quell'endpoint.\n\nUn `Session-Token` di un'applicazione di produzione (non sandbox), o uno che non corrisponde al `sessionId` nel percorso, restituisce `404`. Vedi [Sandbox & Test Data](/it/integration/sandbox-testing).", "operationId": "post_v3_session_sandbox_simulate", "tags": [ "Sessions" ], "security": [ { "SessionTokenAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica sandbox. Deve corrispondere alla sessione codificata nel Session-Token utilizzato per l'autenticazione.", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateRequest" }, "examples": { "Scenario Without Webhooks": { "summary": "Rifiuta tramite uno scenario senza inviare webhook", "value": { "scenario": "decline_aml_hit", "send_webhooks": false } }, "Status Only": { "summary": "Approva e invia i normali webhook", "value": { "new_status": "Approved" } } } } } }, "responses": { "200": { "description": "Lo stato è cambiato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateResponse" }, "examples": { "Simulated": { "summary": "Rifiutata tramite uno scenario, webhook non inviati", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "previous_status": "In Progress", "status": "Declined", "scenario": "decline_aml_hit", "risk": "POSSIBLE_MATCH_FOUND", "send_webhooks": false } } } } } }, "400": { "description": "Errore di validazione: uno scenario o un rischio sconosciuto, nessun `new_status` quando né `scenario` né `risk` ne forniscono uno, uno stato non impostato da questo endpoint, oppure la sessione ha già lo stato richiesto (un array JSON semplice).", "content": { "application/json": { "examples": { "Unknown Scenario": { "summary": "lo scenario non è presente nel catalogo", "value": { "scenario": [ "Unknown sandbox scenario: 'not-a-scenario'." ] } }, "Unknown Risk": { "summary": "risk non è presente nel catalogo", "value": { "risk": [ "Unknown sandbox risk case: 'NOT_A_RISK'." ] } }, "Missing new_status": { "summary": "Nessun new_status, scenario o rischio", "value": { "new_status": [ "This field is required." ] } }, "Invalid new_status": { "summary": "Uno stato che la simulazione non imposta", "value": { "new_status": [ "\"Resubmitted\" is not a valid choice." ] } }, "Same Status": { "summary": "La sessione ha già questo stato", "value": [ "The new status is the same as the current status." ] } } } } }, "403": { "description": "L'intestazione `Session-Token` è mancante o non valida.", "content": { "application/json": { "examples": { "Invalid Session Token": { "summary": "Session-Token mancante o non valido", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Il `Session-Token` appartiene a un'applicazione di produzione (non-sandbox), oppure non corrisponde al `sessionId` nel percorso.", "content": { "application/json": { "examples": { "Not Found": { "summary": "Sessione live, oppure mancata corrispondenza tra session_id / token", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/sandbox/simulate/ \\\n -H 'Session-Token: YOUR_SESSION_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\"new_status\": \"Approved\", \"send_webhooks\": false}'" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/sandbox/simulate/\",\n headers={\"Session-Token\": \"YOUR_SESSION_TOKEN\"},\n json={\"new_status\": \"Approved\", \"send_webhooks\": False},\n)\nresponse.raise_for_status()\nprint(response.json())" } ], "x-didit-sdk": { "resource": "sessions", "method": "simulate_sandbox", "auth": "device_token", "server": false } } }, "/v3/session/{sessionId}/features/overrides/": { "get": { "summary": "Elenca gli override dei controlli di una sessione", "description": "Ogni override dello stato di una singola funzionalità (passaggio) in una sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB), dalla più recente alla più vecchia e senza paginazione: quelle applicate, quelle in attesa che la persona completi il flusso (`pending_until_flow_finishes`) e quelle annullate, ciascuna con l'indicazione di chi l'ha richiesta, il motivo e se è stata applicata mentre la persona era ancora nel flusso (`forced`).\n\n`person_in_flow` indica se un nuovo override con `defer_until_flow_finishes: true` rimarrebbe in attesa. `flow_finished_at` indica quando la persona ha completato l'ultima volta il flusso; è `null` se è ancora al suo interno (incluso un nuovo invio) e se la sessione si è chiusa prima del completamento.\n\nRichiede il privilegio `read:sessions`; una chiave API con ambito limitato necessita dell'accesso in lettura alle decisioni.", "operationId": "get_v3_session_feature_overrides", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "responses": { "200": { "description": "Gli override dei controlli della sessione, dal più recente al meno recente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "person_in_flow", "flow_finished_at", "overrides" ], "properties": { "session_id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "person_in_flow": { "type": "boolean", "description": "Indica se la persona si trova ancora nel flusso, in modo che un nuovo override con `defer_until_flow_finishes: true` rimanga in attesa.", "example": true }, "flow_finished_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando la persona ha completato l'ultima volta il flusso. `null` mentre si trova ancora al suo interno (incluso un nuovo invio) e quando la sessione si è chiusa prima del completamento (abbandonata, scaduta o sottoposta a una decisione a metà flusso).", "example": null }, "overrides": { "type": "array", "description": "Ogni override della sessione, dal più recente al più vecchio.", "items": { "$ref": "#/components/schemas/FeatureStatusOverride" } } } }, "examples": { "Overrides": { "summary": "Un override in attesa, uno applicato", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "person_in_flow": true, "flow_finished_at": null, "overrides": [ { "id": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3", "node_id": "feature_liveness_1", "feature_type": "", "feature_model": "Face", "previous_status": "Declined", "new_status": "Approved", "state": "pending_until_flow_finishes", "forced": false, "reason": "Liveness retried with a reviewer present.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": null, "cancelled_at": null, "cancel_reason": null }, { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "node_id": "feature_ocr_1", "feature_type": "", "feature_model": "KYC", "previous_status": "In Review", "new_status": "Approved", "state": "applied", "forced": true, "reason": "Document manually verified by compliance.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": "2026-10-13T09:15:00Z", "cancelled_at": null, "cancel_reason": null } ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chiave API con ambito oltre la sua data di scadenza", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenziali mancanti, chiamante senza il privilegio `read:sessions`, chiave API con ambito limitato priva dell'accesso richiesto da questo endpoint, oppure un `session_id` che appartiene a un'altra applicazione.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "Il chiamante non dispone dell'autorizzazione read:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chiave API con ambito priva di questo accesso", "value": { "detail": "This API key has no read access to decisions." } } } } } }, "404": { "description": "Non esiste alcuna sessione KYC o KYB con questo `session_id`.", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id sconosciuto", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/features/overrides/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.list_feature_overrides(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listFeatureOverrides(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListFeatureOverrides(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().listFeatureOverrides(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listFeatureOverrides('3fa85f64-5717-4562-b3fc-2c963f66afa6');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_feature_overrides(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListFeatureOverridesAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "list_feature_overrides", "auth": "api_key", "server": true } } }, "/v3/session/{sessionId}/features/overrides/{overrideId}/cancel/": { "post": { "summary": "Annulla un override di controllo in attesa del completamento del flusso", "description": "Annulla l'override dello stato di una funzionalità (passaggio) ancora `pending_until_flow_finishes`, in modo che non venga mai applicato. Il controllo mantiene il suo stato, l'annullamento viene registrato nelle attività della sessione come `FEATURE_OVERRIDE_CANCELLED` e non viene inviato alcun webhook. La risposta è l'override con `state: cancelled` e `cancel_reason: cancelled_by_reviewer`.\n\nUn override già applicato o annullato restituisce `409` con il codice `feature_override_not_pending`. Trova gli ID degli override con `GET /v3/session/{sessionId}/features/overrides/` o nell'oggetto `override` restituito dall'aggiornamento dello stato della funzionalità.\n\nRichiede il privilegio `write:sessions`; una chiave API con ambito limitato necessita dell'accesso in scrittura alle decisioni.", "operationId": "post_v3_session_feature_override_cancel", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, { "in": "path", "name": "overrideId", "required": true, "description": "L'`id` dell'override da annullare.", "schema": { "type": "string", "format": "uuid", "example": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3" } } ], "responses": { "200": { "description": "L'override è annullato e non verrà mai applicato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureStatusOverride" }, "examples": { "Cancelled": { "summary": "L'override annullato", "value": { "id": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3", "node_id": "feature_liveness_1", "feature_type": "", "feature_model": "Face", "previous_status": "Declined", "new_status": "Approved", "state": "cancelled", "forced": false, "reason": "Liveness retried with a reviewer present.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": null, "cancelled_at": "2026-10-13T09:20:00Z", "cancel_reason": "cancelled_by_reviewer" } } } } } }, "401": { "description": "La chiave API con ambito è scaduta.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chiave API con ambito oltre la sua data di scadenza", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenziali mancanti, chiamante senza il privilegio `write:sessions`, chiave API con ambito limitato priva dell'accesso richiesto da questo endpoint, oppure un `session_id` che appartiene a un'altra applicazione.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "Il chiamante non dispone dell'autorizzazione write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chiave API con ambito priva di questo accesso", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "Non esiste alcuna sessione KYC o KYB con questo `session_id`, oppure la sessione non ha alcun override con questo `overrideId`.", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id sconosciuto", "value": { "detail": "Not found." } }, "Override Not Found": { "summary": "Nessun override con questo id nella sessione", "value": { "detail": "Override not found." } } } } } }, "409": { "description": "L'override è già stato applicato o è stato annullato.", "content": { "application/json": { "examples": { "Not Pending": { "summary": "È possibile annullare solo un override in attesa", "value": { "detail": "This override is no longer pending: it already applied or was cancelled.", "code": "feature_override_not_pending" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/features/overrides/9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3/cancel/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.cancel_feature_override(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.cancelFeatureOverride(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.CancelFeatureOverride(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().cancelFeatureOverride(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->cancelFeatureOverride('3fa85f64-5717-4562-b3fc-2c963f66afa6', '9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.cancel_feature_override(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.CancelFeatureOverrideAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "cancel_feature_override", "auth": "api_key", "server": true } } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/add/": { "post": { "summary": "Aggiungi un tag a una rete", "description": "Applica uno dei tag della tua applicazione alla rete. Restituisce i dettagli della rete, il cui campo `tags` elenca i tag della tua applicazione sulla rete, con `201` quando il tag è stato aggiunto e `200` quando era già presente sulla rete. Un tag che appartiene a un'altra applicazione, o che non esiste, restituisce 404 `Tag not found.`. Richiede una chiave API con accesso completo, oppure `write:networks` per un membro della console.", "operationId": "add_network_tag", "tags": [ "Networks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "description": "UUID della rete." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkTagRequest" }, "example": { "tag_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/3fa85f64-5717-4562-b3fc-2c963f66afa6/tags/add/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"tag_uuid\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.add_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid=\"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.addTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.AddTag(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.NetworkTagRequest{\n\tTagUUID: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.NetworkTagRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().addTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", NetworkTagRequest.builder()\n .tagUuid(\"7c9e6679-7425-40de-944b-e07fc1f90ae7\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->addTag('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'tag_uuid' => '7c9e6679-7425-40de-944b-e07fc1f90ae7',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.add_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.AddTagAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new NetworkTagRequest\n{\n TagUuid = \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Il tag è stato aggiunto. Restituisce i dettagli della rete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [ { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "SUSPICIOUS", "color": "#6366F1", "source": "custom", "added_by": null, "added_at": "2026-10-13T08:15:00Z" } ], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "200": { "description": "Il tag era già presente sulla rete e viene lasciato invariato. Restituisce i dettagli della rete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [ { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "SUSPICIOUS", "color": "#6366F1", "source": "custom", "added_by": null, "added_at": "2026-10-13T08:15:00Z" } ], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "400": { "description": "Corpo non valido: `tag_uuid` mancante o non è un UUID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_uuid": { "type": "array", "items": { "type": "string" } } } }, "examples": { "Missing tag_uuid": { "summary": "tag_uuid mancante", "value": { "tag_uuid": [ "This field is required." ] } }, "Invalid tag_uuid": { "summary": "tag_uuid non valido", "value": { "tag_uuid": [ "Must be a valid UUID." ] } } } } } }, "401": { "description": "Credenziali mancanti o non valide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenziali mancanti o non valide", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "La chiave API appartiene a un'altra applicazione, oppure è una chiave con accesso limitato: gli endpoint Networks richiedono una chiave con accesso completo. Un token di un membro della console richiede `write:networks`. Viene restituito anche con `code: networks_not_entitled` quando Networks non è abilitato per l'organizzazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Reti non abilitate", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chiave API con restrizioni", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Nessuna autorizzazione", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Non trovato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Network not found": { "summary": "Rete non trovata", "value": { "detail": "Network not found." } }, "Tag not found": { "summary": "Tag non trovato", "value": { "detail": "Tag not found." } } } } } } }, "x-didit-sdk": { "resource": "networks", "method": "add_tag", "auth": "api_key", "server": true, "scope": "application" } } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/remove/": { "post": { "summary": "Rimuovi un tag da una rete", "description": "Rimuovi uno dei tag della tua applicazione dalla rete. Restituisce il dettaglio della rete. Errore 404 quando il tag non è presente nella rete o non appartiene alla tua applicazione. Richiede una chiave API con accesso completo oppure `write:networks` per un membro della console.", "operationId": "remove_network_tag", "tags": [ "Networks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "description": "UUID della rete." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkTagRequest" }, "example": { "tag_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/3fa85f64-5717-4562-b3fc-2c963f66afa6/tags/remove/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"tag_uuid\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.remove_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid=\"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.removeTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RemoveTag(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.NetworkTagRequest{\n\tTagUUID: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.NetworkTagRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().removeTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", NetworkTagRequest.builder()\n .tagUuid(\"7c9e6679-7425-40de-944b-e07fc1f90ae7\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->removeTag('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'tag_uuid' => '7c9e6679-7425-40de-944b-e07fc1f90ae7',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.remove_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RemoveTagAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new NetworkTagRequest\n{\n TagUuid = \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il tag è stato rimosso dalla rete. Restituisce i dettagli della rete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "400": { "description": "Corpo non valido: `tag_uuid` mancante o non è un UUID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_uuid": { "type": "array", "items": { "type": "string" } } } }, "examples": { "Missing tag_uuid": { "summary": "tag_uuid mancante", "value": { "tag_uuid": [ "This field is required." ] } }, "Invalid tag_uuid": { "summary": "tag_uuid non valido", "value": { "tag_uuid": [ "Must be a valid UUID." ] } } } } } }, "401": { "description": "Credenziali mancanti o non valide.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Missing or invalid credentials": { "summary": "Credenziali mancanti o non valide", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "La chiave API appartiene a un'altra applicazione, oppure è una chiave con accesso limitato: gli endpoint Networks richiedono una chiave con accesso completo. Un token di un membro della console richiede `write:networks`. Viene restituito anche con `code: networks_not_entitled` quando Networks non è abilitato per l'organizzazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Networks not enabled": { "summary": "Reti non abilitate", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "Chiave API con restrizioni", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "Nessuna autorizzazione", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "Non trovato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "Presente sugli errori codificati, ad esempio `networks_not_entitled`." } } }, "examples": { "Network not found": { "summary": "Rete non trovata", "value": { "detail": "Network not found." } }, "Tag not found": { "summary": "Tag non trovato", "value": { "detail": "Tag not found." } }, "Tag not on the network": { "summary": "Tag non presente sulla rete", "value": { "detail": "This tag is not on the network." } } } } } } }, "x-didit-sdk": { "resource": "networks", "method": "remove_tag", "auth": "api_key", "server": true, "scope": "application" } } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/{request_uuid}/remind/": { "post": { "summary": "Invia un promemoria al cliente per una richiesta", "description": "Invia nuovamente l'email di una richiesta del cliente in attesa, allo stesso destinatario verificato, con lo stesso contenuto. Puoi inviare un promemoria per una richiesta al massimo una volta ogni 24 ore. Un promemoria non modifica null'altro: la richiesta mantiene la sua scadenza e il caso mantiene il proprio stato. Ogni promemoria viene registrato nel caso come evento CUSTOMER_REQUEST con azione `reminded`. Il `delivery_status` della risposta indica come si è conclusa la consegna di questo promemoria: SENT, SIMULATED (l'email non è stata inviata) o UNKNOWN (l'email potrebbe essere stata accettata; non viene inviata di nuovo automaticamente). `next_reminder_at` indica quando puoi inviare nuovamente un promemoria per questa richiesta. Restituisce 409 con un `reason` quando il cliente non ha più la richiesta a cui rispondere, e 429 con `retry_at` e un'intestazione `Retry-After` quando è già stato inviato un promemoria per la richiesta nelle ultime 24 ore. Richiede `write:cases`.", "operationId": "organization_application_cases_requests_remind_create", "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID dell'organizzazione." }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID dell'applicazione." }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID del caso." }, { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "UUID della richiesta del cliente, dall'elenco delle richieste del caso." } ], "tags": [ "Case Management" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/requests/3fa85f64-5717-4562-b3fc-2c963f66afa6/remind/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.remind(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.remind(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Remind(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().remind(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->remind('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.remind(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.RemindAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il promemoria è stato registrato e la relativa email è stata inviata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "request", "reminded_at", "delivery_status", "next_reminder_at" ], "properties": { "request": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" }, "reminded_at": { "type": "string", "format": "date-time", "description": "Quando è stato registrato questo promemoria." }, "delivery_status": { "type": "string", "enum": [ "SENT", "SIMULATED", "UNKNOWN" ], "description": "Come si è conclusa la consegna di questo promemoria. SIMULATED: l'email non è stata inviata. UNKNOWN: l'email potrebbe essere stata accettata; non viene inviata di nuovo automaticamente." }, "next_reminder_at": { "type": "string", "format": "date-time", "description": "Quando puoi inviare nuovamente un promemoria per questa richiesta: `reminded_at` più 24 ore." } } }, "example": { "request": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "purpose": "confirm_details", "language": "en", "recipient": "customer@example.com", "expires_at": "2026-10-20T09:00:00Z", "actor_email": "reviewer@example.com", "delivery_status": "SENT", "delivered_at": "2026-10-13T09:00:04Z", "cancelled_at": null, "responded_at": null, "response": null, "has_attachment": false, "created_at": "2026-10-13T09:00:00Z" }, "reminded_at": "2026-10-14T10:30:00Z", "delivery_status": "SENT", "next_reminder_at": "2026-10-15T10:30:00Z" } } } }, "400": { "description": "Il caso presenta una risoluzione in attesa di approvazione. Il body è un elenco di stringhe.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Customer messages require an active case without a pending resolution." ] } } }, "403": { "description": "Il chiamante non dispone dell'autorizzazione richiesta per i casi." }, "404": { "description": "La richiesta o il caso non è disponibile per questo chiamante." }, "409": { "description": "La richiesta non è più in attesa del cliente, quindi non c'è nulla da sollecitare. Il campo `reason` ne indica il motivo: `answered` (il cliente ha risposto), `cancelled`, `expired`, `closed` (il caso è stato risolto dopo l'invio della richiesta, anche se è stato riaperto in seguito), `not_actionable` (un aggiornamento di revisione in corso non richiede alcuna azione), `not_delivered` (la prima email non è stata inviata) o `contact_unavailable` (l'email verificata non è più disponibile).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "case_request_not_waiting" ] }, "reason": { "type": "string", "enum": [ "answered", "cancelled", "expired", "closed", "not_actionable", "not_delivered", "contact_unavailable" ] } } }, "example": { "detail": "This request no longer waits on the customer, so there is nothing to remind them of.", "code": "case_request_not_waiting", "reason": "answered" } } } }, "429": { "description": "La richiesta è già stata sollecitata nelle ultime 24 ore. Il campo `retry_at` e l'intestazione `Retry-After` indicano quando puoi inviare un nuovo sollecito.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di poter inviare nuovamente un promemoria per questa richiesta.", "schema": { "type": "integer", "minimum": 1, "example": 3600 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "case_request_reminder_too_soon" ] }, "retry_at": { "type": "string", "format": "date-time" } } }, "example": { "detail": "This request was already reminded in the last 24 hours.", "code": "case_request_reminder_too_soon", "retry_at": "2026-10-15T10:30:00Z" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-didit-sdk": { "resource": "cases.requests", "method": "remind", "auth": "api_key", "server": true, "scope": "application" } } }, "/v3/session/{sessionId}/decision-email-preview/": { "post": { "summary": "Visualizza l'anteprima dell'email con la decisione di una sessione", "description": "Genera l'anteprima dell'email che la persona riceve quando imposti una sessione su `Approved` o `Declined` con `send_email: true`, senza modificare la sessione né inviare alcunché. La risposta mostra l'oggetto e l'HTML esattamente come vengono inviati, il destinatario, il mittente, la lingua e se la conferma della modifica comporterà effettivamente l'invio dell'email (`will_be_sent`, `not_sent_reason`).\n\nIl destinatario è l'indirizzo della persona stessa: quello verificato in un passaggio di verifica email del workflow, altrimenti quello fornito in `contact_details` alla creazione della sessione. Il mittente è il dominio mittente verificato della tua applicazione quando si applica il White label (`sender_kind: customer`), altrimenti il mittente di Didit (`sender_kind: didit`).\n\nPer inviare esattamente ciò di cui hai visualizzato l'anteprima, chiama [Update Session Status](/it/sessions-api/update-status) con gli stessi `new_status`, `send_email: true`, `email_address` impostato su `recipient`, `email_language` impostato su `language` ed `email_preview_token` impostato su `preview_token`. La ricevuta scade dopo 15 minuti. Se il destinatario, la lingua, lo stato della sessione, il mittente o l'email sono cambiati rispetto all'anteprima, l'aggiornamento restituisce `409` prima che venga modificato qualcosa; genera nuovamente l'anteprima e conferma con la nuova ricevuta.\n\nFunziona per le sessioni di Verifica degli utenti (KYC) e Verifica aziendale (KYB) con stato `Approved`, `Declined`, `In Review`, `Kyc Expired`, `Abandoned` o `Resubmitted`. Il controllo dello stato viene eseguito prima della validazione del corpo. Richiede il privilegio `write:sessions`; una chiave API con ambito limitato necessita dell'accesso in scrittura alle decisioni. Le risposte utilizzano `Cache-Control: no-store`: trattale come contenuto sensibile di verifica.", "operationId": "post_v3_session_decision_email_preview", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "UUID della sessione di verifica. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB).", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "La decisione di cui desideri visualizzare l'anteprima dell'email.", "example": "Approved" }, "email_language": { "type": "string", "default": "en", "description": "Lingua dell'email, con lo stesso valore predefinito di Aggiorna stato della sessione. Una lingua non offerta ripiega sull'inglese; `language` nella risposta indica quale viene utilizzata.", "example": "en" } } }, "examples": { "Approved": { "summary": "Visualizza l'anteprima dell'email di approvazione in inglese", "value": { "new_status": "Approved" } }, "Declined in Spanish": { "summary": "Visualizza l'anteprima dell'email di rifiuto in spagnolo", "value": { "new_status": "Declined", "email_language": "es" } } } } } }, "responses": { "200": { "description": "Solo anteprima. La sessione non viene modificata e non viene inviata alcuna email.", "headers": { "Cache-Control": { "description": "Sempre `no-store`: l'anteprima contiene contenuti di verifica e non deve essere memorizzata nella cache.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient", "recipient_source", "sender", "sender_name", "sender_email", "sender_kind", "subject", "html", "text", "language", "will_be_sent", "not_sent_reason", "preview_token" ], "properties": { "recipient": { "type": "string", "description": "L'indirizzo a cui viene inviata l'email. Stringa vuota se non si conosce alcun indirizzo per la persona: in tal caso non è possibile inviare alcuna email e anche `preview_token` è vuoto. Passalo come `email_address` quando confermi.", "example": "person@example.com" }, "recipient_source": { "type": "string", "enum": [ "email_verification", "contact_details", "" ], "description": "Da dove proviene `recipient`. `email_verification`: l'indirizzo verificato dalla persona in un passaggio di verifica email del flusso. `contact_details`: l'indirizzo fornito in `contact_details` alla creazione della sessione. Una stringa vuota quando non è presente alcun indirizzo.", "example": "email_verification" }, "sender": { "type": "string", "description": "L'intestazione `From` con cui viene inviata l'email.", "example": "Example App " }, "sender_name": { "type": "string", "description": "La parte del nome visualizzato di `sender`.", "example": "Example App" }, "sender_email": { "type": "string", "format": "email", "description": "La parte relativa all'indirizzo di `sender`.", "example": "no-reply@mail.example.com" }, "sender_kind": { "type": "string", "enum": [ "customer", "didit" ], "description": "`customer`: l'email viene inviata dal dominio mittente verificato della tua applicazione (white label). `didit`: viene inviata dal mittente di Didit.", "example": "customer" }, "subject": { "type": "string", "description": "La riga dell'oggetto esattamente come viene inviata.", "example": "Your verification has been approved in Example App" }, "html": { "type": "string", "description": "L'HTML dell'email esattamente come inviato, con il logo incorporato come data URL. Effettuane il rendering in un frame in sandbox, mai direttamente nel DOM della tua applicazione.", "example": "..." }, "text": { "type": "string", "description": "Il testo dell'email in testo normale, così come viene mantenuto nel thread Messaggi della persona, per un'anteprima compatta (l'HTML rimane l'email ricevuta dalla persona).", "example": "Verification Approved\n\nYour identity has been successfully verified with Acme Pay. No further action is needed on your part." }, "language": { "type": "string", "description": "La lingua in cui è scritta l'email. Inglese (`en`) se l'`email_language` richiesta non è disponibile.", "example": "en" }, "will_be_sent": { "type": "boolean", "description": "Indica se la conferma della modifica con `send_email: true` comporta l'invio di questa email. `false` quando `not_sent_reason` è impostato.", "example": true }, "not_sent_reason": { "type": "string", "nullable": true, "enum": [ "status_unchanged", "notification_emails_disabled", "no_recipient", "sandbox", null ], "description": "Il motivo per cui la conferma non invierebbe alcuna email, oppure `null` se verrà inviata. `status_unchanged`: la sessione ha già questo stato, quindi l'aggiornamento non modifica nulla e non invia nulla. `notification_emails_disabled`: la sessione è stata creata senza `contact_details.send_notification_emails: true`, quindi non viene inviata alcuna email di decisione all'indirizzo indicato in `contact_details`. `no_recipient`: non è noto alcun indirizzo per la persona. `sandbox`: una sessione sandbox il cui destinatario non ha acconsentito alla consegna delle email in sandbox, quindi l'invio viene solo simulato.", "example": null }, "preview_token": { "type": "string", "description": "Ricevuta firmata per questa specifica email, valida per 15 minuti. Inviala come `email_preview_token` a [Update Session Status](/it/sessions-api/update-status). Una stringa vuota quando non è presente alcun destinatario.", "example": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } }, "examples": { "Will Be Sent": { "summary": "L'email di approvazione viene inviata all'indirizzo verificato nel flusso", "value": { "recipient": "person@example.com", "recipient_source": "email_verification", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Your verification has been approved in Example App", "html": "...", "language": "en", "will_be_sent": true, "not_sent_reason": null, "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } }, "No Recipient": { "summary": "Nessun indirizzo noto per la persona", "value": { "recipient": "", "recipient_source": "", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Your verification has been declined in Example App", "html": "...", "language": "en", "will_be_sent": false, "not_sent_reason": "no_recipient", "preview_token": "" } } } } } }, "400": { "description": "La sessione non è in uno stato accettato da questo endpoint (`{\"detail\": ...}`), oppure il corpo non è valido (`{\"\": [\"\"]}`).", "content": { "application/json": { "examples": { "Wrong Current Status": { "summary": "La sessione non si trova in uno stato accettato da questo endpoint", "value": { "detail": "Only sessions with status Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted can be updated. Current status: In Progress" } }, "Invalid new_status": { "summary": "new_status non è Approved o Declined", "value": { "new_status": [ "\"Resubmitted\" is not a valid choice." ] } }, "Missing new_status": { "summary": "Campo obbligatorio omesso", "value": { "new_status": [ "This field is required." ] } } } } } }, "401": { "description": "La chiave API con ambito è scaduta.", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "Chiave API con ambito oltre la sua data di scadenza", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Credenziali mancanti, chiamante senza il privilegio `write:sessions`, chiave API con ambito limitato priva dell'accesso richiesto da questo endpoint, oppure un `session_id` che appartiene a un'altra applicazione.", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key mancante o non valida", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "Il chiamante non dispone dell'autorizzazione write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "Chiave API con ambito priva di questo accesso", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "Non esiste alcuna sessione KYC o KYB con questo `session_id`.", "content": { "application/json": { "examples": { "Not Found": { "summary": "session_id sconosciuto", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/decision-email-preview/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"new_status\": \"Approved\", \"email_language\": \"en\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.preview_decision_email(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n new_status=\"Approved\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.previewDecisionEmail(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n new_status: \"Approved\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.PreviewDecisionEmail(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.SessionsPreviewDecisionEmailParams{\n\tNewStatus: \"Approved\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsPreviewDecisionEmailParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().previewDecisionEmail(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", SessionsPreviewDecisionEmailParams.builder()\n .newStatus(SessionsPreviewDecisionEmailParams.NewStatus.of(\"Approved\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->previewDecisionEmail('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'new_status' => 'Approved',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.preview_decision_email(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n new_status: \"Approved\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.PreviewDecisionEmailAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new SessionsPreviewDecisionEmailParams\n{\n NewStatus = \"Approved\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "preview_decision_email", "auth": "api_key", "server": true } } }, "/v3/travel-rule/join/{token}/": { "get": { "summary": "Recupera un invito di adesione libera", "description": "Pubblico, non autenticato. Mostra l'invito a cui si riferisce un link di adesione mentre è aperto: chi lo ha richiesto, l'indirizzo a cui è stato inviato e i valori della directory che verranno precompilati. Il token funge da autenticazione.", "operationId": "getTravelRuleJoinInvitation", "x-didit-sdk": { "resource": "travel_rule.join", "method": "get_invitation", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il token di invito dal link di adesione." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/join/{token}/" } ], "responses": { "200": { "description": "L'invito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinInvitation" } } } }, "404": { "description": "Nessun invito ha questo link." }, "410": { "description": "L'invito non è più aperto: scaduto, già utilizzato o revocato." } } }, "post": { "summary": "Registra un account Travel Rule gratuito", "description": "Pubblico, non autenticato. Crea un account Travel Rule gratuito per un VASP di controparte che ha ricevuto una richiesta. L'email deve essere l'indirizzo a cui è stato inviato l'invito. Un codice di 6 caratteri viene inviato via email a tale indirizzo; invialo all'endpoint di verifica per completare la procedura. I tentativi di registrazione sono soggetti a limite di frequenza per indirizzo e per IP.", "operationId": "registerTravelRuleJoin", "x-didit-sdk": { "resource": "travel_rule.join", "method": "register", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il token di invito dal link di adesione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinRegisterRequest" }, "example": { "email": "compliance@example.com", "password": "a-long-passphrase" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/join/{token}/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\": \"compliance@example.com\", \"password\": \"a-long-passphrase\"}'" } ], "responses": { "202": { "description": "L'account è stato creato ed è stato inviato un codice via email.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Indica alla controparte di verificare la propria email per trovare il codice di verifica." }, "email": { "type": "string", "format": "email", "description": "L'indirizzo a cui è stato inviato il codice." } } } } } }, "400": { "description": "L'email non corrisponde all'indirizzo invitato, oppure la password o l'indirizzo sono stati rifiutati." }, "404": { "description": "Nessun invito ha questo link." }, "410": { "description": "L'invito non è più aperto: scaduto, già utilizzato o revocato." }, "429": { "description": "Troppi tentativi di partecipazione. Le intestazioni `X-RateLimit-*` indicano il budget esaurito." } } } }, "/v3/travel-rule/join/{token}/verify/": { "post": { "summary": "Verifica un account Travel Rule gratuito", "description": "Pubblico, non autenticato. Utilizza il codice inviato via email, crea l'organizzazione gratuita e risponde con le credenziali utilizzate dalla sua applicazione sugli endpoint del workspace. La ricezione dei dati Travel Rule è gratuita.", "operationId": "verifyTravelRuleJoin", "x-didit-sdk": { "resource": "travel_rule.join", "method": "verify", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Il token di invito dal link di adesione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinVerifyRequest" }, "example": { "email": "compliance@example.com", "code": "123456" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/join/{token}/verify/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\": \"compliance@example.com\", \"code\": \"123456\"}'" } ], "responses": { "201": { "description": "Le credenziali dell'organizzazione e dell'applicazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinCredentials" } } } }, "400": { "description": "Il codice o l'email sono stati rifiutati." }, "404": { "description": "Nessun invito ha questo link." }, "410": { "description": "L'invito non è più aperto: scaduto, già utilizzato o revocato." }, "429": { "description": "Troppi tentativi di partecipazione. Le intestazioni `X-RateLimit-*` indicano il budget esaurito." } } } }, "/v3/travel-rule/workspace/": { "get": { "summary": "Recupera il workspace gratuito di Travel Rule", "description": "Legge l'area di lavoro gratuita di un'applicazione che ha aderito al piano gratuito: rivendicazione della directory, prova del dominio, fatturazione ed elenco nella rete di Didit.", "operationId": "getTravelRuleWorkspace", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "get", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/workspace/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.get()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.get();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.Get(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().get();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->get();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.get\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.GetAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "404": { "description": "Questa applicazione non è stata registrata con il piano gratuito, quindi non ha un workspace gratuito." } } } }, "/v3/travel-rule/workspace/claim/": { "post": { "summary": "Rivendica una voce della directory", "description": "Rivendica la voce della directory corrispondente a questo workspace. Quando l'email aziendale appartiene a un dominio elencato nella voce, la rivendicazione è verificata e si applica immediatamente: il profilo VASP e le impostazioni Travel Rule vengono compilati a partire dalla voce e la Travel Rule viene attivata, cosicché il trasferimento successivo verso di essa venga instradato sulla rete Didit. Altrimenti la rivendicazione resta in attesa di revisione (`pending_review`).", "operationId": "claimTravelRuleWorkspace", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "claim", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceClaimRequest" }, "example": { "vasp_id": "0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/claim/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vasp_id\": \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.claim(\n vasp_id=\"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.claim({\n vasp_id: \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.Claim(ctx, didit.TravelRuleWorkspaceClaimRequest{\n\tVASPID: \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWorkspaceClaimRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().claim(TravelRuleWorkspaceClaimRequest.builder()\n .vaspId(\"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->claim([\n 'vasp_id' => '0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.claim(vasp_id: \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.ClaimAsync(new TravelRuleWorkspaceClaimRequest\n{\n VaspId = \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il workspace con il relativo stato della rivendicazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "Nessuna voce della directory ha questo id." }, "404": { "description": "Questa applicazione non è stata registrata con il piano gratuito, quindi non ha un workspace gratuito." } } } }, "/v3/travel-rule/workspace/domain/code/": { "post": { "summary": "Invia un codice di verifica del dominio via email", "description": "Invia un codice monouso all'indirizzo email di lavoro del workspace per verificare che controlli il dominio email. Soggetto a limite di frequenza e con un numero limitato di tentativi errati consentiti per codice. Restituisce anche il record TXT per l'alternativa DNS.", "operationId": "sendTravelRuleWorkspaceDomainCode", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "send_domain_code", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/domain/code/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.send_domain_code()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.sendDomainCode();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.SendDomainCode(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().sendDomainCode();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->sendDomainCode();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.send_domain_code\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.SendDomainCodeAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il dominio, il relativo stato e il record TXT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceDomainCodeResponse" } } } }, "404": { "description": "Questa applicazione non è stata registrata con il piano gratuito, quindi non ha un workspace gratuito." } } } }, "/v3/travel-rule/workspace/domain/confirm/": { "post": { "summary": "Conferma il codice di verifica del dominio", "description": "Consuma il codice inviato via email e contrassegna il dominio email come verificato.", "operationId": "confirmTravelRuleWorkspaceDomain", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "confirm_domain", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceDomainConfirmRequest" }, "example": { "code": "123456" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/domain/confirm/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"code\": \"123456\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.confirm_domain(\n code=\"123456\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.confirmDomain({\n code: \"123456\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.ConfirmDomain(ctx, didit.TravelRuleWorkspaceDomainConfirmRequest{\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWorkspaceDomainConfirmRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().confirmDomain(TravelRuleWorkspaceDomainConfirmRequest.builder()\n .code(\"123456\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->confirmDomain([\n 'code' => '123456',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.confirm_domain(code: \"123456\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.ConfirmDomainAsync(new TravelRuleWorkspaceDomainConfirmRequest\n{\n Code = \"123456\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "Il codice è errato, scaduto o già utilizzato." }, "404": { "description": "Questa applicazione non è stata registrata con il piano gratuito, quindi non ha un workspace gratuito." } } } }, "/v3/travel-rule/workspace/domain/dns/": { "post": { "summary": "Verifica il dominio dal suo record TXT", "description": "Verifica il record TXT `didit-tr-verify.` restituito dall'endpoint del codice e contrassegna il dominio come verificato quando corrisponde. Una delle due prove, il codice inviato via email o il record TXT, è sufficiente.", "operationId": "verifyTravelRuleWorkspaceDomainDns", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "verify_domain_dns", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/domain/dns/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.verify_domain_dns()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.verifyDomainDns();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.VerifyDomainDNS(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().verifyDomainDns();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->verifyDomainDns();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.verify_domain_dns\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.VerifyDomainDnsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "Il record TXT non è stato trovato o non corrisponde." }, "404": { "description": "Questa applicazione non è stata registrata con il piano gratuito, quindi non ha un workspace gratuito." } } } }, "/v3/travel-rule/workspace/billing/": { "post": { "summary": "Abilita la fatturazione in uscita", "description": "Attiva la fatturazione Travel Rule in uscita per il workspace. La ricezione resta gratuita. Questa operazione non può essere annullata tramite l'API: contatta l'assistenza Didit.", "operationId": "enableTravelRuleWorkspaceBilling", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "enable_billing", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceBillingRequest" }, "example": { "enabled": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/billing/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"enabled\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.enable_billing(\n enabled=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.enableBilling({\n enabled: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.EnableBilling(ctx, didit.TravelRuleWorkspaceBillingRequest{\n\tEnabled: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWorkspaceBillingRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().enableBilling(TravelRuleWorkspaceBillingRequest.builder()\n .enabled(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->enableBilling([\n 'enabled' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.enable_billing(enabled: true)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.EnableBillingAsync(new TravelRuleWorkspaceBillingRequest\n{\n Enabled = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il workspace con `billing_enabled` impostato su true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "`enabled` era false." }, "404": { "description": "Questa applicazione non è stata registrata con il piano gratuito, quindi non ha un workspace gratuito." } } } }, "/v3/investigator/summary/": { "get": { "operationId": "investigator_summary", "summary": "Riepilogo dell'investigatore", "description": "Fase, conteggi delle code, report preparati e decisioni prese oggi, accordo a 30 giorni, prezzi e livello di autonomia di ciascuna coda. Le chiavi con restrizioni richiedono l'ambito `decisions` (lettura); gli alert sulle transazioni richiedono anche `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "stage": { "type": "string" }, "last_report_at": { "type": "string", "format": "date-time", "nullable": true }, "prepared_today": { "type": "integer" }, "ready_to_accept": { "type": "integer" }, "open": { "type": "integer" }, "decided_today": { "type": "integer" }, "automation_rate_month": { "type": "number", "nullable": true }, "preparing": { "type": "integer" } } } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessioni e casi non aperti da una regola di transazione) o `transactions` (alert di transazione e casi aperti da una regola di transazione)." }, { "in": "query", "name": "timezone", "schema": { "type": "string" }, "description": "Fuso orario IANA (ad esempio `Europe/Madrid`) da cui viene calcolato \"oggi\". UTC per impostazione predefinita." } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_summary", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_summary()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveSummary();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveSummary(ctx, didit.InvestigatorRetrieveSummaryParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveSummary();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveSummary();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_summary\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveSummaryAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/queue/": { "get": { "operationId": "investigator_queue", "summary": "Elenca la coda di Investigator", "description": "Report aperti, prima **quelli pronti per l'accettazione**, poi per scadenza, rischio e attesa. `counts` copre ogni tipo nell'ambito. `count` ha un limite massimo di 100. Le chiavi con restrizioni richiedono l'ambito `decisions` (lettura); gli alert sulle transazioni richiedono anche `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "counts": { "type": "object", "additionalProperties": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/InvestigatorQueueRow" } } } } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessioni e casi non aperti da una regola di transazione) o `transactions` (alert di transazione e casi aperti da una regola di transazione)." }, { "in": "query", "name": "kind", "schema": { "type": "string" }, "description": "`session`, `business_session`, `transaction` o `case`, oppure più valori separati da virgole." }, { "in": "query", "name": "queue", "schema": { "type": "string", "enum": [ "kyc", "kyb", "aml", "transactions", "cases" ] } }, { "in": "query", "name": "recommendation", "schema": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] } }, { "in": "query", "name": "confidence", "schema": { "type": "string", "enum": [ "high", "moderate", "low" ] } }, { "in": "query", "name": "ready", "schema": { "type": "boolean" } }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Nome, azienda, titolo del caso, numero, ID transazione o ID elemento." }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "x-didit-sdk": { "resource": "investigator", "method": "list_queue", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.investigator.list_queue():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.investigator.listQueue()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Investigator.ListQueueAutoPaging(ctx, didit.InvestigatorListQueueParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.investigator().listQueue()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "investigator->listQueue() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.investigator.list_queue.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Investigator.ListQueueAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/investigator/runs/{run_id}/": { "get": { "operationId": "investigator_run_retrieve", "summary": "Recupera un report di Investigator", "description": "Il report completo di un'esecuzione. 404 se l'esecuzione non ha un report completato o se l'elemento corrispondente è stato eliminato. Le chiavi con restrizioni richiedono lo scope `decisions` (lettura); gli alert sulle transazioni richiedono anche `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorRunDetail" } } } }, "404": { "description": "Non trovato, o nessun report." }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_run", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_run(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveRun(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveRun(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveRun(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveRun('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_run(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveRunAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/runs/{run_id}/accept/": { "post": { "operationId": "investigator_run_accept", "summary": "Accettare una raccomandazione", "description": "Applica l'azione consigliata tramite il percorso standard dell'elemento, attivando i consueti webhook. La presenza di un campo `narrative` lo rende modificato e accettato. Le chiavi con restrizioni richiedono l'ambito `decisions` (scrittura); gli alert sulle transazioni richiedono inoltre `transactions` (scrittura). L'escalation di una verifica o di una transazione apre un caso.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorDecision" } } } }, "409": { "description": "Già deciso, report non pronto, oppure un guardrail blocca l'elemento." }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorAcceptRequest" }, "example": { "send_email": false } } } }, "x-didit-sdk": { "resource": "investigator", "method": "accept_run", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.accept_run(\n \"11111111-2222-3333-4444-555555555555\",\n send_email=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.acceptRun(\"11111111-2222-3333-4444-555555555555\", {\n send_email: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.AcceptRun(ctx, \"11111111-2222-3333-4444-555555555555\", didit.InvestigatorAcceptRequest{\n\tSendEmail: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.InvestigatorAcceptRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().acceptRun(\"11111111-2222-3333-4444-555555555555\", InvestigatorAcceptRequest.builder()\n .sendEmail(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->acceptRun('11111111-2222-3333-4444-555555555555', [\n 'send_email' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.accept_run(\n \"11111111-2222-3333-4444-555555555555\",\n send_email: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.AcceptRunAsync(\"11111111-2222-3333-4444-555555555555\", new InvestigatorAcceptRequest\n{\n SendEmail = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/runs/{run_id}/override/": { "post": { "operationId": "investigator_run_override", "summary": "Sovrascrivi una raccomandazione", "description": "Esegue un'altra azione indicando una categoria e una motivazione. Esegue anche l'override di una decisione presa autonomamente dall'Investigator mentre è ancora valida. Le chiavi con restrizioni richiedono l'ambito `decisions` (scrittura); gli alert sulle transazioni richiedono inoltre `transactions` (scrittura). L'escalation di una verifica o di una transazione apre un caso.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorDecision" } } } }, "409": { "description": "Già deciso, oppure un guardrail blocca l'elemento." }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorOverrideRequest" }, "example": { "action": "decline", "category": "evidence_misread", "reason": "The proof of address is older than three months." } } } }, "x-didit-sdk": { "resource": "investigator", "method": "override_run", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.override_run(\n \"11111111-2222-3333-4444-555555555555\",\n action=\"decline\",\n category=\"evidence_misread\",\n reason=\"The proof of address is older than three months.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.overrideRun(\"11111111-2222-3333-4444-555555555555\", {\n action: \"decline\",\n category: \"evidence_misread\",\n reason: \"The proof of address is older than three months.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.OverrideRun(ctx, \"11111111-2222-3333-4444-555555555555\", didit.InvestigatorOverrideRequest{\n\tAction: \"decline\",\n\tCategory: \"evidence_misread\",\n\tReason: \"The proof of address is older than three months.\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.InvestigatorOverrideRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().overrideRun(\"11111111-2222-3333-4444-555555555555\", InvestigatorOverrideRequest.builder()\n .action(InvestigatorOverrideRequest.Action.of(\"decline\"))\n .category(InvestigatorOverrideRequest.Category.of(\"evidence_misread\"))\n .reason(\"The proof of address is older than three months.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->overrideRun('11111111-2222-3333-4444-555555555555', [\n 'action' => 'decline',\n 'category' => 'evidence_misread',\n 'reason' => 'The proof of address is older than three months.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.override_run(\n \"11111111-2222-3333-4444-555555555555\",\n action: \"decline\",\n category: \"evidence_misread\",\n reason: \"The proof of address is older than three months.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.OverrideRunAsync(\"11111111-2222-3333-4444-555555555555\", new InvestigatorOverrideRequest\n{\n Action = \"decline\",\n Category = \"evidence_misread\",\n Reason = \"The proof of address is older than three months.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/runs/batch-accept/": { "post": { "operationId": "investigator_batch_accept", "summary": "Accetta raccomandazioni in blocco", "description": "Accetta fino a 50 report contrassegnati come Pronti per l'accettazione. Ciascuno costituisce una propria decisione: quelli che non possono essere accettati vengono ignorati indicandone il motivo. Le chiavi con restrizioni richiedono l'ambito `decisions` (scrittura); gli alert sulle transazioni richiedono inoltre `transactions` (scrittura). L'escalation di una verifica o di una transazione apre un caso.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorBatchAcceptResponse" } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorBatchAcceptRequest" } } } }, "x-didit-sdk": { "resource": "investigator", "method": "batch_accept_runs", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.batch_accept_runs(\n run_ids=[\"11111111-2222-3333-4444-555555555555\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.batchAcceptRuns({\n run_ids: [\"11111111-2222-3333-4444-555555555555\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.BatchAcceptRuns(ctx, didit.InvestigatorBatchAcceptRequest{\n\tRunIDs: []string{\"11111111-2222-3333-4444-555555555555\"},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.InvestigatorBatchAcceptRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().batchAcceptRuns(InvestigatorBatchAcceptRequest.builder()\n .runIds(List.of(\"11111111-2222-3333-4444-555555555555\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->batchAcceptRuns([\n 'run_ids' => ['11111111-2222-3333-4444-555555555555'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.batch_accept_runs(run_ids: [\"11111111-2222-3333-4444-555555555555\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.BatchAcceptRunsAsync(new InvestigatorBatchAcceptRequest\n{\n RunIds = new string[] { \"11111111-2222-3333-4444-555555555555\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/transactions/{transaction_id}/": { "get": { "operationId": "investigator_transaction_retrieve", "summary": "Recupera la revisione Investigator di una transazione", "description": "L'ultima revisione della transazione, o `investigator: null` quando non ne ha mai avuta una. Le chiavi con restrizioni richiedono gli ambiti `decisions` e `transactions` (lettura).", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "investigator": { "$ref": "#/components/schemas/InvestigatorBlock" } } } } } }, "404": { "description": "Non è una transazione di questa applicazione." }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "path", "name": "transaction_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_transaction", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_transaction(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveTransaction(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveTransaction(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveTransaction(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveTransaction('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_transaction(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveTransactionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/guardrails/": { "get": { "operationId": "investigator_guardrails", "summary": "Elenca i guardrail bloccati", "description": "I cinque guardrail applicati a ogni coda. Non possono essere disattivati. Le chiavi con restrizioni richiedono lo scope `decisions` (lettura); gli alert sulle transazioni richiedono anche `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "sanctions_to_person", "no_tipping_off", "no_protected_characteristics", "never_files_reports", "every_decision_logged" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "locked": { "type": "boolean" } } } } } } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "x-didit-sdk": { "resource": "investigator", "method": "list_guardrails", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.list_guardrails()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.listGuardrails();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.ListGuardrails(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().listGuardrails();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->listGuardrails();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.list_guardrails\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.ListGuardrailsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/dashboard/": { "get": { "operationId": "investigator_dashboard", "summary": "Dashboard dell'investigatore", "description": "Gli ultimi 30 giorni: revisioni, decisioni, tasso di automazione, ore risparmiate, spesa, sovrascritture, campioni di qualità dal rilascio in produzione, dati per coda e settimanali. Le chiavi con restrizioni richiedono lo scope `decisions` (lettura); gli alert sulle transazioni richiedono anche `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "stage": { "type": "string" }, "window_days": { "type": "integer" }, "reviews": { "type": "integer" }, "decided": { "type": "integer" }, "automated": { "type": "integer" }, "automation_rate": { "type": "number", "nullable": true }, "hours_saved": { "type": "number", "nullable": true } } } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessioni e casi non aperti da una regola di transazione) o `transactions` (alert di transazione e casi aperti da una regola di transazione)." } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_dashboard", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_dashboard()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveDashboard();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveDashboard(ctx, didit.InvestigatorRetrieveDashboardParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveDashboard();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveDashboard();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_dashboard\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveDashboardAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/performance/": { "get": { "operationId": "investigator_performance", "summary": "Rendimento dell'investigatore", "description": "Accordo con il tuo team, volume, tempo risparmiato, calibrazione della confidenza, risultati per coda, motivi di override e disaccordi per un periodo. Le chiavi con restrizioni richiedono l'ambito `decisions` (lettura); gli alert sulle transazioni richiedono anche `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "period": { "type": "integer" }, "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" }, "investigated": { "type": "integer" } } } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessioni e casi non aperti da una regola di transazione) o `transactions` (alert di transazione e casi aperti da una regola di transazione)." }, { "in": "query", "name": "period", "schema": { "type": "string", "enum": [ "7", "30", "90" ], "default": "30" }, "description": "Giorni, con termine oggi." } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_performance", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_performance()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrievePerformance();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrievePerformance(ctx, didit.InvestigatorRetrievePerformanceParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrievePerformance();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrievePerformance();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_performance\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrievePerformanceAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/activity/": { "get": { "operationId": "investigator_activity", "summary": "Elenca l'attività dell'investigatore", "description": "Il registro di audit append-only, dal più recente al meno recente. L'accettazione di un batch costituisce una singola voce. Aggiunge `counts` per gruppo e `actors`. Le chiavi con restrizioni richiedono lo scope `decisions` (lettura); gli alert sulle transazioni richiedono anche `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "counts": { "type": "object", "additionalProperties": true }, "actors": { "type": "array", "items": {} }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "`id`, `at`, `kind`, `group`, `queue`, `run_id`, `item`, `actor`, `agent_version`, `data`, `report_version`, `steps`, `sources`, `batch`." } } } } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessioni e casi non aperti da una regola di transazione) o `transactions` (alert di transazione e casi aperti da una regola di transazione)." }, { "in": "query", "name": "group", "schema": { "type": "string", "enum": [ "agent", "decisions", "overrides", "autonomy" ] } }, { "in": "query", "name": "actor", "schema": { "type": "string" }, "description": "`agent` per l'Investigator, o l'email di una persona." }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "until", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "x-didit-sdk": { "resource": "investigator", "method": "list_activity", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.investigator.list_activity():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.investigator.listActivity()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Investigator.ListActivityAutoPaging(ctx, didit.InvestigatorListActivityParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.investigator().listActivity()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "investigator->listActivity() as $item) {\n print_r($item);\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.investigator.list_activity.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Investigator.ListActivityAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/investigator/activity/export/": { "get": { "operationId": "investigator_activity_export", "summary": "Esportare l'attività dell'Investigator", "description": "Le stesse voci in formato CSV, una riga per decisione, dalla più recente, fino a 10.000 voci. Le chiavi con restrizioni richiedono l'ambito `decisions` (lettura); gli alert delle transazioni richiedono anche `transactions`.", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity` (sessioni e casi non aperti da una regola di transazione) o `transactions` (alert di transazione e casi aperti da una regola di transazione)." }, { "in": "query", "name": "group", "schema": { "type": "string", "enum": [ "agent", "decisions", "overrides", "autonomy" ] } }, { "in": "query", "name": "actor", "schema": { "type": "string" }, "description": "`agent` per l'Investigator, o l'email di una persona." }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "until", "schema": { "type": "string", "format": "date-time" } } ], "x-didit-sdk": { "resource": "investigator", "method": "export_activity", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.investigator.export_activity()\nwith open(\"download.csv\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.investigator.exportActivity();\nawait writeFile(\"download.csv\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Investigator.ExportActivity(ctx, didit.InvestigatorExportActivityParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.csv\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.investigator().exportActivity()\n .writeTo(Path.of(\"download.csv\"));" }, { "lang": "php", "label": "PHP", "source": "investigator->exportActivity();\n$content->saveTo('download.csv');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.investigator.export_activity\nFile.binwrite(\"download.csv\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Investigator.ExportActivityAsync();\nawait content.SaveToAsync(\"download.csv\");" } ] } }, "/v3/investigator/settings/": { "get": { "operationId": "investigator_settings_retrieve", "summary": "Recupera le impostazioni di Investigator", "description": "La fase (`none`, `shadow` o `live`) e il limite di spesa mensile con la spesa del mese corrente. Le chiavi con restrizioni richiedono l'ambito `applications` (read).", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorSettings" } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "x-didit-sdk": { "resource": "investigator", "method": "retrieve_settings", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_settings()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveSettings();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveSettings(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveSettings();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveSettings();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_settings\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveSettingsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "operationId": "investigator_settings_update", "summary": "Aggiorna le impostazioni di Investigator", "description": "Modifica la fase, il limite di spesa mensile o entrambi. Per superare `none` è necessario un piano che includa l'Investigator (Growth o superiore); `live` richiede inoltre un contratto che ne definisca il prezzo, se ne hai uno. Le chiavi con restrizioni richiedono l'ambito `applications` (write).", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorSettings" } } } }, "400": { "description": "Nessuno dei due campi inviato, oppure valore non valido." }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "La chiave non dispone dello scope necessario, il tipo di elemento non è leggibile o il piano non include l'Investigator." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorSettings" }, "example": { "stage": "shadow", "monthly_spend_limit": "500.00" } } } }, "x-didit-sdk": { "resource": "investigator", "method": "update_settings", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.update_settings(\n stage=\"shadow\",\n monthly_spend_limit=\"500.00\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.updateSettings({\n stage: \"shadow\",\n monthly_spend_limit: \"500.00\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.UpdateSettings(ctx, didit.InvestigatorSettingsParam{\n\tStage: didit.Some(didit.InvestigatorSettingsStage(\"shadow\")),\n\tMonthlySpendLimit: didit.String(\"500.00\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.InvestigatorSettings;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().updateSettings(InvestigatorSettings.builder()\n .stage(InvestigatorSettings.Stage.of(\"shadow\"))\n .monthlySpendLimit(\"500.00\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->updateSettings([\n 'stage' => 'shadow',\n 'monthly_spend_limit' => '500.00',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.update_settings(\n stage: \"shadow\",\n monthly_spend_limit: \"500.00\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.UpdateSettingsAsync(new InvestigatorSettings\n{\n Stage = new InvestigatorSettingsStage(\"shadow\"),\n MonthlySpendLimit = \"500.00\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/travel-rule/wallet-addresses/import/": { "post": { "summary": "Importare indirizzi di wallet in blocco", "description": "Aggiungi fino a 10.000 wallet alla tua rubrica degli indirizzi per la Travel Rule in una sola chiamata, in formato JSON o come file CSV. Un wallet può essere inviato tramite il suo indirizzo, tramite lo SHA-256 del suo indirizzo in lettere minuscole (`address_hash`) per mantenerlo privato, o entrambi. L'importazione è idempotente: un wallet già presente nella rubrica viene segnalato come `existing` e lasciato inalterato, consentendo di inviare nuovamente lo stesso file. Ogni riga viene convalidata singolarmente, pertanto una riga errata non compromette mai le altre. Un wallet importato tramite il relativo hash trova corrispondenza solo con i trasferimenti verso quell'indirizzo e può essere dimostrato con il widget di titolarità del wallet come qualsiasi altra voce.", "operationId": "importTravelRuleWalletAddresses", "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "bulk_import", "auth": "api_key", "server": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/WalletAddressImportRow" } } } }, { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/WalletAddressImportRow" } } ] }, "example": { "entries": [ { "address": "0xBeneficiaryWallet01", "chain": "ETH", "holder_name": "Ana Diaz", "holder_vendor_data": "user-042" }, { "address_hash": "4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e", "chain": "bitcoin", "holder_vendor_data": "user-043" }, { "address": "rExchangeSharedAddress01", "chain": "XRP", "memo": "104729", "holder_name": "Ana Diaz" } ] } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Un file CSV in UTF-8 di massimo 5 MB con una riga di intestazione che elenca le relative colonne (i campi della riga o i loro alias). Le celle vuote contano come non inviate; le colonne non lette dall'importazione vengono ignorate." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl (JSON)", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/import/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"entries\": [{\"address\": \"0xBeneficiaryWallet01\", \"chain\": \"ETH\", \"holder_name\": \"Ana Diaz\"}, {\"address\": \"rExchangeSharedAddress01\", \"chain\": \"XRP\", \"memo\": \"104729\"}]}'" }, { "lang": "curl", "label": "curl (CSV)", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/import/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'file=@wallets.csv;type=text/csv'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_addresses.bulk_import(\n body={\n \"entries\": [{\n \"address\": \"0xBeneficiaryWallet01\",\n \"chain\": \"ETH\",\n \"holder_name\": \"Ana Diaz\",\n \"holder_vendor_data\": \"user-042\",\n }, {\n \"address_hash\": \"4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e\",\n \"chain\": \"bitcoin\",\n \"holder_vendor_data\": \"user-043\",\n }, {\n \"address\": \"rExchangeSharedAddress01\",\n \"chain\": \"XRP\",\n \"memo\": \"104729\",\n \"holder_name\": \"Ana Diaz\",\n }],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletAddresses.bulkImport({\n file: await fileFromPath(\"wallet-addresses.csv\"),\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.WalletAddresses.BulkImport(ctx, didit.TravelRuleWalletAddressesBulkImportParams{\n\tFile: didit.Some(didit.FileFromPath(\"wallet-addresses.csv\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.TravelRuleWalletAddressesBulkImportParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletAddresses().bulkImport(TravelRuleWalletAddressesBulkImportParams.builder()\n .file(Path.of(\"wallet-addresses.csv\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->bulkImport([\n 'file' => File::fromPath('wallet-addresses.csv'),\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_addresses.bulk_import(\n body: {\n entries: [{\n address: \"0xBeneficiaryWallet01\",\n chain: \"ETH\",\n holder_name: \"Ana Diaz\",\n holder_vendor_data: \"user-042\",\n }, {\n address_hash: \"4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e\",\n chain: \"bitcoin\",\n holder_vendor_data: \"user-043\",\n }, {\n address: \"rExchangeSharedAddress01\",\n chain: \"XRP\",\n memo: \"104729\",\n holder_name: \"Ana Diaz\",\n }],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletAddresses.BulkImportAsync(new TravelRuleWalletAddressesBulkImportParams\n{\n File = FileUpload.FromPath(\"wallet-addresses.csv\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Ogni riga è stata creata, era già presente nel registro o è una ripetizione di una riga precedente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressImportReport" }, "example": { "total": 3, "created": 2, "existing": 1, "duplicate": 0, "failed": 0, "rows": [ { "row": 1, "status": "existing", "entry_id": "11111111-2222-3333-4444-555555555555", "errors": {}, "duplicate_of_row": null }, { "row": 2, "status": "created", "entry_id": "22222222-3333-4444-5555-666666666666", "errors": {}, "duplicate_of_row": null }, { "row": 3, "status": "created", "entry_id": "33333333-4444-5555-6666-777777777777", "errors": {}, "duplicate_of_row": null } ] } } } }, "207": { "description": "Almeno una riga ha avuto esito negativo; le altre sono state importate. Ogni riga con esito negativo indica i relativi errori.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressImportReport" }, "example": { "total": 2, "created": 1, "existing": 0, "duplicate": 0, "failed": 1, "rows": [ { "row": 1, "status": "created", "entry_id": "44444444-5555-6666-7777-888888888888", "errors": {}, "duplicate_of_row": null }, { "row": 2, "status": "failed", "entry_id": null, "errors": { "address": [ "Send address, address_hash or both." ] }, "duplicate_of_row": null } ] } } } }, "400": { "description": "Impossibile leggere la richiesta: sono presenti sia `entries` sia un `file`, oppure nessuno dei due; più di 10.000 righe; un file superiore a 5 MB, non in formato CSV UTF-8, senza riga di intestazione o privo di righe.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "file": [ "At most 10000 rows per import." ] } } } } } } }, "/v3/travel-rule/counterparty-contacts/": { "get": { "summary": "Elenca i contatti della controparte", "description": "Gli indirizzi di compliance a cui il canale EMAIL può scrivere per la tua applicazione: i contatti della piattaforma Didit più quelli privati della tua applicazione, inclusi quelli per i quali la consegna è fallita, dal più recente. Paginato con `limit` (predefinito 50) e `offset`; `count` si ferma a 100, quindi 100 indica 100 o più.", "operationId": "listTravelRuleCounterpartyContacts", "x-didit-sdk": { "resource": "travel_rule.counterparty_contacts", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "counterparty", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Solo i contatti di questa voce di directory. Deve essere un UUID; un valore vuoto indica nessun filtro." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Dimensione della pagina, valore predefinito 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Righe da saltare." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/travel-rule/counterparty-contacts/?counterparty={vasp_id}' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.counterparty_contacts.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.counterpartyContacts.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.CounterpartyContacts.ListAutoPaging(ctx, didit.TravelRuleCounterpartyContactsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().counterpartyContacts().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->counterpartyContacts->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.counterparty_contacts.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.CounterpartyContacts.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "I contatti.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleCounterpartyContact" } } } }, "example": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b", "counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "counterparty_name": "Example Counterparty VASP", "email": "compliance@counterparty.example", "name": "Compliance desk", "source": "application", "scope": "application", "created_by": "", "verified_at": null, "is_invalid": false, "invalid_reason": "", "invalid_detail": "", "invalid_at": null, "created_at": "2026-10-19T09:00:00Z" } ] } } } }, "400": { "description": "`counterparty` non è un UUID.", "content": { "application/json": { "example": { "counterparty": [ "Must be a valid UUID." ] } } } } } }, "post": { "summary": "Aggiungi un contatto della controparte", "description": "Aggiunge un indirizzo di compliance privato per una voce della directory. Solo la tua applicazione lo vede e lo utilizza, e il canale EMAIL scrive a questo indirizzo prima di qualsiasi contatto della piattaforma. L'aggiunta di un indirizzo già presente per la voce tra i tuoi contatti restituisce quel contatto.", "operationId": "createTravelRuleCounterpartyContact", "x-didit-sdk": { "resource": "travel_rule.counterparty_contacts", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyContactCreate" }, "example": { "counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "email": "compliance@counterparty.example", "name": "Compliance desk" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/counterparty-contacts/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"counterparty\": \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\", \"email\": \"compliance@counterparty.example\", \"name\": \"Compliance desk\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.counterparty_contacts.create(\n counterparty=\"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n email=\"compliance@counterparty.example\",\n name=\"Compliance desk\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.counterpartyContacts.create({\n counterparty: \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n email: \"compliance@counterparty.example\",\n name: \"Compliance desk\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.CounterpartyContacts.Create(ctx, didit.TravelRuleCounterpartyContactCreate{\n\tCounterparty: \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n\tEmail: \"compliance@counterparty.example\",\n\tName: didit.String(\"Compliance desk\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyContactCreate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().counterpartyContacts().create(TravelRuleCounterpartyContactCreate.builder()\n .counterparty(\"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\")\n .email(\"compliance@counterparty.example\")\n .name(\"Compliance desk\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->counterpartyContacts->create([\n 'counterparty' => '0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91',\n 'email' => 'compliance@counterparty.example',\n 'name' => 'Compliance desk',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.counterparty_contacts.create(\n counterparty: \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n email: \"compliance@counterparty.example\",\n name: \"Compliance desk\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.CounterpartyContacts.CreateAsync(new TravelRuleCounterpartyContactCreate\n{\n Counterparty = \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n Email = \"compliance@counterparty.example\",\n Name = \"Compliance desk\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Il contatto è stato aggiunto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyContact" }, "example": { "uuid": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b", "counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "counterparty_name": "Example Counterparty VASP", "email": "compliance@counterparty.example", "name": "Compliance desk", "source": "application", "scope": "application", "created_by": "", "verified_at": null, "is_invalid": false, "invalid_reason": "", "invalid_detail": "", "invalid_at": null, "created_at": "2026-10-19T09:00:00Z" } } } }, "400": { "description": "Un campo è mancante o non valido, oppure nessuna voce della directory ha questo ID.", "content": { "application/json": { "example": { "counterparty": [ "No directory entry with this id." ] } } } } } } }, "/v3/travel-rule/counterparty-contacts/{contact_uuid}/": { "delete": { "summary": "Elimina un contatto della controparte", "description": "Elimina uno dei contatti dell'applicazione. Il canale EMAIL smette immediatamente di inviare comunicazioni a tale indirizzo. I contatti della piattaforma non possono essere eliminati.", "operationId": "deleteTravelRuleCounterpartyContact", "x-didit-sdk": { "resource": "travel_rule.counterparty_contacts", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "contact_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/travel-rule/counterparty-contacts/{contact_uuid}/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.travel_rule.counterparty_contacts.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.travelRule.counterpartyContacts.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.TravelRule.CounterpartyContacts.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.travelRule().counterpartyContacts().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "travelRule->counterpartyContacts->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.counterparty_contacts.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.TravelRule.CounterpartyContacts.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "Eliminato." }, "404": { "description": "Nessun contatto della tua applicazione ha questo id. Anche un contatto di piattaforma risponde con 404." } } } }, "/v3/travel-rule/transfers/": { "get": { "summary": "Elenca i trasferimenti Travel Rule", "description": "I trasferimenti Travel Rule della tua applicazione, dal più recente al meno recente, paginati con `limit` (predefinito 50) e `offset`. Le righe contengono solo nomi di VASP, wallet e note, mai dati personali. I valori separati da virgola consentono di selezionarne molteplici. Un valore sconosciuto restituisce 400 indicando il parametro, ad esempio `{\"direction\": [\"Unknown value(s): inbound.\"]}`.", "operationId": "listTravelRuleTransfers", "x-didit-sdk": { "resource": "travel_rule.transfers", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "INBOUND, OUTBOUND o entrambi separati da virgola. Distingue tra maiuscole e minuscole." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Uno o più stati di trasferimento, separati da virgola." }, { "name": "rail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Uno o più tra INTERNAL, TRP, GTR, TRUST, VERIFYVASP, SYGNA, EMAIL, TEST_VASP, separati da virgola." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "withdrawal, deposit o message, separati da virgola." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "La valuta della transazione, senza distinzione tra maiuscole e minuscole." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Trasferimenti creati a partire da questo giorno incluso (UTC), YYYY-MM-DD." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Trasferimenti creati entro questo giorno incluso (UTC), YYYY-MM-DD." }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "L'`id` di una voce della directory o di un membro della rete Didit da GET /v3/travel-rule/vasps/: i tuoi trasferimenti con tale controparte. Un valore che non è un id valido risponde con 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Dimensione della pagina, valore predefinito 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Righe da saltare." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/travel-rule/transfers/?direction=OUTBOUND&status=AWAITING_COUNTERPARTY' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.transfers.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.transfers.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.Transfers.ListAutoPaging(ctx, didit.TravelRuleTransfersListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().transfers().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->transfers->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.transfers.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.Transfers.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Una pagina di trasferimenti.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleTransferRow" } } } }, "example": { "count": 1, "next": null, "previous": null, "results": [ { "id": "5b0f6c2e-2a4d-4f0e-9a41-0c3f9a7e1d22", "transaction_id": "a3c1e8f4-7b62-4d1a-8e0b-2f9d6c4b7a10", "txn_id": "wd-2026-10-19-0042", "txn_date": "2026-10-19T08:41:12Z", "kind": "withdrawal", "direction": "OUTBOUND", "status": "AWAITING_COUNTERPARTY", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "Origin CASP SL", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": null, "deadline_at": "2026-10-21T08:41:13Z", "created_at": "2026-10-19T08:41:13Z" } ] } } } }, "400": { "description": "Il valore di un filtro non è valido.", "content": { "application/json": { "example": { "start_date": [ "Use the YYYY-MM-DD format." ] } } } } } } }, "/v3/session/imports/providers/": { "get": { "summary": "Elenca i provider di migrazione", "description": "I 15 provider da cui è possibile migrare le verifiche: cosa richiede ciascuno per connettersi, se la sua API può elencare i record, le autorizzazioni richieste dalla sua chiave e la mappatura predefinita degli stati.", "operationId": "get_v3_session_imports_providers_list", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_providers", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "Provider di migrazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ImportProvider" } }, "mapping_targets": { "type": "array", "items": { "type": "string" } }, "skipped_statuses": { "type": "array", "items": { "type": "string" } } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure il chiamante non può importare verifiche per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.list_providers()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.listProviders();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.ListProviders(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().listProviders();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listProviders();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.list_providers\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ListProvidersAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/providers/check/": { "post": { "summary": "Verifica la chiave di un provider", "description": "Legge il provider con la tua chiave prima di creare una migrazione. Non viene memorizzato nulla.", "operationId": "post_v3_session_imports_providers_check", "x-didit-sdk": { "resource": "sessions.imports", "method": "check_provider", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ], "description": "Origine della migrazione, da `GET /v3/session/imports/providers/`. Obbligatoria quando `source` è `provider`." }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "La chiave di sola lettura del provider, con i nomi dei campi elencati in `credential_fields`. Crittografata a riposo, mai restituita ed eliminata al termine dell'importazione. Inviala come stringa JSON in multipart." }, "options": { "type": "object", "properties": { "region": { "type": "string", "description": "La regione del provider, una delle sue `regions` (Onfido: `eu`, `us`, `ca`)." } } }, "record_ids": { "type": "array", "items": { "type": "string" }, "description": "Per i provider `api_ids`: il primo ID record della tua esportazione." } }, "required": [ "provider", "credentials" ] }, "example": { "provider": "sumsub", "credentials": { "app_token": "YOUR_PROVIDER_APP_TOKEN", "secret_key": "YOUR_PROVIDER_SECRET_KEY" } } } } }, "responses": { "200": { "description": "La chiave può leggere i record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "provider": { "type": "string" }, "credential_hint": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Il provider ha rifiutato la chiave: `code`, `detail`, `missing_permissions`, `suggested_region`." }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure il chiamante non può importare verifiche per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.check_provider(\n provider=\"sumsub\",\n credentials={\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.checkProvider({\n provider: \"sumsub\",\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.CheckProvider(ctx, didit.SessionsImportsCheckProviderParams{\n\tProvider: \"sumsub\",\n\tCredentials: map[string]string{\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsImportsCheckProviderParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().checkProvider(SessionsImportsCheckProviderParams.builder()\n .provider(SessionsImportsCheckProviderParams.Provider.of(\"sumsub\"))\n .credentials(Map.of(\"app_token\", \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\", \"YOUR_PROVIDER_SECRET_KEY\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->checkProvider([\n 'provider' => 'sumsub',\n 'credentials' => ['app_token' => 'YOUR_PROVIDER_APP_TOKEN', 'secret_key' => 'YOUR_PROVIDER_SECRET_KEY'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.check_provider(\n provider: \"sumsub\",\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.CheckProviderAsync(new SessionsImportsCheckProviderParams\n{\n Provider = \"sumsub\",\n Credentials = new Dictionary { [\"app_token\"] = \"YOUR_PROVIDER_APP_TOKEN\", [\"secret_key\"] = \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/start/": { "post": { "summary": "Avvia una simulazione", "description": "Avvia una migrazione la cui esecuzione a vuoto è terminata (`READY`): lo stesso job importa realmente, con la mappatura dello stato e la scelta dei modelli facciali inviate ora.", "operationId": "post_v3_session_imports_start", "x-didit-sdk": { "resource": "sessions.imports", "method": "start", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] }, "description": "Modifiche alla mappatura predefinita degli stati del provider: dallo stato di origine allo stato di Didit. `Not Finished` e `Abandoned` vengono ignorati e conteggiati, mai importati." }, "face_templates": { "type": "boolean", "default": false, "description": "Genera modelli biometrici dai selfie importati ed esegui la ricerca rispetto ai volti e alla blocklist dell'applicazione. Le corrispondenze vengono contrassegnate solo per la revisione. Richiede `lawful_basis_confirmed`." }, "lawful_basis_confirmed": { "type": "boolean", "default": false, "description": "Conferma che disponi di una base giuridica per condividere questi selfie con Didit in qualità di responsabile del trattamento." } } } } } }, "responses": { "200": { "description": "Il job di importazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "Il job non si trova in uno stato a cui si applica questa azione." }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure il chiamante non può importare verifiche per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.start(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.start(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Start(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsImportsStartParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().start(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->start('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.start(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.StartAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/pause/": { "post": { "summary": "Metti in pausa un processo di importazione", "description": "Metti in pausa un'importazione in coda o in esecuzione.", "operationId": "post_v3_session_imports_pause", "x-didit-sdk": { "resource": "sessions.imports", "method": "pause", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Il job di importazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "Il job non si trova in uno stato a cui si applica questa azione." }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure il chiamante non può importare verifiche per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.pause(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.pause(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Pause(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().pause(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->pause('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.pause(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.PauseAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/resume/": { "post": { "summary": "Riprendi un processo di importazione", "description": "Riprendi un'importazione che hai sospeso. Un processo sospeso a causa del limite di frequenza del provider riprende automaticamente.", "operationId": "post_v3_session_imports_resume", "x-didit-sdk": { "resource": "sessions.imports", "method": "resume", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Il job di importazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "Il job non si trova in uno stato a cui si applica questa azione." }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure il chiamante non può importare verifiche per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.resume(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.resume(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Resume(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().resume(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->resume('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.resume(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ResumeAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/cancel/": { "post": { "summary": "Annulla un job di importazione", "description": "Annulla un'importazione. Gli elementi già importati rimangono; il file caricato e la chiave vengono cancellati.", "operationId": "post_v3_session_imports_cancel", "x-didit-sdk": { "resource": "sessions.imports", "method": "cancel", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Il job di importazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "Il job non si trova in uno stato a cui si applica questa azione." }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure il chiamante non può importare verifiche per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.cancel(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Cancel(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().cancel(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->cancel('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.cancel(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.CancelAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/retry/": { "post": { "summary": "Riprova una migrazione", "description": "Esegui nuovamente una migrazione terminata come nuovo job, con una nuova chiave (quella precedente è stata cancellata). Mantiene il provider, il workflow, la regione, la mappatura degli stati e la scelta dei modelli facciali; tutto ciò che è già presente in Didit viene saltato.", "operationId": "post_v3_session_imports_retry", "x-didit-sdk": { "resource": "sessions.imports", "method": "retry", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "La chiave di sola lettura del provider, con i nomi dei campi elencati in `credential_fields`. Crittografata a riposo, mai restituita ed eliminata al termine dell'importazione. Inviala come stringa JSON in multipart." }, "file": { "type": "string", "format": "binary", "description": "Di nuovo gli ID dei record o il file di esportazione, per i provider `api_ids` ed `export_file`." } } }, "example": { "credentials": { "app_token": "YOUR_PROVIDER_APP_TOKEN", "secret_key": "YOUR_PROVIDER_SECRET_KEY" } } } } }, "responses": { "201": { "description": "Il nuovo job di importazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "Non è una migrazione, non è terminata o il fornitore ha rifiutato la chiave." }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure il chiamante non può importare verifiche per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.retry(\n \"11111111-2222-3333-4444-555555555555\",\n credentials={\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.retry(\"11111111-2222-3333-4444-555555555555\", {\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Retry(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsImportsRetryParams{\n\tCredentials: didit.Some(map[string]string{\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsImportsRetryParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().retry(\"11111111-2222-3333-4444-555555555555\", SessionsImportsRetryParams.builder()\n .credentials(Map.of(\"app_token\", \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\", \"YOUR_PROVIDER_SECRET_KEY\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->retry('11111111-2222-3333-4444-555555555555', [\n 'credentials' => ['app_token' => 'YOUR_PROVIDER_APP_TOKEN', 'secret_key' => 'YOUR_PROVIDER_SECRET_KEY'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.retry(\n \"11111111-2222-3333-4444-555555555555\",\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.RetryAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsImportsRetryParams\n{\n Credentials = new Dictionary { [\"app_token\"] = \"YOUR_PROVIDER_APP_TOKEN\", [\"secret_key\"] = \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/import-jobs/": { "get": { "summary": "Elenca i job di importazione", "description": "Ogni importazione dell'applicazione in un unico formato: importazioni di verifiche e migrazioni, persone e aziende.", "operationId": "get_v3_import_jobs_list", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_jobs", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "all", "sessions", "users", "businesses" ], "default": "all" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Processi di importazione, dal più recente al meno recente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJobSummary" } }, "counts": { "type": "object", "properties": { "all": { "type": "integer" }, "running_and_waiting": { "type": "integer" }, "needs_attention": { "type": "integer" }, "done": { "type": "integer" } } } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure il chiamante non può importare verifiche per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.list_jobs()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.listJobs();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.ListJobs(ctx, didit.SessionsImportsListJobsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().listJobs();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listJobs();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.list_jobs\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ListJobsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/import-jobs/active/": { "get": { "summary": "Elenca i job di importazione attivi", "description": "Cosa è in esecuzione o in attesa, oltre a cosa è appena terminato, per un indicatore di avanzamento.", "operationId": "get_v3_import_jobs_active", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_active_jobs", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "Processi di importazione attivi.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJobSummary" } }, "running": { "type": "integer" } } } } } }, "403": { "description": "Chiave API mancante, non valida o revocata, oppure il chiamante non può importare verifiche per questa applicazione.", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.list_active_jobs()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.listActiveJobs();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.ListActiveJobs(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().listActiveJobs();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listActiveJobs();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.list_active_jobs\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ListActiveJobsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/delete/": { "delete": { "summary": "Elimina transazioni in blocco", "description": "Elimina una o più transazioni in modo permanente. Selezionale con `transaction_uuids`, oppure elimina ogni transazione nell'applicazione con `delete_all: true`.\n\nUna transazione eliminata viene rimossa insieme ai record associati esclusivamente a essa: le relative parti, tag, note, collegamenti ai metodi di pagamento, documenti e ogni versione archiviata dei relativi file, esecuzioni delle regole, alert, risultati del provider, snapshot di rete e dati Travel Rule. I casi, le persone e le aziende rimangono; il loro collegamento alla transazione eliminata viene rimosso. Le bozze dei report normativi smettono di includerla e vengono rigenerate senza di essa. L'eliminazione è permanente e irreversibile; non esiste alcun endpoint di annullamento.\n\nSe una delle transazioni selezionate è inclusa in un report normativo finalizzato, l'intera richiesta viene rifiutata con `409` e non viene eliminato nulla. Il corpo della risposta utilizza `code: in_filed_report` e specifica ciascuna transazione e i report che la includono. Elimina tali report, quindi ripeti la richiesta.", "operationId": "batch_delete_transactions", "x-didit-sdk": { "resource": "transactions", "method": "batch_delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Transactions" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'organizzazione." }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID dell'applicazione." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "title": "Selected transactions", "required": [ "transaction_uuids" ], "properties": { "transaction_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "UUID delle transazioni Didit da eliminare. Obbligatorio a meno che `delete_all` non sia true.", "minItems": 1 }, "delete_all": { "type": "boolean", "enum": [ false ], "default": false, "description": "Ometti o invia `false` quando selezioni le transazioni con `transaction_uuids`." } } }, { "title": "All transactions", "required": [ "delete_all" ], "properties": { "delete_all": { "type": "boolean", "enum": [ true ], "description": "Elimina ogni transazione nell'applicazione. `transaction_uuids` viene ignorato." }, "transaction_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Ignorato quando `delete_all` è true." } } } ] }, "examples": { "Selected transactions": { "value": { "transaction_uuids": [ "abcdef12-3456-7890-abcd-ef1234567890", "12345678-90ab-cdef-1234-567890abcdef" ] } }, "All transactions": { "value": { "delete_all": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl (selected transactions)", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/delete/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"transaction_uuids\": [\"abcdef12-3456-7890-abcd-ef1234567890\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.transactions.batch_delete(\n body={\n \"transaction_uuids\": [\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"],\n },\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.transactions.batchDelete({\n transaction_uuids: [\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"],\n});" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TransactionsBatchDeleteParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.transactions().batchDelete(TransactionsBatchDeleteParams.builder()\n .putAdditionalProperty(\"transaction_uuids\", List.of(\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"))\n .build());" }, { "lang": "php", "label": "PHP", "source": "transactions->batchDelete([\n 'transaction_uuids' => ['abcdef12-3456-7890-abcd-ef1234567890', '12345678-90ab-cdef-1234-567890abcdef'],\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.transactions.batch_delete(\n body: {\n transaction_uuids: [\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"],\n }\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Transactions.BatchDeleteAsync(new TransactionsBatchDeleteParams\n{\n TransactionUuids = new string[] { \"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\" },\n});" } ], "responses": { "204": { "description": "Transazioni selezionate eliminate." }, "400": { "description": "Non è stato fornito alcun selettore di transazione.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_uuids": { "type": "array", "items": { "type": "string" } } } }, "example": { "transaction_uuids": [ "This field is required unless delete_all is true." ] } } } }, "403": { "description": "La chiave API non può eliminare transazioni. L'endpoint richiede `write:transactions`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "409": { "description": "Almeno una transazione selezionata è inclusa in un report normativo finalizzato. Non viene eliminato nulla.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/travel-rule/networks/": { "get": { "summary": "Recupera reti Travel Rule", "description": "Legge, per questa applicazione, lo stato effettivo di ciascuna rete: se invia tramite la tua adesione o tramite quella di Didit, e il motivo per cui non può ancora farlo. Restituisce inoltre il questionario di due diligence e i tuoi partecipanti. L'operazione di lettura non crea alcuna risorsa.", "operationId": "getTravelRuleNetworks", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/networks/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.retrieve()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.retrieve();\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().retrieve();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->retrieve();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.retrieve\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.RetrieveAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Stati della rete, questionario e partecipanti.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworksOverview" }, "examples": { "Before the questionnaire": { "value": { "platform_networks_enabled": false, "questionnaire": { "status": "draft", "answers": {}, "submitted_at": null, "reviewed_at": null, "review_note": "", "history": [], "updated_at": null }, "participants": [], "networks": { "gtr": { "rail": "GTR", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "trust": { "rail": "TRUST", "mode": "unavailable", "state": "unavailable", "reason": "own_membership_only", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "verifyvasp": { "rail": "VERIFYVASP", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "sygna": { "rail": "SYGNA", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 } } } } } } } }, "401": { "description": "Chiave API mancante o non valida." } } } }, "/v3/travel-rule/networks/questionnaire/": { "get": { "summary": "Recupera il questionario di rete", "description": "Leggi il questionario di due diligence di rete di Didit per questa applicazione, il suo stato e la nota di revisione di Didit. Un'applicazione che non ne ha mai salvato uno legge una bozza vuota.", "operationId": "getTravelRuleNetworkQuestionnaire", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "retrieve_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/networks/questionnaire/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.retrieve_questionnaire()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.retrieveQuestionnaire();\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().retrieveQuestionnaire();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->retrieveQuestionnaire();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.retrieve_questionnaire\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.RetrieveQuestionnaireAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il questionario.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" } } } }, "401": { "description": "Chiave API mancante o non valida." } } }, "put": { "summary": "Salva le risposte al questionario di rete", "description": "Salva le risposte al questionario finché si trova nello stato draft o changes_requested. I salvataggi sono parziali: le risposte non inviate vengono mantenute.", "operationId": "updateTravelRuleNetworkQuestionnaire", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "update_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT https://verification.didit.me/v3/travel-rule/networks/questionnaire/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"legal_name\": \"Example VASP Ltd\", \"incorporation_country\": \"ES\", \"aml_ctf_policy_attested\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.update_questionnaire(\n legal_name=\"Example VASP Ltd\",\n incorporation_country=\"ES\",\n aml_ctf_policy_attested=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.updateQuestionnaire({\n legal_name: \"Example VASP Ltd\",\n incorporation_country: \"ES\",\n aml_ctf_policy_attested: true,\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleNetworkQuestionnaireAnswers;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().updateQuestionnaire(TravelRuleNetworkQuestionnaireAnswers.builder()\n .legalName(\"Example VASP Ltd\")\n .incorporationCountry(\"ES\")\n .amlCtfPolicyAttested(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->updateQuestionnaire([\n 'legal_name' => 'Example VASP Ltd',\n 'incorporation_country' => 'ES',\n 'aml_ctf_policy_attested' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.update_questionnaire(\n legal_name: \"Example VASP Ltd\",\n incorporation_country: \"ES\",\n aml_ctf_policy_attested: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.UpdateQuestionnaireAsync(new TravelRuleNetworkQuestionnaireAnswers\n{\n LegalName = \"Example VASP Ltd\",\n IncorporationCountry = \"ES\",\n AmlCtfPolicyAttested = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaireAnswers" }, "example": { "legal_name": "Example VASP Ltd", "incorporation_country": "ES", "aml_ctf_policy_attested": true } } } }, "responses": { "200": { "description": "Il questionario con le risposte unite.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" } } } }, "400": { "description": "Errore di validazione, indicizzato per campo." }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "L'accesso alla rete tramite l'adesione a Didit non è ancora aperto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_platform_networks_disabled" ] } } } } } }, "409": { "description": "Il questionario è in carico a Didit o è stato deciso: può cambiare solo quando è in stato draft o changes_requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_questionnaire_not_editable" ] } } } } } } } } }, "/v3/travel-rule/networks/questionnaire/submit/": { "post": { "summary": "Invia il questionario di rete", "description": "Invia il questionario salvato alla revisione di Didit. Le risposte salvate devono essere complete: ogni campo tranne lei e data_protection_contact_email, con le tre attestazioni impostate su true. Didit lo approva, richiede modifiche (modifica e invia nuovamente) o lo rifiuta. Le reti richieste mentre era in sospeso vengono affidate al rispettivo onboarding quando viene approvato.", "operationId": "submitTravelRuleNetworkQuestionnaire", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "submit_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/networks/questionnaire/submit/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.submit_questionnaire()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.submitQuestionnaire();\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().submitQuestionnaire();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->submitQuestionnaire();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.submit_questionnaire\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.SubmitQuestionnaireAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il questionario inviato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" } } } }, "400": { "description": "Le risposte salvate sono incomplete o non valide, indicizzate per campo." }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "L'accesso alla rete tramite l'adesione a Didit non è ancora aperto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_platform_networks_disabled" ] } } } } } }, "409": { "description": "Il questionario è in carico a Didit o è stato deciso: può cambiare solo quando è in stato draft o changes_requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_questionnaire_not_editable" ] } } } } } } } } }, "/v3/travel-rule/networks/{network}/request/": { "post": { "summary": "Richiedere una rete Travel Rule", "description": "Richiedi il partecipante proprio di questa applicazione su una rete inclusa nell'affiliazione di Didit (GTR o Sygna). Senza un questionario approvato, il partecipante rimane in attesa (questionnaire_pending); con un questionario approvato, passa all'onboarding della rete (submitted_to_network) e diventa attivo quando la rete gli assegna un codice. Idempotente: un partecipante in attesa, in fase di onboarding o attivo viene restituito senza modifiche. Se la rete ha rifiutato la registrazione (last_error impostato), inviare nuovamente la richiesta esegue un nuovo tentativo. TRUST e VerifyVASP sono raggiungibili solo tramite la propria affiliazione: TRUST ammette membri per singolo VASP e un Enclave VerifyVASP serve un solo ID VASP.", "operationId": "requestTravelRuleNetworkAccess", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "request_access", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "network", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "gtr", "sygna" ] }, "description": "La rete a cui aderire tramite l'adesione di Didit." } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/networks/gtr/request/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.request_access(\n \"your-network\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.requestAccess(\"your-network\");\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().requestAccess(\"your-network\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->requestAccess('your-network');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.request_access(\"your-network\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.RequestAccessAsync(\"your-network\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Il tuo partecipante alla rete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkParticipant" } } } }, "400": { "description": "Rete sconosciuta, una rete non supportata da Didit (collega la tua appartenenza) o un'applicazione sandbox.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_network_own_membership_only", "travel_rule_network_sandbox_application" ] } } } } } }, "401": { "description": "Chiave API mancante o non valida." }, "403": { "description": "L'accesso alla rete tramite l'adesione a Didit non è ancora aperto.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_platform_networks_disabled" ] } } } } } } } } }, "/v3/address-validation/": { "post": { "summary": "Valida un indirizzo", "description": "Conferma che un indirizzo esiste e lo riceve normalizzato: righe di consegna, componenti e coordinate. Conferma solo l'indirizzo; non collega mai l'indirizzo a una persona.\n\n**Richiesta.** Invia l'indirizzo su una sola riga (`address`) o come campi strutturati (`address_line_1` e, facoltativamente, `address_line_2`, `city`, `region`, `postal_code`), mai entrambi, e sempre il rispettivo `country` (ISO 3166-1 alpha-2 o alpha-3).\n\n**Risultato.** `address_validation.status` è `verified` (confermato fino all'edificio), `partially_verified` (confermato solo fino alla via o a un livello superiore), `not_verified` (corrispondenza solo per regione o città, oppure nessuna corrispondenza) o `unavailable` (non è stato possibile eseguire la validazione). HTTP è `200` per ogni richiesta completata, inclusa `unavailable`; riprova più tardi in caso di risultato `unavailable`.\n\n**Fatturazione.** Una chiamata in ambiente di produzione costa $0.10 per indirizzo validato. Un risultato `unavailable` non viene addebitato. Non viene memorizzato nulla a parte il record di utilizzo: non viene creata alcuna sessione e il risultato viene restituito solo in questa risposta.\n\n**Sandbox.** Le chiavi sandbox validano la richiesta e restituiscono sempre un risultato deterministico `verified` che ripropone l'indirizzo inviato, senza consumare crediti.\n\n**Autenticazione.** Invia la chiave API della tua applicazione nell'intestazione `x-api-key`. Credenziali mancanti o non valide restituiscono `403`: questa API non restituisce mai `401`.\n\n**Limite di frequenza.** Budget di scrittura condiviso di 300 richieste al minuto per chiave API tra tutti gli endpoint POST/PATCH/DELETE (la creazione di transazioni e l'ingestione di eventi hanno un budget separato di 600).", "operationId": "post_v3_address_validation", "x-didit-sdk": { "resource": "address_validation", "method": "validate", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/address-validation/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"address_line_1\": \"1600 Amphitheatre Pkwy\",\n \"city\": \"Mountain View\",\n \"region\": \"CA\",\n \"postal_code\": \"94043\",\n \"country\": \"US\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.address_validation.validate(\n address_line_1=\"1600 Amphitheatre Pkwy\",\n city=\"Mountain View\",\n region=\"CA\",\n postal_code=\"94043\",\n country=\"US\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.addressValidation.validate({\n address_line_1: \"1600 Amphitheatre Pkwy\",\n city: \"Mountain View\",\n region: \"CA\",\n postal_code: \"94043\",\n country: \"US\",\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.AddressValidationRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.addressValidation().validate(AddressValidationRequest.builder()\n .addressLine1(\"1600 Amphitheatre Pkwy\")\n .city(\"Mountain View\")\n .region(\"CA\")\n .postalCode(\"94043\")\n .country(\"US\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "addressValidation->validate([\n 'address_line_1' => '1600 Amphitheatre Pkwy',\n 'city' => 'Mountain View',\n 'region' => 'CA',\n 'postal_code' => '94043',\n 'country' => 'US',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.address_validation.validate(\n address_line_1: \"1600 Amphitheatre Pkwy\",\n city: \"Mountain View\",\n region: \"CA\",\n postal_code: \"94043\",\n country: \"US\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.AddressValidation.ValidateAsync(new AddressValidationRequest\n{\n AddressLine1 = \"1600 Amphitheatre Pkwy\",\n City = \"Mountain View\",\n Region = \"CA\",\n PostalCode = \"94043\",\n Country = \"US\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationRequest" }, "examples": { "Structured": { "summary": "Campi strutturati dell'indirizzo", "value": { "address_line_1": "1600 Amphitheatre Pkwy", "city": "Mountain View", "region": "CA", "postal_code": "94043", "country": "US" } }, "One line": { "summary": "L'indirizzo completo su una sola riga", "value": { "address": "Paseo de la Castellana 259, 28046 Madrid", "country": "ES" } } } } } }, "responses": { "200": { "description": "La validazione è stata completata. Leggi `address_validation.status`; il codice HTTP è sempre `200` per una richiesta completata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationResponse" }, "examples": { "Verified": { "summary": "Un indirizzo reale, confermato a livello di edificio", "value": { "request_id": "6f7d2c1e-1c5a-4a1e-9b8f-2a1f0f4b9c3d", "address_validation": { "status": "verified", "verification_level": "premise", "address": { "address_line_1": "1600 Amphitheatre Pkwy", "address_line_2": null, "city": "Mountain View", "region": "CA", "postal_code": "94043-1351", "country": "US" }, "formatted_address": "1600 Amphitheatre Pkwy, Mountain View CA 94043-1351", "latitude": 37.422022, "longitude": -122.08429 }, "created_at": "2026-10-27T11:20:00.000000+00:00" } }, "Not verified": { "summary": "Una via inventata: solo la città corrispondeva", "value": { "request_id": "0b9e3f4a-6c2d-4e8b-a1f7-5d3c2b1a0e9f", "address_validation": { "status": "not_verified", "verification_level": "locality", "address": { "address_line_1": "Calle Inventada Que No Existe 99999 28046", "address_line_2": null, "city": "Madrid", "region": "Madrid", "postal_code": null, "country": "ES" }, "formatted_address": "Calle Inventada Que No Existe 99999 28046, Madrid, MADRID, SPAIN", "latitude": 40.42603054, "longitude": -3.68645331 }, "created_at": "2026-10-27T11:21:00.000000+00:00" } }, "Unavailable": { "summary": "Impossibile eseguire la validazione; nessun addebito", "value": { "request_id": "3c1b2a0f-9e8d-4c7b-b6a5-1f0e9d8c7b6a", "address_validation": { "status": "unavailable", "verification_level": null, "address": null, "formatted_address": null, "latitude": null, "longitude": null }, "created_at": "2026-10-27T11:22:00.000000+00:00" } } } } } }, "400": { "$ref": "#/components/responses/AddressValidationValidationError" }, "403": { "$ref": "#/components/responses/AddressValidationPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } } } }, "/v3/travel-rule/wallet-proofs/": { "get": { "summary": "Elenca prove del wallet tramite screenshot da revisionare", "description": "La tua coda di revisione per le prove di proprietà del wallet tramite screenshot. Lo screenshot è l'unica prova che Didit non può verificare automaticamente: una volta che l'utente finale lo carica dal widget, rimane in stato PENDING fino a quando non lo approvi o lo rifiuti con POST /v3/travel-rule/wallet-proofs/{proof_uuid}/decision/. Prima le prove più vecchie, così la coda viene gestita a partire dalla prova in attesa da più tempo. Vengono mostrati solo gli screenshot caricati, mai una prova per cui l'utente finale non ha ancora caricato un file, e mai una su un wallet eliminato dalla tua rubrica (Didit le chiude con OWNERSHIP_CHANGED).", "operationId": "listTravelRuleWalletProofs", "x-didit-sdk": { "resource": "travel_rule.wallet_proofs", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "description": "Quali prove elencare. Il valore predefinito è PENDING, ovvero quelle ancora da decidere.", "schema": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ], "default": "PENDING" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/wallet-proofs/?status=PENDING \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.wallet_proofs.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.walletProofs.list()) {\n console.log(item);\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().walletProofs().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletProofs->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.wallet_proofs.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.WalletProofs.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "Prove tramite screenshot impaginate. Il conteggio è esatto fino a 100 e bloccato a 100 oltre tale soglia.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleWalletProofReview" } } } } } } }, "400": { "description": "Stato sconosciuto." }, "401": { "description": "x-api-key mancante o non valida." }, "403": { "description": "Il chiamante non dispone dell'autorizzazione per le transazioni." } } } }, "/v3/travel-rule/wallet-proofs/{proof_uuid}/decision/": { "post": { "summary": "Approva o rifiuta una prova del wallet tramite screenshot", "description": "Prendi una decisione su una prova tramite screenshot dalla tua coda di revisione. approve verifica la prova e la voce della rubrica e applica l'assetto proprietario al trasferimento per cui la sessione del widget è stata creata, esattamente come fa una firma verificata. Uno screenshot non conferma mai un trasferimento inviato da un altro cliente Didit tramite il canale INTERNAL: per questo è necessario un messaggio firmato o un deposito di prova. reject chiude la prova come REJECTED con failure_reason REVIEW_REJECTED; l'utente finale può avviare una nuova prova dal widget. La nota viene conservata con la prova.", "operationId": "decideTravelRuleWalletProof", "x-didit-sdk": { "resource": "travel_rule.wallet_proofs", "method": "decide", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "proof_uuid", "in": "path", "required": true, "description": "proof_id dalla coda di revisione.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWalletProofDecision" }, "example": { "decision": "approve", "note": "Address matches the wallet app." } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-proofs/{proof_uuid}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"decision\": \"approve\", \"note\": \"Address matches the wallet app.\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_proofs.decide(\n \"11111111-2222-3333-4444-555555555555\",\n decision=\"approve\",\n note=\"Address matches the wallet app.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletProofs.decide(\"11111111-2222-3333-4444-555555555555\", {\n decision: \"approve\",\n note: \"Address matches the wallet app.\",\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWalletProofDecision;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletProofs().decide(\"11111111-2222-3333-4444-555555555555\", TravelRuleWalletProofDecision.builder()\n .decision(TravelRuleWalletProofDecision.Decision.of(\"approve\"))\n .note(\"Address matches the wallet app.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletProofs->decide('11111111-2222-3333-4444-555555555555', [\n 'decision' => 'approve',\n 'note' => 'Address matches the wallet app.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_proofs.decide(\n \"11111111-2222-3333-4444-555555555555\",\n decision: \"approve\",\n note: \"Address matches the wallet app.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletProofs.DecideAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleWalletProofDecision\n{\n Decision = \"approve\",\n Note = \"Address matches the wallet app.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "La prova determinata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWalletProofReview" } } } }, "400": { "description": "Decisione non valida o nota più lunga di 512 caratteri." }, "401": { "description": "x-api-key mancante o non valida." }, "403": { "description": "Il chiamante non dispone dell'autorizzazione per le transazioni." }, "404": { "description": "Nessuna prova con screenshot inviata con questo id nella tua applicazione." }, "409": { "description": "La prova ha già una decisione (il corpo ne riporta lo stato) o il codice OWNERSHIP_CHANGED: il titolare del wallet è cambiato o il wallet è stato eliminato dopo la creazione della sessione del widget, quindi la prova è chiusa e l'attuale titolare ne necessita una nuova.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } } } } }, "/v3/travel-rule/widget/{token}/proofs/": { "post": { "summary": "Avvia una prova di titolarità del wallet", "description": "Endpoint pubblico associato al token di sessione del widget, nessuna chiave API richiesta: il widget ospitato lo chiama quando l'utente finale sceglie un metodo di prova. Una prova esiste, e conta nel tuo funnel di prova, solo a partire da questa chiamata. Scegliere di nuovo lo stesso metodo restituisce la prova già aperta (200, stesso challenge o importo del deposito) invece di avviarne una seconda; scegliere un altro metodo chiude quella non completata come METHOD_SWITCHED, ad eccezione di uno screenshot inviato o di un deposito di prova ancora in fase di verifica. MESSAGE_SIGNING restituisce il challenge da firmare; SATOSHI_TEST l'indirizzo di deposito, l'importo esatto e la finestra temporale; SELF_DECLARATION viene verificata immediatamente (stato VERIFIED). Formati di firma verificati per famiglia di catena: le catene EVM accettano una firma personal_sign (EIP-191), codificata in hex; Bitcoin accetta una firma signmessage BIP-137 (indirizzi P2PKH, P2SH-P2WPKH e P2WPKH) o una firma semplice BIP-322 (indirizzi P2WPKH e P2TR), codificata in base64; Solana accetta una firma Ed25519 sul challenge, codificata in base58; Tron accetta una firma signMessageV2 (TIP-191), codificata in hex. Una firma BIP-322 completa o di prova dei fondi, oppure un indirizzo multisig, fallisce con SIGNATURE_UNSUPPORTED_SCHEME.", "operationId": "createTravelRuleWidgetProof", "x-didit-sdk": { "resource": "travel_rule", "method": "create_widget_proof", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token di sessione opaco restituito quando la sessione del widget è stata creata.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofCreate" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget/{token}/proofs/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"method\": \"MESSAGE_SIGNING\"}'" } ], "responses": { "201": { "description": "Una nuova prova PENDING (VERIFIED per SELF_DECLARATION).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofSummary" } } } }, "200": { "description": "La prova già aperta per questo metodo, ripresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofSummary" } } } }, "400": { "description": "Corpo non valido, un wallet che non corrisponde al trasferimento, SCREENSHOT non consentito o codice CHAIN_UNSUPPORTED quando il metodo non è disponibile sulla blockchain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "403": { "description": "SELF_DECLARATION non è consentito per questa applicazione." }, "404": { "description": "Token sconosciuto." }, "409": { "description": "codice OWNERSHIP_CHANGED: il titolare del wallet è cambiato o il wallet è stato eliminato dopo la creazione della sessione; crea una nuova sessione per il titolare attuale. Restituito anche per SATOSHI_TEST quando la sessione non ha satoshi_deposit_address e quando la sessione non ha tentativi rimanenti (nessun codice; il corpo contiene max_attempts, attempts_used e attempts_remaining 0): crea una nuova sessione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "410": { "description": "La sessione è scaduta." } } } }, "/v3/travel-rule/widget/{token}/proofs/{proof_id}/verify/": { "post": { "summary": "Invia la prova di titolarità del wallet", "description": "Endpoint pubblico associato al token di sessione del widget, nessuna chiave API richiesta. Invia l'evidenza richiesta dal metodo di prova: firma per MESSAGE_SIGNING, txid per SATOSHI_TEST (JSON) o un file per SCREENSHOT (multipart). Ogni invio conta come un tentativo. Una firma che non viene verificata, o un deposito che non corrisponde, restituisce 400 con un codice e lascia la prova in PENDING affinché l'utente finale possa riprovare. Un deposito rilevato ma non ancora confermato risponde con 200 e stato PENDING e viene ricontrollato automaticamente fino alla chiusura della finestra temporale. Uno screenshot risponde con 200 e stato PENDING e attende nella tua coda di revisione (GET /v3/travel-rule/wallet-proofs/). Una prova EXPIRED o REJECTED non verrà mai verificata in seguito: avviane una nuova. Formati di firma verificati per famiglia di catena: le catene EVM accettano una firma personal_sign (EIP-191), codificata in hex; Bitcoin accetta una firma signmessage BIP-137 (indirizzi P2PKH, P2SH-P2WPKH e P2WPKH) o una firma semplice BIP-322 (indirizzi P2WPKH e P2TR), codificata in base64; Solana accetta una firma Ed25519 sul challenge, codificata in base58; Tron accetta una firma signMessageV2 (TIP-191), codificata in hex. Una firma BIP-322 completa o di prova dei fondi, oppure un indirizzo multisig, fallisce con SIGNATURE_UNSUPPORTED_SCHEME.", "operationId": "verifyTravelRuleWidgetProof", "x-didit-sdk": { "resource": "travel_rule", "method": "verify_widget_proof", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token di sessione opaco restituito quando la sessione del widget è stata creata.", "schema": { "type": "string" } }, { "name": "proof_id", "in": "path", "required": true, "description": "proof_id restituito all'avvio della prova.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature": { "type": "string", "description": "MESSAGE_SIGNING: la firma del wallet sulla sfida della prova." }, "txid": { "type": "string", "description": "SATOSHI_TEST: l'ID di transazione del deposito di prova." } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "SCREENSHOT: un'immagine che mostra il wallet nell'app del wallet dell'utente finale." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget/{token}/proofs/{proof_id}/verify/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"signature\": \"0x...\"}'" } ], "responses": { "200": { "description": "VERIFIED, o ancora PENDING (uno screenshot in attesa di revisione, un deposito non ancora indicizzato o non ancora confermato, con codice DEPOSIT_NOT_FOUND o DEPOSIT_UNCONFIRMED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofVerifyResult" } } } }, "400": { "description": "Elemento probatorio mancante; un tentativo non riuscito che mantiene la prova in stato PENDING consentendo all'utente finale di riprovare (codice SIGNATURE_INVALID, SIGNATURE_UNSUPPORTED_SCHEME o DEPOSIT_LOOKUP_FAILED); oppure un deposito di prova che rifiuta la prova (codice DEPOSIT_MISMATCH, DEPOSIT_STALE o TXID_REUSED, stato REJECTED, con il conteggio dei tentativi della sessione): selezionando nuovamente un metodo si avvia una nuova prova finché attempts_remaining è superiore a 0.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "404": { "description": "Token sconosciuto o nessuna prova di questo tipo presente nella sessione." }, "409": { "description": "codice OWNERSHIP_CHANGED (la prova si chiude con questo); una prova chiusa (REJECTED o EXPIRED), con il suo stato, il codice con cui si è chiusa e i conteggi dei tentativi della sessione: seleziona nuovamente un metodo per avviare una nuova prova; oppure una prova SELF_DECLARATION, che viene verificata all'avvio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "410": { "description": "La sessione è scaduta, oppure codice WINDOW_EXPIRED quando la finestra del test dei satoshi si è chiusa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } } } } }, "/v3/id-verification/wallets/verifications/{request_id}/response/": { "post": { "operationId": "submit_wallet_verification_response", "x-didit-sdk": { "resource": "id_wallets", "method": "submit_verification_response", "auth": "api_key", "server": true }, "description": "Wallet Digital Credentials API (Google Wallet): invia ciò che il wallet ha restituito alla tua pagina o app per una verifica la cui next_action è request_digital_credential. Didit lo decifra, controlla la firma dell'emittente rispetto alle radici attendibili degli emittenti, ogni valore restituito rispetto al suo digest firmato e la firma del dispositivo sulla tua origine e su questa richiesta, quindi decide la verifica: verificata (fatturata una volta) o rifiutata con il codice di errore. Monouso: un secondo invio restituisce la verifica decisa.", "summary": "Invia una risposta del wallet", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "Il request_id restituito dall'endpoint di avvio.", "required": true } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialResponseRequest" }, "example": { "response": { "protocol": "openid4vp-v1-signed", "data": { "response": "" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialResponseRequest" }, "example": { "response": { "protocol": "openid4vp-v1-signed", "data": { "response": "" } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialResponseRequest" }, "example": { "response": { "protocol": "openid4vp-v1-signed", "data": { "response": "" } } } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "google_wallet", "name": "Google Wallet", "issuing_authority": "Google Wallet (ID pass) and US state issuers (mobile driving licence)" }, "country": "USA", "status": "Approved", "outcome": "verified", "error": null, "interaction": "digital_credentials", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": null, "identity": { "full_name": "Alex Example", "first_name": "Alex", "last_name": "Example", "date_of_birth": "1990-01-31", "nationality": "USA", "issuing_state": "USA" }, "attributes": { "document_number": "X0000000", "document_expiry_date": "2030-01-31" }, "level_of_assurance": "substantial", "verified_at": "2026-01-01T10:01:00Z", "signature_valid": true, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "Credenziali mancanti (x-api-key o Authorization: Bearer)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore not_found: nessuna verifica wallet di questa applicazione ha questo request_id." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]})." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore not_a_digital_credentials_wallet: questa verifica non accetta una risposta da un wallet." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può verificare il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/response/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"response\": {\n \"protocol\": \"openid4vp-v1-signed\",\n \"data\": {\n \"response\": \"\"\n }\n }\n}'" } ] } }, "/v3/id-verification/wallets/google-wallet/": { "post": { "operationId": "start_google_wallet_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_google_wallet", "auth": "api_key", "server": true }, "description": "Avvia un accesso Google Wallet (Google Wallet (ID pass) ed emittenti statali degli Stati Uniti (patente di guida mobile); USA, GBR, BRA, SGP, TWN) senza alcun workflow. Fatturato una sola volta, solo quando l'identità viene verificata. La risposta contiene next_action.type=request_digital_credential con una richiesta firmata da Didit per la tua applicazione, utilizzabile solo dall'origine. In corrispondenza di un gesto dell'utente, passa next_action.digital_credentials.request a navigator.credentials.get({digital: ...}) (o ad Android Credential Manager come GetDigitalCredentialOption requestJson), quindi invia con POST ciò che il wallet restituisce a /v3/id-verification/wallets/verifications/{request_id}/response/. Il browser propone un proprio codice QR quando il wallet si trova su un altro dispositivo. Le applicazioni sandbox ottengono una simulazione deterministica (simulated: true) che non contatta mai il provider.", "summary": "Avvia la verifica Google Wallet", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "Chiave di sicurezza per i nuovi tentativi opzionale (max 255 caratteri). Un nuovo tentativo con la stessa chiave, wallet e corpo restituisce la verifica originale senza avviare un secondo accesso; la stessa chiave con un altro wallet o corpo restituisce 409 idempotency_key_reused." } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest" }, "example": { "country": "USA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "origin": "https://app.example.com" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "google_wallet", "name": "Google Wallet", "issuing_authority": "Google Wallet (ID pass) and US state issuers (mobile driving licence)" }, "country": "USA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "digital_credentials", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "request_digital_credential", "digital_credentials": { "protocol": "openid4vp-v1-signed", "request": { "requests": [ { "protocol": "openid4vp-v1-signed", "data": { "request": "" } } ] } } }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "Errori di validazione dei campi ({field: [messages]}), oppure errore return_url_invalid, return_url_not_allowed, origin_invalid, origin_not_allowed, invalid_personal_code, invalid_phone_number o idempotency_key_invalid." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "Credenziali mancanti ({detail}), oppure errore wallet_unavailable, insufficient_credits o contract_rate_missing." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore idempotency_key_reused o idempotency_key_in_progress (con Retry-After)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_provider_unavailable: non è stato possibile avviare il provider; non è stato creato nulla." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "errore wallet_not_configured: questo ambiente non può raggiungere il wallet." } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"USA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"origin\": \"https://app.example.com\"\n}'" } ], "x-didit-wallet-id": "google_wallet" } }, "/v3/session/{sessionId}/kyb/documents/": { "post": { "summary": "Carica i documenti KYB in una sessione", "description": "Carica uno o più documenti aziendali (atto costitutivo, libro dei soci, certificato di costituzione, ...) nel passaggio Documenti KYB di una sessione di Verifica aziendale (KYB), dal tuo server invece che dalla pagina ospitata. Didit esegue la pipeline ospitata: compressione, OCR, controlli di manomissione e di corrispondenza tra documenti, raggruppamento dei documenti e fa avanzare la sessione quando i gruppi di documenti richiesti sono soddisfatti. Il passaggio ha un costo fisso forfettario, indipendentemente dal numero di file inviati. La sessione deve essere aperta e trovarsi nel passaggio Documenti KYB, e l'azienda scelta nel passaggio del registro delle imprese deve esistere. Leggi le persone nominate nei documenti con `GET /v3/session/{sessionId}/kyb/extracted-parties/`. Richiede `write:businesses`.", "operationId": "post_v3_session_kyb_documents", "x-didit-sdk": { "resource": "sessions", "method": "upload_kyb_documents", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica aziendale (KYB). Deve appartenere all'applicazione della chiave API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nodo del workflow del passaggio KYB. Necessario solo quando il workflow contiene più di un nodo KYB; per impostazione predefinita Didit utilizza il nodo della sessione stessa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "File da caricare: JPG, JPEG, PNG, TIFF, WEBP, PDF o archivi ZIP contenenti questi formati. PDF fino a 50 MB, foto fino a 6 MB prima della compressione." }, "document_passwords": { "type": "array", "items": { "type": "string" }, "description": "Una voce per ciascun file in `documents`, nello stesso ordine: la password di un PDF protetto, vuota per qualsiasi altro file." }, "document_group": { "type": "string", "enum": [ "LEGAL_PRESENCE", "COMPANY_DETAILS", "OWNERSHIP_STRUCTURE", "REPRESENTATIVES_AUTHORIZATION" ], "description": "Gruppo di documenti richiesto a cui risponde questo caricamento." }, "locale": { "type": "string", "maxLength": 10, "description": "Locale utilizzato per tradurre la risposta del passaggio successivo." } } } } } }, "responses": { "200": { "description": "Documenti elaborati. Quando ogni gruppo obbligatorio è soddisfatto, la sessione avanza e `next_step` indica il passaggio successivo; altrimenti rimane nel passaggio Documenti e `document_groups` e `document_answer` indicano cosa manca ancora.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "next_step": { "type": "string", "nullable": true, "description": "Passaggio in cui si trova la sessione dopo il caricamento." }, "kyb_status": { "type": "string", "description": "Stato del controllo aziendale." }, "document_answer": { "type": "object", "additionalProperties": true, "description": "Risultato per ciascun documento caricato e caricamenti rimanenti." } }, "additionalProperties": true }, "example": { "valid": true, "next_step": "KYB_KEY_PEOPLE", "kyb_status": "In Progress" } } } }, "400": { "description": "Un documento è stato rifiutato (manomesso, illeggibile o non supportato) oppure la sessione non ha ancora un'azienda KYB. Riprova con un altro file finché restano tentativi disponibili.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "message": "No KYB company found. Submit company data first." } } } }, "402": { "description": "L'organizzazione non ha più credito residuo per il passaggio dei documenti.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "detail": "Insufficient credits." } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata, appartiene a un'altra applicazione o non rientra nei limiti di una chiave con ambito limitato; nessun dettaglio li distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "La sessione è terminata (`kyb_session_not_writable`) o non si trova nel passaggio Documenti KYB (`kyb_step_mismatch`, con `next_step` che indica il passaggio in cui si trova).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." }, "code": { "type": "string" }, "next_step": { "type": "string" } } }, "example": { "detail": "The session is not on the step this operation completes.", "code": "kyb_step_mismatch", "next_step": "KYB_REGISTRY" } } } }, "429": { "description": "Limite di frequenza superato: 300 richieste di scrittura (POST, PATCH, DELETE) al minuto per chiave API. Attendi i secondi indicati in `Retry-After` prima di riprovare; le intestazioni `X-RateLimit-*` indicano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.upload_kyb_documents(\n \"33333333-4444-5555-6666-777777777777\",\n documents=[open(\"document.pdf\", \"rb\")],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.uploadKybDocuments(\"33333333-4444-5555-6666-777777777777\", {\n documents: [await fileFromPath(\"document.pdf\")],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UploadKYBDocuments(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsUploadKYBDocumentsParams{\n\tDocuments: []didit.File{didit.FileFromPath(\"document.pdf\")},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUploadKybDocumentsParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().uploadKybDocuments(\"33333333-4444-5555-6666-777777777777\", SessionsUploadKybDocumentsParams.builder()\n .documents(List.of(Path.of(\"document.pdf\")))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->uploadKybDocuments('33333333-4444-5555-6666-777777777777', [\n 'documents' => [File::fromPath('document.pdf')],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.upload_kyb_documents(\n \"33333333-4444-5555-6666-777777777777\",\n documents: [Pathname(\"document.pdf\")]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UploadKybDocumentsAsync(\"33333333-4444-5555-6666-777777777777\", new SessionsUploadKybDocumentsParams\n{\n Documents = new FileUpload[] { FileUpload.FromPath(\"document.pdf\") },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/extracted-parties/": { "get": { "summary": "Elenca le parti indicate dai documenti caricati", "description": "Restituisce gli azionisti e gli amministratori menzionati nei documenti caricati in questa sessione KYB, aggregati per persona e attribuiti ai documenti che li indicano. Mostrali al richiedente per la conferma, quindi dichiarali con gli endpoint di bozza delle parti. Un intervallo rimane un intervallo: `ownership_percent.text` mantiene il valore testuale esatto e `min` / `max` i valori numerici ricavati da esso. Nessuno viene designato come UBO in questa fase; la determinazione avviene al momento dell'invio delle parti, in base alle impostazioni dei ruoli e alle soglie di assetto proprietario del workflow. Lo stesso elenco è presente nella decisione della sessione come `document_verifications[].extracted_parties`. Richiede `read:businesses` o `read:sessions`.", "operationId": "get_v3_session_kyb_extracted_parties", "x-didit-sdk": { "resource": "sessions", "method": "list_kyb_extracted_parties", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica aziendale (KYB). Deve appartenere all'applicazione della chiave API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nodo del workflow del passaggio KYB. Necessario solo quando il workflow contiene più di un nodo KYB; per impostazione predefinita Didit utilizza il nodo della sessione stessa.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Parti indicate dai documenti correnti.", "content": { "application/json": { "schema": { "type": "object", "required": [ "parties", "document_count" ], "properties": { "parties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "appointment_date": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "roles": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "ownership_percent": { "type": "object", "properties": { "text": { "type": "string", "nullable": true, "description": "La percentuale di proprietà esattamente come indicata nel documento, ad esempio `25-50%`, `>50%` o `NO EXHIBE`." }, "min": { "type": "number", "nullable": true, "description": "Numero inferiore letto da `text`; null se non ne indica alcuno." }, "max": { "type": "number", "nullable": true, "description": "Numero superiore letto da `text`; null se non ne indica nessuno." } } } } } }, "documents": { "type": "array", "description": "I documenti caricati in cui era indicata questa parte.", "items": { "type": "object", "properties": { "document_uuid": { "type": "string", "format": "uuid" }, "document_type": { "type": "string", "nullable": true }, "document_subtype": { "type": "string", "nullable": true }, "original_filename": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } } } } } }, "description": "Gli azionisti e gli amministratori indicati nei documenti caricati, unificati per persona. Nessuno è etichettato come UBO qui: questo viene deciso al momento dell'invio delle parti." }, "document_count": { "type": "integer", "description": "Numero di documenti caricati da cui è stato letto l'elenco." }, "node_id": { "type": "string", "nullable": true } } }, "example": { "parties": [ { "name": "Ana Lopez", "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "appointment_date": null, "designation": "Administrador unico", "roles": [ { "role": "shareholder", "ownership_percent": { "text": "60%", "min": 60, "max": 60 } } ], "documents": [ { "document_uuid": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41", "document_type": "OWNERSHIP_STRUCTURE", "document_subtype": "ARTICLES_OF_INCORPORATION", "original_filename": "acta_constitutiva.pdf", "status": "Approved" } ] } ], "document_count": 1, "node_id": "node_kyb_documents" } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata, appartiene a un'altra applicazione o non rientra nei limiti di una chiave con ambito limitato; nessun dettaglio li distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "detail": "Session not found." } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.list_kyb_extracted_parties(\n \"33333333-4444-5555-6666-777777777777\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listKybExtractedParties(\"33333333-4444-5555-6666-777777777777\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListKYBExtractedParties(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsListKYBExtractedPartiesParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().listKybExtractedParties(\"33333333-4444-5555-6666-777777777777\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listKybExtractedParties('33333333-4444-5555-6666-777777777777');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_kyb_extracted_parties(\"33333333-4444-5555-6666-777777777777\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListKybExtractedPartiesAsync(\"33333333-4444-5555-6666-777777777777\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/parties/drafts/": { "get": { "summary": "Elenca le bozze delle parti KYB", "description": "Elenca le parti che stai preparando per questa sessione KYB, dalla meno recente alla più recente. Una bozza non è una parte dichiarata: non compare nella decisione o nella console e non crea alcuna sessione di verifica finché non la invii con `POST /v3/session/{sessionId}/kyb/parties/submit/`. Richiede `write:businesses`.", "operationId": "get_v3_session_kyb_party_drafts", "x-didit-sdk": { "resource": "sessions", "method": "list_kyb_party_drafts", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica aziendale (KYB). Deve appartenere all'applicazione della chiave API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nodo del workflow del passaggio KYB. Necessario solo quando il workflow contiene più di un nodo KYB; per impostazione predefinita Didit utilizza il nodo della sessione stessa.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Le bozze salvate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "parties": { "type": "array", "items": { "type": "object", "required": [ "draft_id", "created_at", "updated_at", "party" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "party": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se la parte è una persona fisica o un'azienda." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo di una persona. Invia questo, oppure `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Ruolo ricoperto dalla parte. Intercambiabile con `roles`; quando vengono inviati entrambi, vengono uniti." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Ogni ruolo ricoperto dal soggetto. Una persona deve avere almeno un ruolo (qui o in `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Qualifica professionale di una persona." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome di una parte aziendale. Obbligatorio quando `entity_type` è `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Numero di registrazione di un soggetto aziendale." }, "email": { "type": "string", "format": "email", "description": "Dove viene inviato il link di verifica. Obbligatorio quando la parte deve completare la verifica, il che dipende dalle impostazioni del ruolo e dalle soglie dell'assetto proprietario del workflow." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Quota dell'azienda posseduta dal soggetto." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nazionalità di una persona fisica o paese di costituzione di un'azienda. Obbligatorio per ogni parte." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campi aggiuntivi definiti dal workflow." }, "skip_verification": { "type": "boolean", "default": false, "description": "Richiedi di saltare la verifica di questa parte. Applicato solo se il ruolo della parte consente di saltarla nelle impostazioni di Persone chiave del workflow." } } } } } }, "node_id": { "type": "string", "nullable": true } } }, "example": { "parties": [ { "draft_id": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d", "created_at": "2026-10-31T10:00:00Z", "updated_at": "2026-10-31T10:00:00Z", "party": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 60, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } ], "node_id": "node_kyb_key_people" } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata, appartiene a un'altra applicazione o non rientra nei limiti di una chiave con ambito limitato; nessun dettaglio li distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "detail": "Session not found." } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.list_kyb_party_drafts(\n \"33333333-4444-5555-6666-777777777777\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listKybPartyDrafts(\"33333333-4444-5555-6666-777777777777\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListKYBPartyDrafts(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsListKYBPartyDraftsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().listKybPartyDrafts(\"33333333-4444-5555-6666-777777777777\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listKybPartyDrafts('33333333-4444-5555-6666-777777777777');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_kyb_party_drafts(\"33333333-4444-5555-6666-777777777777\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListKybPartyDraftsAsync(\"33333333-4444-5555-6666-777777777777\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "post": { "summary": "Crea una bozza di controparte KYB", "description": "Aggiungi una parte (una persona o un'azienda) all'elenco che stai preparando per questa sessione KYB. Si applicano gli stessi campi e le stesse regole della schermata Persone chiave ospitata: per una persona sono necessari `full_name` oppure `first_name` e `last_name`, almeno un ruolo e una nazionalità; per un'azienda sono necessari `company_name` e il paese di costituzione in `nationality`. Nulla viene dichiarato o fatturato fino alla chiamata `POST /v3/session/{sessionId}/kyb/parties/submit/`. Richiede `write:businesses`.", "operationId": "post_v3_session_kyb_party_drafts", "x-didit-sdk": { "resource": "sessions", "method": "create_kyb_party_draft", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica aziendale (KYB). Deve appartenere all'applicazione della chiave API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nodo del workflow del passaggio KYB. Necessario solo quando il workflow contiene più di un nodo KYB; per impostazione predefinita Didit utilizza il nodo della sessione stessa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se la parte è una persona fisica o un'azienda." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo di una persona. Invia questo, oppure `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Ruolo ricoperto dalla parte. Intercambiabile con `roles`; quando vengono inviati entrambi, vengono uniti." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Ogni ruolo ricoperto dal soggetto. Una persona deve avere almeno un ruolo (qui o in `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Qualifica professionale di una persona." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome di una parte aziendale. Obbligatorio quando `entity_type` è `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Numero di registrazione di un soggetto aziendale." }, "email": { "type": "string", "format": "email", "description": "Dove viene inviato il link di verifica. Obbligatorio quando la parte deve completare la verifica, il che dipende dalle impostazioni del ruolo e dalle soglie dell'assetto proprietario del workflow." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Quota dell'azienda posseduta dal soggetto." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nazionalità di una persona fisica o paese di costituzione di un'azienda. Obbligatorio per ogni parte." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campi aggiuntivi definiti dal workflow." }, "skip_verification": { "type": "boolean", "default": false, "description": "Richiedi di saltare la verifica di questa parte. Applicato solo se il ruolo della parte consente di saltarla nelle impostazioni di Persone chiave del workflow." } } }, "example": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 60, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } } }, "responses": { "201": { "description": "Bozza creata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_id", "created_at", "updated_at", "party" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "party": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se la parte è una persona fisica o un'azienda." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo di una persona. Invia questo, oppure `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Ruolo ricoperto dalla parte. Intercambiabile con `roles`; quando vengono inviati entrambi, vengono uniti." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Ogni ruolo ricoperto dal soggetto. Una persona deve avere almeno un ruolo (qui o in `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Qualifica professionale di una persona." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome di una parte aziendale. Obbligatorio quando `entity_type` è `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Numero di registrazione di un soggetto aziendale." }, "email": { "type": "string", "format": "email", "description": "Dove viene inviato il link di verifica. Obbligatorio quando la parte deve completare la verifica, il che dipende dalle impostazioni del ruolo e dalle soglie dell'assetto proprietario del workflow." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Quota dell'azienda posseduta dal soggetto." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nazionalità di una persona fisica o paese di costituzione di un'azienda. Obbligatorio per ogni parte." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campi aggiuntivi definiti dal workflow." }, "skip_verification": { "type": "boolean", "default": false, "description": "Richiedi di saltare la verifica di questa parte. Applicato solo se il ruolo della parte consente di saltarla nelle impostazioni di Persone chiave del workflow." } } } } }, "example": { "draft_id": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d", "created_at": "2026-10-31T10:00:00Z", "updated_at": "2026-10-31T10:00:00Z", "party": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 60, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } } } }, "400": { "description": "Un campo relativo a una parte non è valido o manca un campo obbligatorio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "non_field_errors": [ "Person parties require at least one role." ] } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata, appartiene a un'altra applicazione o non rientra nei limiti di una chiave con ambito limitato; nessun dettaglio li distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "La sessione è terminata (`kyb_session_not_writable`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." }, "code": { "type": "string" } } }, "example": { "detail": "This verification session is no longer accepting changes.", "code": "kyb_session_not_writable" } } } }, "429": { "description": "Limite di frequenza superato: 300 richieste di scrittura (POST, PATCH, DELETE) al minuto per chiave API. Attendi i secondi indicati in `Retry-After` prima di riprovare; le intestazioni `X-RateLimit-*` indicano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.create_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n entity_type=\"person\",\n first_name=\"Ana\",\n last_name=\"Lopez\",\n roles=[\"ubo\", \"director\"],\n date_of_birth=\"1984-06-12\",\n email=\"ana.lopez@example.com\",\n ownership_percent=60.0,\n nationality=\"MEX\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.createKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", {\n entity_type: \"person\",\n first_name: \"Ana\",\n last_name: \"Lopez\",\n roles: [\"ubo\", \"director\"],\n date_of_birth: \"1984-06-12\",\n email: \"ana.lopez@example.com\",\n ownership_percent: 60.0,\n nationality: \"MEX\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.CreateKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsCreateKYBPartyDraftParams{\n\tEntityType: \"person\",\n\tFirstName: didit.String(\"Ana\"),\n\tLastName: didit.String(\"Lopez\"),\n\tRoles: didit.Some([]didit.SessionsCreateKYBPartyDraftParamsRoles{\"ubo\", \"director\"}),\n\tDateOfBirth: didit.String(\"1984-06-12\"),\n\tEmail: didit.String(\"ana.lopez@example.com\"),\n\tOwnershipPercent: didit.Float(60.0),\n\tNationality: \"MEX\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsCreateKybPartyDraftParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().createKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", SessionsCreateKybPartyDraftParams.builder()\n .entityType(SessionsCreateKybPartyDraftParams.EntityType.of(\"person\"))\n .firstName(\"Ana\")\n .lastName(\"Lopez\")\n .roles(List.of(SessionsCreateKybPartyDraftParams.Roles.of(\"ubo\"), SessionsCreateKybPartyDraftParams.Roles.of(\"director\")))\n .dateOfBirth(LocalDate.parse(\"1984-06-12\"))\n .email(\"ana.lopez@example.com\")\n .ownershipPercent(60.0)\n .nationality(\"MEX\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->createKybPartyDraft('33333333-4444-5555-6666-777777777777', [\n 'entity_type' => 'person',\n 'first_name' => 'Ana',\n 'last_name' => 'Lopez',\n 'roles' => ['ubo', 'director'],\n 'date_of_birth' => '1984-06-12',\n 'email' => 'ana.lopez@example.com',\n 'ownership_percent' => 60.0,\n 'nationality' => 'MEX',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.create_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n entity_type: \"person\",\n first_name: \"Ana\",\n last_name: \"Lopez\",\n roles: [\"ubo\", \"director\"],\n date_of_birth: \"1984-06-12\",\n email: \"ana.lopez@example.com\",\n ownership_percent: 60.0,\n nationality: \"MEX\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.CreateKybPartyDraftAsync(\"33333333-4444-5555-6666-777777777777\", new SessionsCreateKybPartyDraftParams\n{\n EntityType = \"person\",\n FirstName = \"Ana\",\n LastName = \"Lopez\",\n Roles = new SessionsCreateKybPartyDraftParamsRoles[] { \"ubo\", \"director\" },\n DateOfBirth = \"1984-06-12\",\n Email = \"ana.lopez@example.com\",\n OwnershipPercent = 60.0,\n Nationality = \"MEX\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/parties/drafts/{draftId}/": { "patch": { "summary": "Modifica una bozza di parte KYB", "description": "Modifica i campi della bozza di una parte. La modifica viene unita alla bozza memorizzata e la parte combinata viene validata nel suo complesso, pertanto una modifica che lascerebbe la parte incompleta viene rifiutata. La modifica di `first_name` o `last_name` sostituisce il nome completo memorizzato. Richiede `write:businesses`.", "operationId": "patch_v3_session_kyb_party_draft", "x-didit-sdk": { "resource": "sessions", "method": "update_kyb_party_draft", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica aziendale (KYB). Deve appartenere all'applicazione della chiave API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "draftId", "in": "path", "required": true, "description": "UUID della bozza della controparte (`draft_id` restituito al momento della creazione).", "schema": { "type": "string", "format": "uuid", "example": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nodo del workflow del passaggio KYB. Necessario solo quando il workflow contiene più di un nodo KYB; per impostazione predefinita Didit utilizza il nodo della sessione stessa.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Qualsiasi sottoinsieme dei campi della parte. La modifica viene unita alla bozza memorizzata e la parte risultante dall'unione viene convalidata nel suo complesso; pertanto, una bozza che poteva essere inviata prima di una modifica può ancora essere inviata dopo di essa.", "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se la parte è una persona fisica o un'azienda." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo di una persona. Invia questo, oppure `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Ruolo ricoperto dalla parte. Intercambiabile con `roles`; quando vengono inviati entrambi, vengono uniti." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Ogni ruolo ricoperto dal soggetto. Una persona deve avere almeno un ruolo (qui o in `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Qualifica professionale di una persona." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome di una parte aziendale. Obbligatorio quando `entity_type` è `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Numero di registrazione di un soggetto aziendale." }, "email": { "type": "string", "format": "email", "description": "Dove viene inviato il link di verifica. Obbligatorio quando la parte deve completare la verifica, il che dipende dalle impostazioni del ruolo e dalle soglie dell'assetto proprietario del workflow." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Quota dell'azienda posseduta dal soggetto." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nazionalità di una persona fisica o paese di costituzione di un'azienda. Obbligatorio per ogni parte." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campi aggiuntivi definiti dal workflow." }, "skip_verification": { "type": "boolean", "default": false, "description": "Richiedi di saltare la verifica di questa parte. Applicato solo se il ruolo della parte consente di saltarla nelle impostazioni di Persone chiave del workflow." } } }, "example": { "ownership_percent": 55 } } } }, "responses": { "200": { "description": "Bozza aggiornata.", "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_id", "created_at", "updated_at", "party" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "party": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se la parte è una persona fisica o un'azienda." }, "full_name": { "type": "string", "maxLength": 255, "description": "Nome completo di una persona. Invia questo, oppure `first_name` e `last_name`." }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Ruolo ricoperto dalla parte. Intercambiabile con `roles`; quando vengono inviati entrambi, vengono uniti." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "Ogni ruolo ricoperto dal soggetto. Una persona deve avere almeno un ruolo (qui o in `role`)." }, "position": { "type": "string", "maxLength": 128, "description": "Qualifica professionale di una persona." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "Nome di una parte aziendale. Obbligatorio quando `entity_type` è `company`." }, "registration_number": { "type": "string", "maxLength": 100, "description": "Numero di registrazione di un soggetto aziendale." }, "email": { "type": "string", "format": "email", "description": "Dove viene inviato il link di verifica. Obbligatorio quando la parte deve completare la verifica, il che dipende dalle impostazioni del ruolo e dalle soglie dell'assetto proprietario del workflow." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Quota dell'azienda posseduta dal soggetto." }, "nationality": { "type": "string", "maxLength": 100, "description": "Nazionalità di una persona fisica o paese di costituzione di un'azienda. Obbligatorio per ogni parte." }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campi aggiuntivi definiti dal workflow." }, "skip_verification": { "type": "boolean", "default": false, "description": "Richiedi di saltare la verifica di questa parte. Applicato solo se il ruolo della parte consente di saltarla nelle impostazioni di Persone chiave del workflow." } } } } }, "example": { "draft_id": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d", "created_at": "2026-10-31T10:00:00Z", "updated_at": "2026-10-31T10:00:00Z", "party": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 55, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } } } }, "400": { "description": "La parte aggregata non è valida.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "non_field_errors": [ "Person parties require at least one role." ] } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione o la bozza non esiste, oppure la sessione non appartiene all'applicazione associata alla chiave o non rientra nei limiti di una chiave con ambito limitato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "La sessione è terminata (`kyb_session_not_writable`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." }, "code": { "type": "string" } } }, "example": { "detail": "This verification session is no longer accepting changes.", "code": "kyb_session_not_writable" } } } }, "429": { "description": "Limite di frequenza superato: 300 richieste di scrittura (POST, PATCH, DELETE) al minuto per chiave API. Attendi i secondi indicati in `Retry-After` prima di riprovare; le intestazioni `X-RateLimit-*` indicano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n ownership_percent=55.0,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateKybPartyDraft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n {\n ownership_percent: 55.0,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", didit.SessionsUpdateKYBPartyDraftParams{\n\tOwnershipPercent: didit.Float(55.0),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateKybPartyDraftParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", SessionsUpdateKybPartyDraftParams.builder()\n .ownershipPercent(55.0)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateKybPartyDraft('33333333-4444-5555-6666-777777777777', '5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d', [\n 'ownership_percent' => 55.0,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n ownership_percent: 55.0\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateKybPartyDraftAsync(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", new SessionsUpdateKybPartyDraftParams\n{\n OwnershipPercent = 55.0,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "Elimina una bozza di soggetto KYB", "description": "Elimina la bozza di una parte. Le parti dichiarate non sono interessate. Richiede `write:businesses`.", "operationId": "delete_v3_session_kyb_party_draft", "x-didit-sdk": { "resource": "sessions", "method": "delete_kyb_party_draft", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica aziendale (KYB). Deve appartenere all'applicazione della chiave API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "draftId", "in": "path", "required": true, "description": "UUID della bozza della controparte (`draft_id` restituito al momento della creazione).", "schema": { "type": "string", "format": "uuid", "example": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nodo del workflow del passaggio KYB. Necessario solo quando il workflow contiene più di un nodo KYB; per impostazione predefinita Didit utilizza il nodo della sessione stessa.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Bozza eliminata. Nessun contenuto." }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione o la bozza non esiste, oppure la sessione non appartiene all'applicazione associata alla chiave o non rientra nei limiti di una chiave con ambito limitato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "La sessione è terminata (`kyb_session_not_writable`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." }, "code": { "type": "string" } } }, "example": { "detail": "This verification session is no longer accepting changes.", "code": "kyb_session_not_writable" } } } }, "429": { "description": "Limite di frequenza superato: 300 richieste di scrittura (POST, PATCH, DELETE) al minuto per chiave API. Attendi i secondi indicati in `Retry-After` prima di riprovare; le intestazioni `X-RateLimit-*` indicano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.sessions.delete_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.sessions.deleteKybPartyDraft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Sessions.DeleteKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", didit.SessionsDeleteKYBPartyDraftParams{}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().deleteKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\");" }, { "lang": "php", "label": "PHP", "source": "sessions->deleteKybPartyDraft('33333333-4444-5555-6666-777777777777', '5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.delete_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Sessions.DeleteKybPartyDraftAsync(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\");" } ] } }, "/v3/session/{sessionId}/kyb/parties/submit/": { "post": { "summary": "Invia le bozze delle parti KYB", "description": "Dichiara le bozze salvate come persone chiave dell'azienda. Questo è il passaggio Persone chiave ospitato con la tua chiave API: Didit decide, in base alle impostazioni dei ruoli e alle soglie dell'assetto proprietario del workflow, quali soggetti devono essere verificati, crea una sessione KYC individuale (o una sotto-sessione KYB per un titolare societario) per ciascuno di essi, invia le email richieste dal workflow e fa avanzare la sessione. Ogni sessione figlia viene fatturata come nel flusso ospitato. Le bozze vengono consumate. Ripetere la chiamata dopo un invio riuscito non modifica nulla e risponde con `200`, `already_submitted: true` e i soggetti già esistenti. La sessione deve trovarsi nel passaggio Persone chiave. Invia a ciascuna persona il proprio `kyc_session_url` oppure incorporalo. Richiede `write:businesses`.", "operationId": "post_v3_session_kyb_parties_submit", "x-didit-sdk": { "resource": "sessions", "method": "submit_kyb_parties", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di Verifica aziendale (KYB). Deve appartenere all'applicazione della chiave API.", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "Nodo del workflow del passaggio KYB. Necessario solo quando il workflow contiene più di un nodo KYB; per impostazione predefinita Didit utilizza il nodo della sessione stessa.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "maxLength": 10, "description": "Locale utilizzato per tradurre la risposta del passaggio a cui avanza la sessione." } } }, "example": { "locale": "es" } } } }, "responses": { "200": { "description": "Parti dichiarate (o già dichiarate).", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "next_step": { "type": "string", "nullable": true, "description": "Passaggio in cui si trova la sessione." }, "status": { "type": "string", "description": "Stato della sessione aziendale." }, "advanced": { "type": "boolean", "description": "`true` quando questa chiamata ha dichiarato le parti e ha fatto avanzare la sessione." }, "already_submitted": { "type": "boolean", "description": "`true` quando le parti erano state dichiarate da una chiamata precedente." }, "kyb_key_people_status": { "type": "string" }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/KYBKeyPeopleParty" } } } }, "example": { "valid": true, "next_step": "FINISHED", "status": "In Progress", "advanced": true, "already_submitted": false, "kyb_key_people_status": "In Progress", "parties": [] } } } }, "402": { "description": "L'organizzazione non ha più credito residuo per le sessioni di verifica secondarie.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "detail": "Insufficient credits." } } } }, "401": { "description": "La chiave API con ambito è scaduta. Questo è l'unico caso che restituisce `401`: una chiave mancante, non valida o revocata restituisce `403`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Expired key": { "summary": "La data di scadenza della chiave è stata superata", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "Errore di autenticazione o autorizzazione. Una chiave mancante restituisce `403`, così come la chiave di un'altra applicazione, una chiave con ambito limitato priva dell'autorizzazione necessaria per questo endpoint e una richiesta proveniente dall'esterno dell'allowlist IP della chiave; una chiave errata, revocata o scaduta restituisce `401`. Distinguili tramite `detail`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Missing or invalid credentials": { "summary": "Nessuna intestazione x-api-key, oppure validazione della chiave non riuscita", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "Una chiave valida appartenente a un'applicazione diversa da quella della sessione", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "La chiave con ambito non dispone di decisions: write", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "Richiesta proveniente da un indirizzo esterno all'allowlist degli IP della chiave", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "La sessione non esiste, è stata eliminata, appartiene a un'altra applicazione o non rientra nei limiti di una chiave con ambito limitato; nessun dettaglio li distingue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "`kyb_no_party_drafts`: non c'è nulla da inviare. `kyb_parties_already_submitted`: le bozze sono state aggiunte dopo che le parti sono state dichiarate. `kyb_step_mismatch`: la sessione non si trova nel passaggio Persone chiave (`next_step` indica il relativo passaggio). `kyb_session_not_writable`: la sessione è conclusa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." }, "code": { "type": "string" }, "next_step": { "type": "string" } } }, "example": { "detail": "There are no draft parties to submit.", "code": "kyb_no_party_drafts" } } } }, "429": { "description": "Limite di frequenza superato: 300 richieste di scrittura (POST, PATCH, DELETE) al minuto per chiave API. Attendi i secondi indicati in `Retry-After` prima di riprovare; le intestazioni `X-RateLimit-*` indicano il budget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di errore di facile lettura." } } }, "examples": { "Rate limited": { "summary": "Budget per il minuto corrente esaurito", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "Secondi da attendere prima di effettuare un nuovo tentativo.", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.submit_kyb_parties(\n \"33333333-4444-5555-6666-777777777777\",\n locale=\"es\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.submitKybParties(\"33333333-4444-5555-6666-777777777777\", {\n locale: \"es\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.SubmitKYBParties(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsSubmitKYBPartiesParams{\n\tLocale: didit.String(\"es\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsSubmitKybPartiesParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().submitKybParties(\"33333333-4444-5555-6666-777777777777\", SessionsSubmitKybPartiesParams.builder()\n .locale(\"es\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->submitKybParties('33333333-4444-5555-6666-777777777777', [\n 'locale' => 'es',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.submit_kyb_parties(\n \"33333333-4444-5555-6666-777777777777\",\n locale: \"es\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.SubmitKybPartiesAsync(\"33333333-4444-5555-6666-777777777777\", new SessionsSubmitKybPartiesParams\n{\n Locale = \"es\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/files-export/": { "post": { "summary": "Esportare tutti i file di una sessione", "description": "Avvia la preparazione di uno ZIP con ogni immagine, video e documento di una sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB), in qualità originale: i file vengono archiviati nello ZIP così come sono stati acquisiti, mai ricompressi. Risponde `202` con l'esportazione; leggila con `GET /v3/session/{sessionId}/files-export/{exportId}/` finché lo `status` non è `READY`, quindi scarica `download_url`. Mentre un'esportazione della stessa sessione è ancora in preparazione, viene restituita quell'esportazione anziché una nuova.\n\nLo ZIP viene eliminato 24 ore dopo essere pronto, e immediatamente quando la sessione viene eliminata. Una sessione eliminata non può essere esportata. Ogni esportazione e ogni link di download rilasciato vengono registrati nel registro di audit della sessione. Una chiave API con ambito limitato richiede `media: read` e `decisions: read`; un utente della console ha bisogno dell'autorizzazione per leggere le sessioni.", "operationId": "post_v3_session_files_export", "x-didit-sdk": { "resource": "sessions", "method": "export_files", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica (il `session_id` restituito da `POST /v3/session/`). Accetta sia ID di sessione di Verifica degli utenti (KYC) sia di Verifica aziendale (KYB). Una sessione eliminata restituisce `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/files-export/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.export_files(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.exportFiles(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ExportFiles(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().exportFiles(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->exportFiles('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.export_files(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ExportFilesAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "202": { "description": "L'esportazione, in fase di preparazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFilesExport" }, "example": { "export_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "session_id": "11111111-2222-3333-4444-555555555555", "status": "PENDING", "file_count": null, "size_bytes": null, "download_url": null, "expires_at": null, "error": null, "created_at": "2026-10-29T12:00:03Z", "completed_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/files-export/{exportId}/": { "get": { "summary": "Recupera un'esportazione dei file di sessione", "description": "Avanzamento di un'esportazione avviata con `POST /v3/session/{sessionId}/files-export/`. Quando `status` è `READY`, `download_url` è un URL firmato dello ZIP che rimane valido per breve tempo; leggi nuovamente l'esportazione per riceverne uno nuovo fino a `expires_at`. Ciascuna lettura che fornisce un link per il download viene registrata nel registro di audit della sessione. L'esportazione di una sessione eliminata restituisce `404`.", "operationId": "get_v3_session_files_export", "x-didit-sdk": { "resource": "sessions", "method": "get_files_export", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "UUID della sessione di verifica (il `session_id` restituito da `POST /v3/session/`). Accetta sia ID di sessione di Verifica degli utenti (KYC) sia di Verifica aziendale (KYB). Una sessione eliminata restituisce `404`.", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "exportId", "in": "path", "required": true, "description": "L'`export_id` restituito da `POST /v3/session/{sessionId}/files-export/`.", "schema": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/files-export/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.get_files_export(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.getFilesExport(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.GetFilesExport(ctx, \"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().getFilesExport(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->getFilesExport('11111111-2222-3333-4444-555555555555', 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.get_files_export(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.GetFilesExportAsync(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "L'esportazione.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFilesExport" }, "example": { "export_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "session_id": "11111111-2222-3333-4444-555555555555", "status": "READY", "file_count": 9, "size_bytes": 18734120, "download_url": "https://storage.example.com/session/11111111-2222-3333-4444-555555555555/files-export/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/session-42-files.zip?X-Amz-Signature=...", "expires_at": "2026-10-30T12:00:41Z", "error": null, "created_at": "2026-10-29T12:00:03Z", "completed_at": "2026-10-29T12:00:41Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/travel-rule/unmatched/": { "get": { "summary": "Elenca i depositi Travel Rule non abbinati", "description": "Depositi in entrata ancora in attesa dei dati Travel Rule del VASP ordinante: il loro trasferimento è `AWAITING_COUNTERPARTY`, `NOT_ENOUGH_COUNTERPARTY_DATA` o `COUNTERPARTY_VASP_NOT_FOUND`, nessun messaggio ricevuto è associato ad essi e nessuno li ha abbinati manualmente. Le righe e i filtri sono gli stessi di `GET /v3/travel-rule/transfers/`, dal più recente al meno recente, con paginazione tramite `limit` (predefinito 50) e `offset`. Abbina un deposito al messaggio inviato dal VASP ordinante con `POST /v3/travel-rule/unmatched/{transaction_uuid}/match/`.", "operationId": "listUnmatchedTravelRuleDeposits", "x-didit-sdk": { "resource": "travel_rule.unmatched_deposits", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "INBOUND, OUTBOUND o entrambi separati da virgola. Distingue tra maiuscole e minuscole." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Uno o più stati di trasferimento, separati da virgola." }, { "name": "rail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Uno o più tra INTERNAL, TRP, GTR, TRUST, VERIFYVASP, SYGNA, EMAIL, TEST_VASP, separati da virgola." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "withdrawal, deposit o message, separati da virgola." }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "La valuta della transazione, senza distinzione tra maiuscole e minuscole." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Trasferimenti creati a partire da questo giorno incluso (UTC), YYYY-MM-DD." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Trasferimenti creati entro questo giorno incluso (UTC), YYYY-MM-DD." }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "L'`id` di una voce della directory o di un membro della rete Didit da GET /v3/travel-rule/vasps/: i tuoi trasferimenti con tale controparte. Un valore che non è un id valido risponde con 400." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "description": "Dimensione della pagina, valore predefinito 50." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "description": "Righe da saltare." } ], "responses": { "200": { "description": "Una pagina di depositi senza corrispondenza.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleTransferRow" } } } }, "example": { "count": 1, "next": null, "previous": null, "results": [ { "id": "7d3a1c55-0b9e-4d52-8a3c-1f6e2b9d4a08", "transaction_id": "c41f9b2e-5a8d-4e0c-9f17-3b6d8a2e5c91", "txn_id": "dep-2026-10-20-0007", "txn_date": "2026-10-19T08:41:12Z", "kind": "deposit", "direction": "INBOUND", "status": "AWAITING_COUNTERPARTY", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": null, "deadline_at": null, "created_at": "2026-10-19T08:41:13Z" } ] } } } }, "400": { "description": "Il valore di un filtro non è valido.", "content": { "application/json": { "example": { "start_date": [ "Use the YYYY-MM-DD format." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.unmatched_deposits.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.unmatchedDeposits.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.UnmatchedDeposits.ListAutoPaging(ctx, didit.TravelRuleUnmatchedDepositsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().unmatchedDeposits().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->unmatchedDeposits->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.unmatched_deposits.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.UnmatchedDeposits.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/travel-rule/unmatched/{transaction_uuid}/match/": { "post": { "summary": "Abbina un deposito Travel Rule a un messaggio ricevuto", "operationId": "matchUnmatchedTravelRuleDeposit", "x-didit-sdk": { "resource": "travel_rule.unmatched_deposits", "method": "match", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "description": "Associa un deposito in entrata ancora in attesa dei dati dell'ordinante al messaggio Travel Rule che il VASP ordinante ha inviato per esso. Il deposito acquisisce i dati dell'ordinante, il VASP di controparte e il canale del messaggio, ed entrambi i trasferimenti registrano la corrispondenza sulle rispettive cronologie. `transaction_uuid` è il `transaction_id` del deposito da `GET /v3/travel-rule/unmatched/`. `transaction_id` nel corpo è il `transaction_id` del messaggio ricevuto, da una riga di `GET /v3/travel-rule/transfers/?kind=message`; l'`id` del trasferimento stesso non viene trovato. Il messaggio deve riguardare lo stesso asset del deposito. Un deposito o un messaggio eliminato dalla Console restituisce `404`; uno che è già avanzato (associato o non più in attesa) restituisce `409`.", "parameters": [ { "name": "transaction_uuid", "in": "path", "required": true, "description": "Il `transaction_id` del deposito non abbinato.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleManualMatchRequest" }, "example": { "transaction_id": "e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24" } } } }, "responses": { "200": { "description": "Entrambi i trasferimenti dopo la corrispondenza.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleManualMatchResponse" }, "example": { "deposit": { "id": "7d3a1c55-0b9e-4d52-8a3c-1f6e2b9d4a08", "transaction_id": "c41f9b2e-5a8d-4e0c-9f17-3b6d8a2e5c91", "txn_id": "dep-2026-10-20-0007", "txn_date": "2026-10-19T08:41:12Z", "kind": "deposit", "direction": "INBOUND", "status": "AWAITING_COUNTERPARTY", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "Example Counterparty VASP", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": "e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24", "deadline_at": null, "created_at": "2026-10-19T08:41:13Z" }, "message": { "id": "2b8e6f10-9c3a-47d1-b5e2-0a4c7d9f3e66", "transaction_id": "e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24", "txn_id": "msg-2026-10-20-0003", "txn_date": "2026-10-19T08:41:12Z", "kind": "message", "direction": "INBOUND", "status": "COMPLETED", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "Origin CASP SL", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": null, "deadline_at": "2026-10-21T08:41:13Z", "created_at": "2026-10-19T08:41:13Z" } } } } }, "400": { "description": "Errore di validazione: `transaction_id` è mancante, corrisponde al deposito stesso, non è un messaggio Travel Rule ricevuto o si riferisce a un asset diverso rispetto al deposito; oppure la transazione nel percorso non è un deposito in entrata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Error": { "value": { "transaction_id": [ "The travel rule message is for a different asset than the deposit." ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Deposito o messaggio sconosciuto, oppure uno di essi è stato eliminato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No TravelRuleTransfer matches the given query." } } } }, "409": { "description": "Il deposito non è più in attesa dei dati dell'ordinante, oppure il messaggio è già associato a un deposito.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Error": { "value": { "detail": "This deposit is no longer waiting for originator data." } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.unmatched_deposits.match(\n \"11111111-2222-3333-4444-555555555555\",\n transaction_id=\"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.unmatchedDeposits.match(\"11111111-2222-3333-4444-555555555555\", {\n transaction_id: \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.UnmatchedDeposits.Match(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleManualMatchRequest{\n\tTransactionID: \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleManualMatchRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().unmatchedDeposits().match(\"11111111-2222-3333-4444-555555555555\", TravelRuleManualMatchRequest.builder()\n .transactionId(\"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->unmatchedDeposits->match('11111111-2222-3333-4444-555555555555', [\n 'transaction_id' => 'e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.unmatched_deposits.match(\n \"11111111-2222-3333-4444-555555555555\",\n transaction_id: \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.UnmatchedDeposits.MatchAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleManualMatchRequest\n{\n TransactionId = \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } } }, "components": { "schemas": { "DocumentAIDetectedCode": { "type": "object", "required": [ "type", "page_number", "position", "x", "y", "width", "height", "page_width", "page_height", "raw_payload", "parsed_payload" ], "properties": { "type": { "type": "string", "description": "Simbologia rilevata, ad esempio `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` o `PDF_417`." }, "page_number": { "type": "integer", "minimum": 1, "description": "Numero di pagina a partire da 1." }, "position": { "type": "array", "nullable": true, "description": "Poligono rilevato nelle coordinate in pixel della pagina renderizzata. `null` quando non è disponibile alcuna posizione affidabile.", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "integer" } } }, "x": { "type": "integer", "nullable": true, "description": "Bordo sinistro del riquadro di delimitazione in pixel della pagina renderizzata." }, "y": { "type": "integer", "nullable": true, "description": "Bordo superiore del riquadro di delimitazione in pixel della pagina renderizzata." }, "width": { "type": "integer", "nullable": true, "description": "Larghezza del riquadro di delimitazione in pixel della pagina renderizzata." }, "height": { "type": "integer", "nullable": true, "description": "Altezza del riquadro di delimitazione in pixel della pagina renderizzata." }, "page_width": { "type": "integer", "description": "Larghezza della pagina renderizzata in pixel." }, "page_height": { "type": "integer", "description": "Altezza della pagina renderizzata in pixel." }, "raw_payload": { "type": "string", "description": "Payload non elaborato del decodificatore come stringa base64 quando disponibile; altrimenti una stringa vuota." }, "parsed_payload": { "nullable": true, "description": "Stringa decodificata o valore strutturato. `null` quando il codice è stato individuato ma non è stato possibile decodificarlo." } } }, "SessionImportJob": { "type": "object", "required": [ "uuid", "status", "import_type", "source_format", "source_filename", "total_rows", "processed_rows", "created_count", "updated_count", "skipped_count", "failed_count" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID del processo di importazione. Usa questo valore per verificare lo stato di avanzamento e recuperare gli errori delle righe." }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "PAUSED", "CANCELLED", "READY" ] }, "import_type": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ] }, "source_format": { "type": "string", "enum": [ "csv", "ndjson" ] }, "source_filename": { "type": "string" }, "total_rows": { "type": "integer", "format": "int64" }, "processed_rows": { "type": "integer", "format": "int64" }, "checkpoint_row": { "type": "integer", "format": "int64" }, "created_count": { "type": "integer", "format": "int64" }, "updated_count": { "type": "integer", "format": "int64" }, "skipped_count": { "type": "integer", "format": "int64" }, "failed_count": { "type": "integer", "format": "int64" }, "total_media_bytes": { "type": "integer", "format": "int64" }, "last_error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "state": { "type": "string", "enum": [ "ready", "queued", "running", "paused", "completed", "errors", "failed", "cancelled" ], "description": "Lo stato del job così come mostrato nella console; `errors` corrisponde a un job completato con righe rifiutate." }, "source": { "type": "string", "enum": [ "file", "api", "provider" ] }, "provider": { "type": "string", "description": "Origine della migrazione; vuota per un'importazione da file o API." }, "provider_options": { "type": "object" }, "credential_hint": { "type": "string", "description": "I primi caratteri della chiave contenuta nella migrazione. La chiave stessa non viene mai restituita." }, "credentials_expires_at": { "type": "string", "format": "date-time", "nullable": true }, "resumes_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando un processo sospeso a causa del limite di frequenza del provider riprende automaticamente." }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "is_dry_run": { "type": "boolean" }, "dry_run_summary": { "type": "object", "description": "Risultati di una simulazione (dry run): `total`, `by_status`, `already_in_didit`, `same_person`, `not_finished`, `failed`, `unmapped_statuses`." }, "face_templates_enabled": { "type": "boolean" }, "lawful_basis_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "not_finished_count": { "type": "integer", "format": "int64" }, "same_person_count": { "type": "integer", "format": "int64" }, "face_templates_count": { "type": "integer", "format": "int64" }, "face_duplicates_count": { "type": "integer", "format": "int64" }, "face_blocklist_hits_count": { "type": "integer", "format": "int64" }, "created_by_name": { "type": "string", "nullable": true }, "created_by_email": { "type": "string", "nullable": true } } }, "SessionImportError": { "type": "object", "required": [ "uuid", "row_number", "error", "raw_row" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "row_number": { "type": "integer", "format": "int64" }, "external_id": { "type": "string", "nullable": true }, "error": { "type": "string" }, "raw_row": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "BrandingCustomizationUpdate": { "type": "object", "description": "Corpo di aggiornamento parziale del branding. Fornisci solo i campi che desideri modificare. I colori esadecimali accettano `#RRGGBB` o `#RRGGBBAA`. Il dominio personalizzato e l'email white label non sono accettati qui.", "properties": { "color_primary": { "type": "string", "description": "Colore delle intestazioni / del testo principale." }, "color_secondary": { "type": "string", "description": "Colore del testo secondario / dei paragrafi." }, "color_background": { "type": "string", "description": "Colore di sfondo della pagina." }, "color_panel": { "type": "string", "description": "Colore del pannello / accento." }, "color_panel_10": { "type": "string", "description": "Colore del pannello al 10% di opacità." }, "color_on_panel_1": { "type": "string", "description": "Colore del testo di supporto sui pannelli." }, "color_on_panel_2": { "type": "string", "description": "Colore del badge sui pannelli." }, "color_on_background": { "type": "string", "description": "Colore del testo sullo sfondo." }, "color_button_1": { "type": "string", "description": "Colore del pulsante principale." }, "color_button_2": { "type": "string", "description": "Colore del pulsante secondario." }, "color_button_text_1": { "type": "string", "description": "Colore del testo del pulsante principale." }, "color_button_text_2": { "type": "string", "description": "Colore del testo del pulsante secondario." }, "color_pill_text": { "type": "string", "description": "Colore del testo per pill, campi di input e selettori." }, "border_radius_panel": { "type": "integer", "minimum": 0, "description": "Raggio degli angoli del pannello in pixel." }, "border_radius_buttons": { "type": "integer", "minimum": 0, "description": "Raggio dell'angolo del pulsante in pixel." }, "font_family": { "type": "string", "description": "Nome della famiglia di Google Font (es. `Inter`, `AR One Sans`)." }, "font_weight": { "type": "string", "description": "Spessore del carattere disponibile per la famiglia selezionata (es. `regular`, `500`, `700`)." }, "app_public_name": { "type": "string", "nullable": true, "description": "Nome pubblico mostrato nel flusso di verifica." }, "privacy_policy_url": { "type": "string", "nullable": true, "description": "URL dell'informativa sulla privacy mostrato all'utente finale." }, "skip_welcome_screen": { "type": "boolean", "description": "Salta la schermata iniziale di benvenuto." }, "disable_login_with_didit": { "type": "boolean", "description": "Continua come ospite invece di mostrare la schermata di accesso con Didit. Non può essere reimpostato a `false` mentre è configurato un dominio personalizzato (400)." }, "hide_progress_bar": { "type": "boolean", "description": "Nascondi la barra di avanzamento durante il flusso." }, "callback_seconds": { "type": "integer", "minimum": 0, "description": "Ritardo (secondi) prima del reindirizzamento all'URL di callback." }, "delete_logo_square": { "type": "boolean", "description": "Quando è `true`, rimuove il logo quadrato corrente." }, "delete_logo_rectangular": { "type": "boolean", "description": "Quando è `true`, rimuove il logo rettangolare corrente." }, "delete_logo_rectangular_dark": { "type": "boolean", "description": "Quando è `true`, rimuove l'attuale logo per la modalità scura e `logo_rectangular_dark` assume il valore `null`. Se la stessa richiesta multipart carica anche `image_rectangular_dark`, prevale il caricamento." }, "delete_favicon": { "type": "boolean", "description": "Quando è `true`, rimuove la favicon corrente." } } }, "BrandingCustomization": { "type": "object", "description": "Branding White label per un'applicazione: colori, font, raggi dei bordi, URL dei loghi e opzioni UI/UX. Gli URL dei loghi sono di sola lettura (impostali caricando le immagini). Il dominio personalizzato e l'email White label non sono inclusi.", "properties": { "color_primary": { "type": "string" }, "color_secondary": { "type": "string" }, "color_background": { "type": "string" }, "color_panel": { "type": "string" }, "color_panel_10": { "type": "string" }, "color_on_panel_1": { "type": "string" }, "color_on_panel_2": { "type": "string" }, "color_on_background": { "type": "string" }, "color_button_1": { "type": "string" }, "color_button_2": { "type": "string" }, "color_button_text_1": { "type": "string" }, "color_button_text_2": { "type": "string" }, "color_pill_text": { "type": "string" }, "border_radius_panel": { "type": "integer" }, "border_radius_buttons": { "type": "integer" }, "font_family": { "type": "string" }, "font_weight": { "type": "string" }, "font_url": { "type": "string", "nullable": true, "description": "Sola lettura. URL del foglio di stile Google Fonts risolto per la famiglia di caratteri selezionata." }, "logo_square": { "type": "string", "nullable": true, "description": "URL di sola lettura del logo quadrato. Carica tramite `image_square`." }, "logo_rectangular": { "type": "string", "nullable": true, "description": "URL di sola lettura del logo rettangolare. Carica tramite `image_rectangular`." }, "logo_rectangular_dark": { "type": "string", "format": "uri", "nullable": true, "description": "Sola lettura. URL firmato temporaneo del logo rettangolare per la modalità scura, visualizzato su sfondo scuro. `null` quando non è impostato alcun logo per la modalità scura o i loghi rettangolari non sono visualizzati per il tuo account. Caricalo con `image_rectangular_dark`." }, "favicon": { "type": "string", "nullable": true, "description": "URL di sola lettura della favicon. Carica tramite `image_favicon`." }, "app_public_name": { "type": "string", "nullable": true }, "privacy_policy_url": { "type": "string", "nullable": true }, "skip_welcome_screen": { "type": "boolean" }, "disable_login_with_didit": { "type": "boolean" }, "hide_progress_bar": { "type": "boolean" }, "callback_seconds": { "type": "integer" } } }, "WebhookEvent": { "type": "string", "description": "Nome dell'evento webhook supportato. Usa queste stringhe esatte in `subscribed_events`; i valori non supportati vengono rifiutati.", "enum": [ "status.updated", "data.updated", "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created", "transaction.created", "transaction.status.updated", "travel_rule.status.updated", "workflow.compliance_changed", "transaction_rule_suggestions.created", "auth.signup", "auth.login", "auth.login_failed", "auth.password_reset_requested", "auth.password_reset_completed", "auth.mfa_changed", "auth.new_device", "auth.account_locked", "investigator.report.ready", "investigator.decision.automated", "investigator.decision.overridden", "investigator.decision.contested", "investigator.question.raised", "investigator.automation.paused", "investigator.rfi.answered", "investigator.rfi.overdue", "investigator.drift.detected", "investigator.sla.breached", "investigator.qa.failed", "investigator.external.report.ready" ] }, "WebhookSubscribedEvents": { "type": "array", "description": "Filtro degli eventi per questa destinazione webhook. Didit consegna solo i webhook il cui tipo di evento corrisponde esattamente a uno di questi valori — non esiste un abbonamento con caratteri jolly. Quando viene inviato, l'elenco deve contenere almeno un evento valido (un `[]` esplicito viene rifiutato con 400); una destinazione il cui elenco è vuoto (campo omesso alla creazione) non riceve nulla. In caso di aggiornamento, l'elenco viene sostituito per intero, mai unito.", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEvent" }, "example": [ "status.updated", "data.updated" ] }, "PhoneVerificationSendResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID sessione della verifica. Un invio `Retry` restituisce lo stesso `request_id` dell'invio originale. Questo id compare nella Business Console, viene restituito nuovamente da un `POST /v3/phone/check/` finalizzato e può essere passato a `GET /v3/session/{sessionId}/decision/`." }, "status": { "type": "string", "enum": [ "Success", "Retry", "Blocked" ], "description": "`Success` — OTP inviato per una nuova verifica. `Retry` — OTP inviato nuovamente per la verifica in sospeso creata da un invio precedente. `Blocked` — il livello antifrode ha rifiutato l'invio; la verifica viene immediatamente finalizzata come `Declined` e non viene addebitato nulla." }, "reason": { "type": "string", "nullable": true, "description": "Il motivo per cui un invio è stato `Blocked` (ad es. `repeated_attempts`, `suspicious`, `spam`). `null` su `Success` e `Retry`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` memorizzato nella sessione (dal primo invio)." }, "metadata": { "type": "object", "nullable": true, "description": "Eco dei `metadata` memorizzati nella sessione (dal primo invio)." } } }, "PhoneVerificationCheckResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Su `Approved`/`Declined`: l'id di sessione della verifica corrispondente — identico al `request_id` restituito da `POST /v3/phone/send/`. Su `Failed` ed `Expired or Not Found`: un UUID casuale monouso che non può essere cercato in seguito." }, "status": { "type": "string", "enum": [ "Approved", "Declined", "Failed", "Expired or Not Found" ], "description": "`Approved` — codice corretto, nessun rischio di rifiuto. `Declined` — definitivo: è stato rilevato un rischio che comporta il rifiuto oppure il limite di tentativi (3) è stato esaurito. `Failed` — codice errato, tentativi rimanenti. `Expired or Not Found` — nessuna verifica in attesa per questo numero negli ultimi 5 minuti." }, "message": { "type": "string", "description": "Spiegazione di facile lettura dell'esito, compreso il numero di tentativi rimanenti dopo un codice errato." }, "phone": { "type": "object", "nullable": true, "description": "Report telefonico completo. Presente (non nullo) solo per gli esiti finalizzati (`Approved`/`Declined`); `null` per `Failed` e assente per `Expired or Not Found`.", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Not Finished", "Expired" ], "description": "Stato finale della verifica telefonica. Corrisponde allo `status` di primo livello per i controlli finalizzati." }, "phone_number_prefix": { "type": "string", "description": "Prefisso telefonico internazionale del paese con `+` iniziale (es. `+1`).", "example": "+1" }, "phone_number": { "type": "string", "description": "Numero nazionale senza prefisso telefonico internazionale.", "example": "4155552671" }, "full_number": { "type": "string", "description": "Numero completo in formato E.164.", "example": "+14155552671" }, "country_code": { "type": "string", "nullable": true, "description": "Paese ISO 3166-1 alpha-2 del numero.", "example": "US" }, "country_name": { "type": "string", "description": "Nome completo del paese ricavato da `country_code`.", "example": "United States" }, "carrier": { "type": "object", "description": "Rete attuale che serve il numero, derivata dalla ricerca dell'operatore eseguita al momento della finalizzazione.", "properties": { "name": { "type": "string", "description": "Nome dell'operatore telefonico. Stringa vuota quando la ricerca non è riuscita a identificarlo." }, "type": { "type": "string", "description": "Tipo di linea restituito dalla ricerca: `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `pager`, `payphone`, `satellite`, `service`, `shared_cost`, `short_codes_commercial`, `calling_cards`, `local_rate`, `universal_access`, `voice_mail`, `other` o `unknown`." } } }, "is_disposable": { "type": "boolean", "description": "`true` quando il numero appartiene a un servizio di numeri temporanei/usa e getta." }, "is_virtual": { "type": "boolean", "description": "`true` quando il tipo di linea è virtuale (`voip`, `isp` o `vpn`)." }, "verification_method": { "type": "string", "description": "Canale che ha effettivamente consegnato l'OTP una volta confermata la consegna (ad es. `whatsapp`, `sms`); fino a quel momento, il canale richiesto." }, "verification_attempts": { "type": "integer", "description": "Numero di invii dell'OTP per questa verifica (1, oppure 2 dopo un nuovo tentativo)." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora di inserimento del codice corretto. `null` se la verifica non è mai stata approvata." }, "warnings": { "type": "array", "description": "Avvisi di rischio registrati durante la verifica (duplicate, disposable, VoIP, attempts exceeded, blocklist, ecc.). Array vuoto se non ne è presente alcuno.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Funzionalità che ha generato l'avviso. Sempre `PHONE` qui." }, "risk": { "type": "string", "description": "Codice di rischio leggibile dalla macchina." }, "additional_data": { "type": "object", "nullable": true, "description": "Contesto specifico del rischio (ad es. l'ID della sessione duplicata per i rischi di duplicazione). `null` quando il rischio non include dati aggiuntivi." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravità. I rischi `error` comportano il rifiuto della verifica, `warning` la contrassegna per la revisione, `information` viene registrato senza influire sullo stato." }, "short_description": { "type": "string", "description": "Riepilogo del rischio su una riga leggibile dall'utente." }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura del rischio." } } } }, "lifecycle": { "type": "array", "description": "Traccia di audit cronologica della verifica. L'evento `type` è uno tra `PHONE_VERIFICATION_MESSAGE_SENT`, `PHONE_VERIFICATION_RETRY_MESSAGE_SENT`, `PHONE_VERIFICATION_BLOCKED`, `PHONE_DELIVERY_DELIVERED`, `PHONE_DELIVERY_UNDELIVERABLE`, `VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`, `PHONE_VERIFICATION_APPROVED`, `PHONE_VERIFICATION_DECLINED`, `PHONE_VERIFICATION_IN_REVIEW`, `PHONE_VERIFICATION_EXPIRED`.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo di evento." }, "timestamp": { "type": "string", "format": "date-time", "description": "Data e ora in cui si è verificato l'evento." }, "details": { "type": "object", "nullable": true, "description": "Payload specifico dell'evento. Eventi di invio: `{status, reason, channel, actual_channel}` (`actual_channel` viene compilato una volta confermata la consegna). Eventi di consegna: `{channel, status}`. Eventi di inserimento codice: `{code_tried, status}`. Eventi di stato finale: `null`, o `{reason}` se rifiutata o in revisione." }, "fee": { "type": "number", "description": "Importo in USD fatturato per questo evento. Diverso da zero solo per gli eventi di invio (il prezzo di consegna); 0 per inserimenti di codici, conferme di consegna ed eventi di stato." } } } }, "matches": { "type": "array", "description": "Altre sessioni della tua applicazione (KYC, KYB o API) in cui lo stesso numero di telefono è stato utilizzato da un utente diverso (`vendor_data` differente). Fino a 5 voci; una corrispondenza sintetica della blocklist da voce di elenco compare per prima, se presente (le corrispondenze derivate dalla sessione mantengono l'ordine della query). Array vuoto quando non ci sono corrispondenze.", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID sessione dell'altra verifica che ha utilizzato questo numero di telefono." }, "session_number": { "type": "integer", "description": "Numero progressivo di facile lettura di tale sessione." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` di quella sessione." }, "verification_date": { "type": "string", "description": "Data e ora di creazione di quella sessione (`YYYY-MM-DDTHH:MM:SSZ`)." }, "phone_number": { "type": "string", "description": "Il numero di telefono corrispondente." }, "status": { "type": "string", "description": "Stato di quella sessione (ad es., `Approved`, `Declined`, `In Progress`)." }, "is_blocklisted": { "type": "boolean", "description": "Indica se il numero di telefono è presente nella blocklist della tua applicazione." }, "api_service": { "type": "string", "nullable": true, "description": "Per le sessioni di tipo API, l'API standalone che l'ha creata (es. `PHONE_VERIFICATION`); `null` per le normali sessioni di verifica." }, "source": { "type": "string", "description": "Dove è stata trovata la corrispondenza. Di solito `session`; un riscontro nella blocklist tramite una voce dell'elenco dell'organizzazione antepone una corrispondenza sintetica con `source: \"list_entry\"` e `session_id`/`session_number` nulli." } } } }, "phone_social": { "$ref": "#/components/schemas/PhoneSocialFootprint" }, "phone_intelligence": { "allOf": [ { "$ref": "#/components/schemas/PhoneIntelligence" } ], "description": "Segnali di intelligence telefonica. Presenti solo quando `enable_enrichment` era `true` nel controllo." } } }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` della sessione della verifica corrispondente. `null` in caso di `Expired or Not Found`." }, "metadata": { "type": "object", "nullable": true, "description": "`metadata` della sessione di verifica corrispondente. `null` in caso di `Expired or Not Found`." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp della risposta a questo controllo." } } }, "EmailVerificationSendResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID sessione della verifica. Un invio `Retry` restituisce lo stesso `request_id` dell'invio originale. Questo id compare nella Business Console, viene restituito nuovamente da un `POST /v3/email/check/` finalizzato e può essere passato a `GET /v3/session/{sessionId}/decision/`." }, "status": { "type": "string", "enum": [ "Success", "Retry", "Undeliverable" ], "description": "`Success` — OTP inviato via email per una nuova verifica (fatturata). `Retry` — nuovo OTP inviato via email per la verifica in sospeso creata da un invio precedente (gratuito). `Undeliverable` — l'indirizzo non ha superato la convalida di recapito o non è stato possibile inviare il messaggio; la verifica viene immediatamente finalizzata come `Declined` e non viene addebitato nulla." }, "reason": { "type": "string", "nullable": true, "enum": [ "email_can_not_be_delivered", null ], "description": "`email_can_not_be_delivered` quando `status` è `Undeliverable`; `null` altrimenti." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` memorizzato nella sessione (dal primo invio)." }, "metadata": { "type": "object", "nullable": true, "description": "Eco dei `metadata` memorizzati nella sessione (dal primo invio)." } } }, "EmailVerificationCheckResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Su `Approved`/`Declined`: l'id di sessione della verifica corrispondente — identico al `request_id` restituito da `POST /v3/email/send/`. Su `Failed` ed `Expired or Not Found`: un UUID casuale monouso che non può essere cercato in seguito." }, "status": { "type": "string", "enum": [ "Approved", "Declined", "Failed", "Expired or Not Found" ], "description": "`Approved` — codice corretto, nessun rischio di rifiuto. `Declined` — definitivo: è stato rilevato un rischio che comporta il rifiuto oppure il limite di tentativi (3) è stato esaurito. `Failed` — codice errato, tentativi rimanenti. `Expired or Not Found` — nessuna verifica in attesa per questo indirizzo negli ultimi 5 minuti." }, "message": { "type": "string", "description": "Spiegazione di facile lettura dell'esito, compreso il numero di tentativi rimanenti dopo un codice errato." }, "email": { "type": "object", "nullable": true, "description": "Report email completo. Presente (non nullo) solo per gli esiti finalizzati (`Approved`/`Declined`); `null` su `Failed` e assente su `Expired or Not Found`.", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Not Finished", "Expired" ], "description": "Stato finale della verifica email. Corrisponde allo `status` di primo livello per i controlli finalizzati." }, "email": { "type": "string", "format": "email", "description": "L'indirizzo email verificato.", "example": "alice@example.com" }, "is_breached": { "type": "boolean", "description": "`true` quando l'indirizzo compare in violazioni di dati note (ricerca di intelligence sulle violazioni eseguita al momento del completamento)." }, "breaches": { "type": "array", "description": "Fino a 5 delle violazioni note più recenti contenenti questo indirizzo. Array vuoto (o omesso) quando `is_breached` è `false`.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Identificatore della violazione." }, "domain": { "type": "string", "description": "Dominio del servizio violato." }, "breach_date": { "type": "string", "format": "date", "description": "Data in cui si è verificata la violazione." }, "breach_emails_count": { "type": "integer", "description": "Numero totale di account esposti nella violazione dei dati." }, "description": { "type": "string", "description": "Descrizione di facile lettura della violazione (può contenere markup HTML)." }, "logo_path": { "type": "string", "description": "URL del logo del servizio violato." }, "data_classes": { "type": "array", "items": { "type": "string" }, "description": "Categorie di dati esposti, in snake_case (ad es., `email_addresses`, `passwords`)." }, "is_verified": { "type": "boolean", "description": "Indica se la violazione è stata verificata come legittima." } } } }, "is_disposable": { "type": "boolean", "description": "`true` quando il dominio appartiene a un provider noto di email temporanee/usa e getta." }, "is_undeliverable": { "type": "boolean", "description": "`true` quando l'indirizzo non può ricevere posta (validazione della sintassi o DNS/MX non riuscita, oppure messaggio rimbalzato)." }, "verification_attempts": { "type": "integer", "description": "Numero di invii dell'OTP per questa verifica (1, oppure 2 dopo un nuovo tentativo)." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora di inserimento del codice corretto. `null` se la verifica non è mai stata approvata." }, "warnings": { "type": "array", "description": "Avvisi di rischio registrati durante la verifica (duplicate, breached, disposable, undeliverable, attempts exceeded, blocklist, ecc.). Array vuoto se non ne è presente alcuno.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Funzionalità che ha generato l'avviso. Sempre `EMAIL` qui." }, "risk": { "type": "string", "description": "Codice di rischio leggibile dalla macchina." }, "additional_data": { "type": "object", "nullable": true, "description": "Contesto specifico del rischio (ad es. l'ID della sessione duplicata per i rischi di duplicazione). `null` quando il rischio non include dati aggiuntivi." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravità. I rischi `error` comportano il rifiuto della verifica, `warning` la contrassegna per la revisione, `information` viene registrato senza influire sullo stato." }, "short_description": { "type": "string", "description": "Riepilogo del rischio su una riga leggibile dall'utente." }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura del rischio." } } } }, "lifecycle": { "type": "array", "description": "Traccia di audit cronologica della verifica. L'evento `type` è uno tra `EMAIL_VERIFICATION_MESSAGE_SENT`, `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT`, `VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`, `EMAIL_VERIFICATION_APPROVED`, `EMAIL_VERIFICATION_DECLINED`, `EMAIL_VERIFICATION_IN_REVIEW`, `EMAIL_VERIFICATION_EXPIRED`.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo di evento." }, "timestamp": { "type": "string", "format": "date-time", "description": "Data e ora in cui si è verificato l'evento." }, "details": { "type": "object", "nullable": true, "description": "Payload specifico dell'evento. Eventi di invio: `{status, reason}`. Eventi di inserimento codice: `{code_tried, status}`. Eventi di stato finale: `null`, o `{reason}` se rifiutata o in revisione." }, "fee": { "type": "number", "description": "Importo in USD fatturato per questo evento. Diverso da zero solo al primo invio riuscito; 0 per nuovi tentativi, inserimenti di codici ed eventi di stato." } } } }, "matches": { "type": "array", "description": "Altre sessioni della tua applicazione (KYC, KYB o API) in cui lo stesso indirizzo email è stato utilizzato da un utente diverso (differente `vendor_data`). Fino a 5 voci; una corrispondenza sintetica con una voce della blocklist viene anteposta se presente (e solo quando non esiste un'email derivata dalla sessione inclusa nella blocklist) — le corrispondenze derivate dalla sessione mantengono l'ordine di created_at. Array vuoto in assenza di corrispondenze.", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID sessione dell'altra verifica che ha utilizzato questo indirizzo email." }, "session_number": { "type": "integer", "description": "Numero progressivo di facile lettura di tale sessione." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` di quella sessione." }, "verification_date": { "type": "string", "description": "Data e ora di creazione di quella sessione (`YYYY-MM-DDTHH:MM:SSZ`)." }, "email": { "type": "string", "description": "L'indirizzo email corrispondente." }, "status": { "type": "string", "description": "Stato di quella sessione (ad es., `Approved`, `Declined`, `In Progress`)." }, "is_blocklisted": { "type": "boolean", "description": "Indica se l'indirizzo email è presente nella blocklist della tua applicazione." }, "api_service": { "type": "string", "nullable": true, "description": "Per le sessioni di tipo API, l'API standalone che l'ha creata (es. `PHONE_VERIFICATION`); `null` per le normali sessioni di verifica." }, "source": { "type": "string", "description": "Dove è stata trovata la corrispondenza. Di solito `session`; un riscontro nella blocklist tramite una voce dell'elenco dell'organizzazione antepone una corrispondenza sintetica con `source: \"list_entry\"` e `session_id`/`session_number` nulli." } } } }, "email_social": { "$ref": "#/components/schemas/EmailSocialFootprint" }, "email_intelligence": { "allOf": [ { "$ref": "#/components/schemas/EmailIntelligence" } ], "description": "Segnali di intelligence sulle email. Presenti solo quando `enable_enrichment` era `true` nel controllo." } } }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` della sessione della verifica corrispondente. `null` in caso di `Expired or Not Found`." }, "metadata": { "type": "object", "nullable": true, "description": "`metadata` della sessione di verifica corrispondente. `null` in caso di `Expired or Not Found`." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp della risposta a questo controllo." } } }, "WorkflowListItem": { "type": "object", "description": "Una singola versione del workflow nella vista a elenco.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID per versione. Utilizzalo come `{settings_uuid}` per recuperare/aggiornare/eliminare e come `workflow_id` durante la creazione delle sessioni." }, "workflow_id": { "type": "string", "format": "uuid", "description": "ID di gruppo stabile condiviso da tutte le versioni dello stesso workflow. Equivale a `uuid` per la versione 1." }, "workflow_label": { "type": "string", "description": "Nome visualizzato per il workflow." }, "workflow_type": { "type": "string", "nullable": true, "description": "Tipo base per workflow semplici: `kyc`, `kyb`, `adaptive_age_verification`, `biometric_authentication`, ecc. `null` per workflow basati su grafi senza una funzionalità KYB." }, "is_default": { "type": "boolean", "description": "Indica se questo è il workflow predefinito per le nuove sessioni." }, "is_archived": { "type": "boolean" }, "is_white_label_enabled": { "type": "boolean", "description": "Indica se la personalizzazione White label si applica alle sessioni create con questo workflow." }, "total_price": { "type": "number", "description": "Prezzo fisso per verifica in USD (numero JSON, esclude le funzionalità a prezzo variabile come DATABASE_VALIDATION e PHONE_VERIFICATION)." }, "min_price": { "type": "number", "description": "Prezzo fisso più economico tra i percorsi del grafo del workflow, in USD." }, "max_price": { "type": "number", "description": "Prezzo fisso più elevato tra i percorsi del grafo del workflow, in USD." }, "features": { "type": "string", "description": "Funzionalità abilitate sotto forma di singola stringa unita da `\" + \"`, ad es. `\"OCR + LIVENESS + FACE_MATCH\"`. Suddividi usando `\" + \"` per ottenere un elenco." }, "is_simple_workflow": { "type": "boolean", "description": "True quando il workflow non ha un grafo del workflow personalizzato." }, "is_editable": { "type": "boolean", "description": "True quando questa versione è una `draft` (le bozze possono essere modificate direttamente; le versioni pubblicate sono immutabili nella Console)." }, "workflow_url": { "type": "string", "format": "uri", "description": "URL di verifica pubblico e condivisibile per questo workflow (`https://verify.didit.me/u/`)." }, "max_retry_attempts": { "type": "integer", "description": "Numero massimo di nuovi tentativi consentiti dopo una verifica rifiutata (0-10)." }, "retry_window_days": { "type": "integer", "nullable": true, "description": "Finestra mobile in giorni utilizzata per contare i nuovi tentativi (1-365). `null` = limite complessivo." }, "session_expiration_time": { "type": "integer", "description": "Secondi prima della scadenza di una sessione non completata (3600-2419200)." }, "version": { "type": "integer", "description": "Numero di versione all'interno del gruppo `workflow_id`, a partire da 1." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Stato della versione. Le nuove sessioni utilizzano l'ultima versione `published` di un gruppo." }, "has_draft": { "type": "boolean", "description": "True quando qualsiasi versione in questo gruppo `workflow_id` è attualmente una bozza." }, "created_by": { "type": "object", "nullable": true, "description": "Chi ha creato questa versione: `{name, email, type}` dove `type` è `user` (utente della Console, `email` impostata) o `api_key` (`name` è il client id, `email` è null). `null` quando non è stato registrato alcun creatore.", "properties": { "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "user", "api_key" ] } } }, "updated_at": { "type": "string", "format": "date-time" } } }, "SimpleWorkflowRequest": { "type": "object", "description": "Crea un workflow lineare semplice. L'API converte internamente questo elenco di funzionalità in un grafo di workflow basato su nodi. Whitelist dei campi RIGIDA: qualsiasi chiave non presente in questo elenco (incluso `workflow_type`) viene rifiutata con un 400.", "required": [ "features" ], "properties": { "workflow_label": { "type": "string", "maxLength": 50, "default": "ID Verification", "description": "Nome visualizzato per il workflow (massimo 50 caratteri). Il valore predefinito è `\"ID Verification\"` se omesso: impostalo sempre affinché i workflow rimangano distinguibili.", "example": "Standard KYC" }, "is_default": { "type": "boolean", "description": "Imposta questo workflow come predefinito per le nuove sessioni." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Ometti questo campo per creare un workflow pubblicato pronto per le sessioni. Usa `draft` solo quando vuoi salvare senza pubblicare." }, "features": { "type": "array", "minItems": 1, "description": "Funzionalità di verifica in ordine di esecuzione. L'API collega ciascun elemento a quello successivo e aggiunge automaticamente un nodo di stato finale.", "items": { "$ref": "#/components/schemas/SimpleWorkflowFeature" } }, "is_white_label_enabled": { "type": "boolean", "description": "Abilita la personalizzazione White label per le sessioni create con questo workflow.", "default": false }, "is_desktop_allowed": { "type": "boolean", "description": "Consenti l'esecuzione del flusso di verifica sui browser desktop.", "default": false }, "max_retry_attempts": { "type": "integer", "minimum": 0, "maximum": 10, "default": 3, "description": "Numero massimo di nuovi tentativi consentiti dopo una verifica rifiutata. `0` blocca l'utente dopo il primo rifiuto." }, "retry_window_days": { "type": "integer", "minimum": 1, "maximum": 365, "nullable": true, "default": 7, "description": "Finestra mobile in giorni utilizzata per contare i nuovi tentativi. `null` applica un limite complessivo." }, "face_liveness_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "default": 3, "description": "Numero massimo di invii per il rilevamento della vitalità per sessione. Valore predefinito 3: un tentativo iniziale più due nuovi tentativi. Questo valore viene copiato anche nei nodi di workflow generati per il rilevamento della vitalità e la stima dell'età, a meno che la configurazione a livello di funzionalità non lo sovrascriva." }, "face_match_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "default": 3, "description": "Numero massimo di invii per il confronto facciale per sessione. Valore predefinito 3: un tentativo iniziale più due nuovi tentativi. Questo valore viene copiato anche nei nodi di workflow generati per il confronto facciale, a meno che la configurazione a livello di funzionalità non lo sovrascriva." }, "session_expiration_time": { "type": "integer", "minimum": 3600, "maximum": 2419200, "default": 604800, "description": "Secondi prima della scadenza di una sessione non completata. Minimo 1 ora (3600), massimo 4 settimane (2419200)." } } }, "SimpleWorkflowUpdateRequest": { "type": "object", "description": "Aggiorna i metadati del workflow o sostituisci l'elenco lineare completo delle funzionalità. Whitelist dei campi RIGOROSA: qualsiasi chiave non presente qui viene rifiutata con un 400.", "properties": { "workflow_label": { "type": "string", "maxLength": 50, "description": "Nome visualizzato per il workflow (massimo 50 caratteri)." }, "is_default": { "type": "boolean", "description": "Imposta questo workflow come predefinito per le nuove sessioni." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Controlla il versionamento. Ometti per aggiornare la versione corrente sul posto (le bozze vengono pubblicate automaticamente). `published` su una versione già pubblicata crea e restituisce una NUOVA versione. `draft` è valido solo finché la versione è ancora una bozza." }, "features": { "type": "array", "minItems": 1, "description": "Se fornito, questo sostituisce l'intero ordine delle funzionalità e la relativa configurazione.", "items": { "$ref": "#/components/schemas/SimpleWorkflowFeature" } }, "is_white_label_enabled": { "type": "boolean", "description": "Abilita la personalizzazione White label per le sessioni create con questo workflow." }, "is_desktop_allowed": { "type": "boolean", "description": "Consenti l'esecuzione del flusso di verifica sui browser desktop." }, "max_retry_attempts": { "type": "integer", "minimum": 0, "maximum": 10, "description": "Numero massimo di nuovi tentativi consentiti dopo una verifica rifiutata. `0` blocca l'utente dopo il primo rifiuto." }, "retry_window_days": { "type": "integer", "minimum": 1, "maximum": 365, "nullable": true, "description": "Finestra mobile in giorni utilizzata per contare i nuovi tentativi. `null` applica un limite complessivo." }, "face_liveness_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "Numero massimo di invii per il rilevamento della vitalità per sessione. Questo valore viene copiato anche nei nodi di workflow generati per il rilevamento della vitalità e la stima dell'età, a meno che la configurazione a livello di funzionalità non lo sovrascriva." }, "face_match_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "Numero massimo di invii per il confronto facciale per sessione. Questo valore viene copiato anche nei nodi di workflow generati per il confronto facciale, a meno che la configurazione a livello di funzionalità non lo sovrascriva." }, "session_expiration_time": { "type": "integer", "minimum": 3600, "maximum": 2419200, "description": "Secondi prima della scadenza di una sessione non completata. Minimo 1 ora (3600), massimo 4 settimane (2419200)." } } }, "SimpleWorkflowFeature": { "type": "object", "required": [ "feature" ], "properties": { "feature": { "type": "string", "description": "Funzionalità da eseguire. Usa i valori in lettere maiuscole mostrati qui.", "enum": [ "OCR", "NFC", "LIVENESS", "FACE_MATCH", "PROOF_OF_ADDRESS", "QUESTIONNAIRE", "DOCUMENT_AI", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "DATABASE_VALIDATION", "AML", "IP_ANALYSIS", "AGE_ESTIMATION", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "SIGNATURE" ] }, "config": { "type": "object", "description": "Impostazioni specifiche della funzionalità. Per `QUESTIONNAIRE`, includi `questionnaire_uuid` con il `questionnaire_id` restituito dall'endpoint di creazione del questionario. Per `SIGNATURE`, un workflow che passa in produzione richiede un documento da firmare: imposta `signature_documents_source` su `session` o `both` in modo che ogni sessione possa fornire il proprio, oppure invia `status: \"draft\"` e aggiungi i documenti prima della pubblicazione. `signature_level: \"aes\"` viene rifiutato con `aes_not_available` finché `signature_availability.aes` è `false` nel workflow. Per `OCR`, `methods` seleziona quali metodi di Verifica dell'identità ciascun paese può utilizzare (acquisizione del documento, verifica non documentale rispetto a fonti governative o altre fonti autorevoli e wallet di identità digitale); omettilo e ogni paese utilizzerà unicamente l'acquisizione del documento. Per `SIGNATURE`, consulta [Impostazioni della firma elettronica](/it/management-api/workflows/feature-configs#e-signature): `signature_level` accetta per ora `simple` (il valore predefinito, non richiede verifica dell'identità, email o telefono) e `aes`; inoltre, i documenti del workflow e i relativi campi vengono gestiti nella console, quindi tramite l'API invia documenti e campi per sessione con `signature_documents_source: \"session\"`.", "additionalProperties": true }, "label": { "type": "string", "description": "Etichetta interna opzionale per questo nodo del workflow." } } }, "ReviewItem": { "type": "object", "description": "Una voce nel feed di revisione / attività di una sessione. Le modifiche di stato contengono `previous_status`, `new_status`, `previous_value`, `new_value` e `changed_fields`; i commenti contengono `comment` e (per i commenti della Console) `mentioned_emails`; i campi rimanenti sono `null` o vuoti se non si applicano al tipo di attività.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificativo univoco di questa voce del feed.", "example": "de0561bc-5583-4409-9171-1a31a4c8a5f4" }, "activity_type": { "type": "string", "enum": [ "COMMENT", "STATUS_UPDATED", "KYC_DATA_UPDATED", "POA_DATA_UPDATED", "FILE_ADDED", "FILE_REMOVED", "AML_ONGOING_MATCH", "AML_STATUS_UPDATED", "AML_HIT_STATUS_UPDATED", "KYB_DATA_UPDATED", "KYB_DOCUMENT_UPLOADED", "TAG_ADDED", "TAG_REMOVED", "FEATURE_OVERRIDE_PENDING", "FEATURE_OVERRIDE_APPLIED", "FEATURE_OVERRIDE_CANCELLED" ], "description": "Che tipo di attività registra questa voce. Le righe `STATUS_UPDATED` provengono da decisioni manuali (`PATCH /v3/session/{session_id}/update-status/`) e da voci aggiunte tramite `POST …/reviews/` (che assumono questo tipo per impostazione predefinita anche quando non viene registrato alcuno stato). Le righe `COMMENT` provengono dai revisori della Console; le visualizzazioni della pagina di dettaglio della Console vengono memorizzate anch'esse come righe `COMMENT` contrassegnate con `metadata.system_event = \"DETAIL_VIEWED\"`. I restanti tipi tracciano modifiche ai dati, variazioni di file, tag e attività di monitoraggio AML. Le righe STATUS_UPDATED vengono scritte anche da attori di sistema (ad es. monitoraggio AML continuo con actor_type SYSTEM e aggiornamenti automatici dello stato delle funzionalità), non solo dall'endpoint update-status e dagli inserimenti di revisione manuale. `FEATURE_OVERRIDE_PENDING`, `FEATURE_OVERRIDE_APPLIED` e `FEATURE_OVERRIDE_CANCELLED` registrano l'override dello stato di un controllo (`PATCH /v3/session/{session_id}/features/{node_id}/update-status/`): richiesto in attesa del completamento del flusso, applicato o annullato. Riportano lo stato del controllo in `previous_value` / `new_value` (`{\"status\": ...}`), lasciano `previous_status` e `new_status` impostati su `null` e indicano l'override in `metadata` (`feature_override_id`, `node_id`, `feature_model`, `forced`, `state`, `cancel_reason`). La voce relativa alla richiesta include il `comment` del revisore; un override applicato al termine del flusso viene registrato con `actor_type` pari a `SYSTEM`.", "example": "STATUS_UPDATED" }, "actor_display": { "type": "string", "description": "Etichetta dell'autore di facile lettura, risolta nell'ordine: nome completo dell'attore → identificatore dell'account della Console → parte locale di `actor_email` → `\"API Client\"` (per attori `API_KEY`) → `\"System\"` (per attori `SYSTEM`) → `\"Unknown\"`. Le voci create tramite `POST …/reviews/` mostrano sempre `\"Unknown\"` poiché quell'endpoint non registra alcuna attribuzione dell'attore.", "example": "API Client" }, "actor_email": { "type": "string", "nullable": true, "description": "Email dell'utente della Console che ha eseguito l'azione. `null` per le chiavi API e i soggetti di sistema.", "example": null }, "actor_type": { "type": "string", "enum": [ "API_KEY", "CONSOLE_USER", "SYSTEM" ], "description": "Chi ha eseguito l'azione: una chiave API, un utente della Console o Didit stessa (`SYSTEM`, ad es. monitoraggio AML continuo). Le voci create tramite `POST …/reviews/` riportano il valore predefinito `CONSOLE_USER` indipendentemente dal chiamante.", "example": "API_KEY" }, "new_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Stato della sessione registrato da questa voce (per gli aggiornamenti di stato). `null` per commenti e voci di modifica dei dati.", "example": "Approved" }, "previous_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Stato della sessione prima della modifica. Compilato nelle voci `STATUS_UPDATED` scritte dall'endpoint di aggiornamento dello stato; `null` nelle voci aggiunte tramite `POST …/reviews/`. Compilato anche nelle righe STATUS_UPDATED scritte dal sistema.", "example": "In Review" }, "comment": { "type": "string", "nullable": true, "description": "Nota in formato testo libero allegata alla voce, oppure `null`.", "example": "Document re-checked manually; address matches." }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Utenti della Console menzionati con `@email` nel commento. Sempre vuoto per le voci create tramite questa API: l'elaborazione delle menzioni è una funzionalità esclusiva della Console.", "example": [] }, "previous_value": { "type": "object", "nullable": true, "description": "Istantanea dei dati modificati prima dell'azione, ad es. `{\"status\": \"In Review\"}` in caso di cambio di stato. `null` quando non è stato modificato nulla.", "example": { "status": "In Review" } }, "new_value": { "type": "object", "nullable": true, "description": "Istantanea dei dati modificati dopo l'azione, ad es. `{\"status\": \"Approved\"}`. `null` quando non è stato modificato nulla.", "example": { "status": "Approved" } }, "changed_fields": { "type": "array", "items": { "type": "string" }, "description": "Nomi dei campi modificati da questa attività (es. `[\"status\"]`). Vuoto per i commenti e per le voci aggiunte tramite `POST …/reviews/`.", "example": [ "status" ] }, "metadata": { "type": "object", "nullable": true, "description": "Contesto aggiuntivo per le voci generate dal sistema. Le visualizzazioni della pagina dei dettagli nella Console includono `{\"system_event\": \"DETAIL_VIEWED\", \"detail_type\": \"verification\"}` in modo da poter essere escluse dalla logica di notifica. Un `COMMENT` modificato dal rispettivo autore nella Console include `edited_at`, l'orario ISO 8601 dell'ultima modifica (`comment` e `mentioned_emails` conterranno quindi il testo modificato e le relative menzioni). `null` per le voci ordinarie.", "example": null }, "created_at": { "type": "string", "format": "date-time", "description": "Data e ora di scrittura della voce, ISO 8601 UTC.", "example": "2026-06-12T00:19:31.918735Z" } } }, "QuestionnaireListItem": { "type": "object", "description": "Una versione del questionario nella vista a elenco.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID per versione. Utilizzalo come `{questionnaire_uuid}` per recuperare/aggiornare/eliminare e come `questionnaire_uuid` nella configurazione della funzionalità QUESTIONNAIRE di un workflow." }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "is_active": { "type": "boolean" }, "is_simple_questionnaire": { "type": "boolean", "description": "True per i questionari lineari creati tramite questa API; false per i questionari basati su grafo creati nella Console." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "question_types": { "type": "array", "items": { "type": "string" }, "description": "Tipi di elementi in lettere maiuscole delle domande a cui è possibile rispondere, in ordine di creazione (ad es. `SHORT_TEXT`, `MULTIPLE_CHOICE`, `FILE_UPLOAD`). Gli elementi strutturali `SECTION_HEADER` e `SEPARATOR` sono esclusi. Una voce per domanda, pertanto i valori possono ripetersi." }, "workflow_names": { "type": "array", "items": { "type": "string" }, "description": "Nomi dei workflow che utilizzano questo questionario. Attualmente sempre `[]` su questo endpoint (compilato solo nell'elenco della Console)." }, "questionnaire_group_id": { "type": "string", "format": "uuid", "description": "Identificatore stabile che raggruppa tutte le versioni dello stesso questionario." }, "version": { "type": "integer", "description": "Numero di versione all'interno del gruppo, a partire da 1." }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando è stata pubblicata questa versione. `null` per le bozze." }, "is_editable": { "type": "boolean", "description": "True quando questa versione è una `draft`." } } }, "SimpleQuestionnaireRequest": { "type": "object", "description": "Crea un questionario lineare semplice. L'API converte `form_elements` nel grafo interno del questionario.", "required": [ "title", "languages", "form_elements" ], "properties": { "title": { "type": "string", "description": "Nome interno del questionario." }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "description": "Lingue incluse in ogni etichetta. Deve includere `en`.", "items": { "type": "string" }, "example": [ "en" ] }, "default_language": { "type": "string", "description": "Lingua predefinita. Deve essere inclusa in `languages`.", "example": "en" }, "is_active": { "type": "boolean", "default": true }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Ometti questo campo per creare un questionario pubblicato pronto per i workflow." }, "form_elements": { "type": "array", "minItems": 1, "description": "Domande nell'ordine esatto in cui gli utenti dovrebbero vederle. La ramificazione e i campi condizionali non sono supportati.", "items": { "$ref": "#/components/schemas/SimpleQuestionnaireElement" } } } }, "SimpleQuestionnaireUpdateRequest": { "type": "object", "description": "Aggiorna i metadati del questionario o sostituisci l'elenco lineare completo di `form_elements`.", "properties": { "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "is_active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "form_elements": { "type": "array", "minItems": 1, "description": "Se fornito, questo sostituisce l'intero elenco lineare delle domande.", "items": { "$ref": "#/components/schemas/SimpleQuestionnaireElement" } } } }, "SimpleQuestionnaireElement": { "type": "object", "required": [ "element_type", "label" ], "properties": { "id": { "type": "string", "description": "ID domanda stabile opzionale. Se omesso, l'API genera `q1`, `q2`, ecc. Usa lettere minuscole, numeri e trattini bassi per migliorare la leggibilità.", "example": "source_of_funds" }, "element_type": { "type": "string", "description": "Tipo di domanda. L'API accetta questi valori in lettere minuscole e i loro equivalenti in lettere maiuscole.", "enum": [ "short_text", "long_text", "dropdown", "single_choice", "multiple_choice", "number", "image", "file_upload", "time", "email", "address", "phone", "country", "date_picker", "consent", "section_header", "separator", "heading", "paragraph" ] }, "label": { "type": "object", "description": "Etichetta della domanda per codice lingua, ad esempio `{ \"en\": \"Source of funds\" }`.", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "placeholder": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "is_required": { "type": "boolean", "default": false }, "options": { "type": "array", "description": "Usa per `dropdown`, `single_choice` e `multiple_choice`. Se `value` viene omesso, l'API ne genera uno a partire dall'etichetta dell'opzione.", "items": { "type": "object", "required": [ "label" ], "properties": { "value": { "type": "string" }, "label": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "max_files": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Usa con `file_upload` o `image`." }, "validation": { "type": "object", "nullable": true, "description": "Validazione del formato opzionale per `short_text`, `long_text` o `number`. Applicata mentre l'utente compila il campo (non può procedere finché non è superata) e riverificata dall'API al momento dell'invio.", "properties": { "pattern": { "type": "string", "description": "Espressione regolare (sottoinsieme ECMA-262) a cui il valore deve corrispondere completamente. Per `short_text` e `long_text`. Non aggiungere gli ancoraggi ^/$; il confronto viene eseguito sull'intero valore." }, "min_length": { "type": "integer", "minimum": 0, "description": "Numero minimo di caratteri. Per `short_text` e `long_text`." }, "max_length": { "type": "integer", "minimum": 0, "description": "Numero massimo di caratteri. Per `short_text` e `long_text`." }, "min": { "type": "number", "description": "Valore numerico minimo. Per `number`." }, "max": { "type": "number", "description": "Valore numerico massimo. Per `number`." }, "error_message": { "type": "object", "description": "Messaggio tradotto mostrato quando la validazione non riesce, indicizzato per codice lingua.", "additionalProperties": { "type": "string" } } } } } }, "QuestionnaireDetail": { "type": "object", "description": "Dettaglio completo del questionario restituito dagli endpoint GET, POST (creazione) e PATCH (aggiornamento).", "properties": { "questionnaire_id": { "type": "string", "format": "uuid", "description": "Identificativo univoco del questionario. Usa questo id quando fai riferimento al questionario da un workflow o nelle successive richieste di aggiornamento/eliminazione." }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "is_active": { "type": "boolean" }, "is_simple_questionnaire": { "type": "boolean" }, "graph": { "type": "object", "description": "Struttura a grafo con start_node e mappa dei nodi." }, "sections": { "type": "array", "description": "Contenuto del questionario raggruppato in sezioni (derivato dal grafo).", "items": { "type": "object" } }, "questionnaire_group_id": { "type": "string", "format": "uuid", "description": "Identificatore stabile che raggruppa tutte le versioni dello stesso questionario." }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "is_editable": { "type": "boolean", "description": "True quando il questionario può ancora essere modificato direttamente (versioni in bozza)." } } }, "UserListItem": { "type": "object", "description": "Un utente verificato.", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "UUID interno stabile di Didit per questo utente." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore univoco per questo utente (passato durante la creazione delle sessioni). Può essere null se non è stato fornito alcun identificatore del fornitore." }, "display_name": { "type": "string", "nullable": true, "description": "Nome visualizzato personalizzato impostato da te" }, "full_name": { "type": "string", "nullable": true, "description": "Nome completo estratto dai documenti verificati" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "effective_name": { "type": "string", "nullable": true, "description": "Miglior nome disponibile: display_name se impostato, altrimenti full_name" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Stato del ciclo di vita del record utente (NON uno stato della sessione). `ACTIVE` è il valore predefinito, `FLAGGED` contrassegna l'utente per una verifica manuale, `BLOCKED` impedisce nuove sessioni per questo `vendor_data`." }, "portrait_image_url": { "type": "string", "nullable": true, "description": "URL prefirmato della foto ritratto dell'utente (scade dopo alcune ore)" }, "session_count": { "type": "integer", "description": "Numero totale di sessioni di verifica per questo utente" }, "approved_count": { "type": "integer", "description": "Numero di sessioni approvate" }, "declined_count": { "type": "integer", "description": "Numero di sessioni rifiutate" }, "in_review_count": { "type": "integer", "description": "Numero di sessioni in revisione" }, "issuing_states": { "type": "array", "items": { "type": "string" }, "description": "Codici ISO 3166-1 alpha-3 dei paesi di emissione rilevati nei documenti d'identità approvati di questo utente, ad es. `[\"USA\", \"ESP\"]`. Array vuoto se assenti." }, "approved_emails": { "type": "array", "items": { "type": "string" }, "description": "Indirizzi email verificati raccolti dalle sessioni approvate di questo utente, ad es. `[\"john@example.com\"]`." }, "approved_phones": { "type": "array", "items": { "type": "string" }, "description": "Numeri di telefono verificati raccolti dalle sessioni approvate di questo utente, ad es. `[\"+14155551234\"]`." }, "features": { "type": "object", "description": "Stato aggregato per funzionalità in tutte le sessioni di questo utente. Chiavi possibili: `ID_VERIFICATION`, `NFC`, `LIVENESS`, `FACE_MATCH`, `POA`, `QUESTIONNAIRE`, `EMAIL_VERIFICATION`, `PHONE`, `AML`, `IP_ANALYSIS`, `AGE_ESTIMATION`, `DATABASE_VALIDATION`. Valori possibili: `Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`." }, "features_list": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "status": { "type": "string" } } }, "description": "Gli stessi dati di `features`, sotto forma di array ordinato di oggetti `{feature, status}`." }, "last_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp della sessione più recente" }, "first_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp della prima sessione" }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp dell'attività più recente su questo utente (sessione, transazione, cambio di stato, modifica dei dati, ecc.)." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "description": "Tag assegnati a questo utente" }, "created_at": { "type": "string", "format": "date-time" } } }, "BlocklistItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "face", "document", "phone", "email" ] }, "session_id": { "type": "string", "format": "uuid" }, "session_number": { "type": "integer" }, "blocklisted_at": { "type": "string", "format": "date-time" }, "face_image": { "type": "string", "nullable": true }, "document_type": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "phone_number": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "UserDetailItem": { "type": "object", "description": "Dettaglio completo dell'utente. Estende UserListItem con metadati, commenti e updated_at.", "allOf": [ { "$ref": "#/components/schemas/UserListItem" }, { "type": "object", "properties": { "metadata": { "type": "object", "description": "JSON di metadati personalizzati che hai allegato a questo utente. Il valore predefinito è `{}`." }, "tags": { "type": "array", "description": "Assegnazioni dei tag. NOTA: nelle risposte di dettaglio ogni voce è un oggetto *collegamento* del tag (`{uuid, tag: {...}, added_by_email, added_by_name, created_at}`), a differenza della struttura piatta `{uuid, name, color}` usata nelle risposte di elenco.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID dell'assegnazione del tag (non del tag stesso)." }, "tag": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "added_by_email": { "type": "string", "nullable": true }, "added_by_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "comment_type": { "type": "string", "enum": [ "COMMENT", "STATUS_CHANGED", "METADATA_UPDATED", "TAG_ADDED", "TAG_REMOVED", "PROFILE_UPDATED" ] }, "comment": { "type": "string", "nullable": true }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "previous_status": { "type": "string", "nullable": true, "enum": [ "ACTIVE", "FLAGGED", "BLOCKED", null ] }, "new_status": { "type": "string", "nullable": true, "enum": [ "ACTIVE", "FLAGGED", "BLOCKED", null ] }, "previous_value": { "type": "object", "nullable": true, "description": "Valori precedenti dei campi per le voci PROFILE_UPDATED." }, "new_value": { "type": "object", "nullable": true, "description": "Nuovi valori dei campi per le voci PROFILE_UPDATED." }, "changed_fields": { "type": "array", "items": { "type": "string" }, "description": "Nomi dei campi modificati da una voce PROFILE_UPDATED." }, "metadata": { "type": "object", "nullable": true }, "mentioned_emails": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "Registro delle attività e commenti per questo utente (modifiche di stato, modifiche al profilo, note manuali)." }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "BusinessListItem": { "type": "object", "description": "Un'azienda verificata.", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "UUID interno stabile di Didit per questa azienda." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore univoco per questa azienda (passato durante la creazione delle sessioni). Può essere null se non è stato fornito alcun identificatore del fornitore." }, "display_name": { "type": "string", "nullable": true, "description": "Nome visualizzato personalizzato impostato da te" }, "legal_name": { "type": "string", "nullable": true, "description": "Denominazione legale ufficiale dal registro o inserimento manuale" }, "registration_number": { "type": "string", "nullable": true, "description": "Numero di registrazione o costituzione dell'azienda" }, "country_code": { "type": "string", "nullable": true, "description": "Paese di costituzione (ISO 3166-1 alpha-2, ad es. `GB`, `US`)." }, "effective_name": { "type": "string", "nullable": true, "description": "Miglior nome disponibile: display_name se impostato, altrimenti legal_name" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Stato del ciclo di vita del record aziendale (NON uno stato della sessione). `ACTIVE` è il valore predefinito, `FLAGGED` lo contrassegna per una verifica manuale, `BLOCKED` impedisce nuove sessioni per questo `vendor_data`." }, "session_count": { "type": "integer", "description": "Numero totale di sessioni di verifica per questa azienda" }, "approved_count": { "type": "integer", "description": "Numero di sessioni approvate" }, "declined_count": { "type": "integer", "description": "Numero di sessioni rifiutate" }, "in_review_count": { "type": "integer", "description": "Numero di sessioni in revisione" }, "features": { "type": "object", "description": "Stato aggregato per funzionalità in tutte le sessioni KYB di questa azienda. Attualmente l'unica chiave è `KYB` (lo stato del controllo aziendale nel registro). Valori possibili: `Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`." }, "features_list": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "status": { "type": "string" } } }, "description": "Gli stessi dati di `features`, sotto forma di array ordinato di oggetti `{feature, status}`." }, "last_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp della sessione più recente" }, "first_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp della prima sessione" }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp dell'attività più recente (cambio di stato, aggiornamento della sessione, ecc.)" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "description": "Tag assegnati a questa azienda" }, "created_at": { "type": "string", "format": "date-time" } } }, "BusinessDetailItem": { "type": "object", "description": "Dettagli completi dell'azienda. Estende BusinessListItem con metadati e updated_at.", "allOf": [ { "$ref": "#/components/schemas/BusinessListItem" }, { "type": "object", "properties": { "metadata": { "type": "object", "description": "JSON di metadati personalizzati che hai allegato a questa azienda. Il valore predefinito è `{}`." }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "TransactionDetail": { "type": "object", "description": "Record di monitoraggio completo per una transazione, come restituito da `GET /v3/transactions/{transaction_id}/` e `POST /v3/transactions/`.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificativo della transazione stabile di Didit. Utilizzalo come `{transaction_id}` per le chiamate successive." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Ambiente dell'applicazione proprietaria della transazione. Una transazione in `sandbox` viene archiviata ma non viene mai valutata, sottoposta a screening, notificata o fatturata; pertanto, il valore vuoto di `rule_runs` indica \"non valutata\"." }, "transaction_number": { "type": "integer", "description": "Numero sequenziale della transazione con ambito limitato all'applicazione mostrato nella Console (es. `4123`)." }, "txn_id": { "type": "string", "description": "Il `transaction_id` fornito al momento della creazione (max 128 caratteri). Univoco per applicazione." }, "txn_date": { "type": "string", "format": "date-time", "description": "Quando è avvenuta la transazione (da `transaction_at`; il valore predefinito è il momento dell'invio)." }, "zone_id": { "type": "string", "nullable": true, "description": "Identificatore di fuso orario IANA fornito al momento della creazione." }, "transaction_type": { "type": "string", "description": "Categoria di primo livello così come memorizzata: `finance`, `kyc`, `travelRule`, `userPlatformEvent`, `gamblingBet`, `gamblingLimitChange`, `gamblingBonusChange`, `auditTrailEvent`. Nota che i valori composti da più parole vengono restituiti in camelCase anche se inviati in snake_case." }, "action_type": { "type": "string", "description": "Sottotipo all'interno della categoria (ad es. `deposit`, `withdrawal`, `transfer`). Se non specificato, il valore predefinito coincide con la categoria." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direzione rispetto al soggetto. Memorizzato in maiuscolo indipendentemente dal formato inviato (`in`/`out`/`inbound`/`outbound` sono accettati in input)." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Verdetto di monitoraggio attuale. Le transazioni vengono create come `APPROVED`; le regole possono modificarle in `IN_REVIEW`/`DECLINED` in modo sincrono." }, "source": { "type": "string", "enum": [ "LIVE", "IMPORTED" ], "description": "In che modo ha avuto origine il record: `LIVE` per le transazioni inviate tramite API o SDK, `IMPORTED` per le transazioni caricate tramite l'importazione da console." }, "amount": { "type": "string", "description": "Importo della transazione come stringa decimale senza zeri finali (es. `\"1500\"`, `\"0.5\"`, `\"0.123456789012345678\"`). Fino a 18 cifre decimali." }, "currency": { "type": "string", "description": "Codice valuta di `amount`. Viene accettato qualsiasi codice alfabetico ISO 4217 (ad es. `EUR`, `USD`, `NGN`), così come il simbolo di un asset crypto (ad es. `BTC`). È preferibile utilizzare un codice attualmente in circolazione. Non tutti i codici accettati hanno un tasso di cambio: quando non ne è disponibile alcuno per il codice (ad esempio l'unità di conto ISO `XSU` o un simbolo crypto di cui Didit non calcola il prezzo), la conversione automatica non riesce e `preferred_currency_amount` viene restituito null a meno che la richiesta non abbia fornito un `amount_in_default_currency` pre-convertito." }, "currency_type": { "type": "string", "nullable": true, "description": "`fiat` o `crypto`, come inviato in `currency_kind`." }, "amount_in_default_currency": { "type": "string", "nullable": true, "description": "Importo pre-convertito fornito dall'utente, come stringa decimale priva di zeri finali." }, "default_currency_code": { "type": "string", "nullable": true }, "preferred_currency_amount": { "type": "string", "nullable": true, "description": "`amount` convertito nella valuta preferita dell'applicazione, se disponibile." }, "preferred_currency_code": { "type": "string", "nullable": true }, "payment_details": { "type": "string", "nullable": true, "description": "Riferimento di pagamento o promemoria in formato testo libero derivante dall'invio." }, "payment_txn_id": { "type": "string", "nullable": true, "description": "Riferimento del sistema di pagamento esterno (ad es. hash della transazione blockchain) da `payment_reference_id`." }, "score": { "type": "integer", "description": "Punteggio di rischio accumulato dalle regole (in genere 0–100). Più alto = più rischioso." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Gravità categoriale del rischio impostata da regole/provider (`UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`). `null` finché non viene impostata." }, "decision_reason_code": { "type": "string", "nullable": true, "description": "Motivo leggibile dalla macchina per il `status` attuale." }, "decision_reason_label": { "type": "string", "nullable": true, "description": "Etichetta di facile lettura per `decision_reason_code`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Copia per comodità di `vendor_data` del richiedente." }, "metadata": { "type": "object", "description": "Istantanea dei payload di `subject` e `counterparty` così come inviati al momento della creazione." }, "props": { "type": "object", "description": "Le `custom_properties` fornite al momento della creazione. Ciascuna chiave è accessibile nelle condizioni delle regole come `custom_values.`." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "Indica se il tag è predefinito da Didit o personalizzato." } } }, "description": "Tag associati alla transazione (manualmente o tramite regole)." }, "parties": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "APPLICANT", "REMITTER", "BENEFICIARY", "COUNTERPARTY" ], "description": "Ruolo della parte. L'endpoint di creazione assegna `APPLICANT` (il soggetto) e `COUNTERPARTY`." }, "entity_type": { "type": "string", "enum": [ "individual", "company", "external", "unhostedWallet" ] }, "kind": { "type": "string", "enum": [ "USER", "BUSINESS", "EXTERNAL" ], "description": "Le parti `USER`/`BUSINESS` rimandano a un'entità di Didit tramite `vendor_data`. Le parti `EXTERNAL` non hanno alcuna entità Didit associata." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore interno utente/azienda." }, "full_name": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true, "description": "Codice del paese ricavato dal valore `address.country` inviato (in genere ISO 3166-1 alpha-3)." }, "dob": { "type": "string", "format": "date", "nullable": true, "description": "Data di nascita dal valore `date_of_birth` inviato." }, "address": { "type": "object", "description": "Oggetto indirizzo così come inviato. `{}` se omesso." }, "institution_info": { "type": "object", "description": "Dettagli dell'istituto così come inviati. `{}` se omessi." }, "device": { "type": "object", "description": "Contesto del dispositivo normalizzato, compreso l'arricchimento IP lato server sotto network_context (geolocalizzazione, flag VPN/data center) se è stato fornito un indirizzo IP.", "properties": { "fingerprint": { "type": "string", "description": "Impronta digitale univoca del dispositivo." }, "persistent_device_id": { "type": "string", "description": "Identificatore stabile del dispositivo tra sessioni diverse (schema di fingerprint v2)." }, "user_agent": { "type": "string", "description": "Stringa user agent del browser o dell'app." }, "browser_family": { "type": "string", "description": "Famiglia del browser (es. Chrome, Firefox, Safari)." }, "browser_version": { "type": "string", "description": "Stringa della versione del browser." }, "platform": { "type": "string", "description": "Identificatore della piattaforma (web, ios, android, macos, windows, linux)." }, "os_family": { "type": "string", "description": "Famiglia del sistema operativo (ad es. iOS, Android, Windows)." }, "os_version": { "type": "string", "description": "Stringa della versione del sistema operativo." }, "accept_language": { "type": "string", "description": "Valore dell'intestazione Accept-Language." }, "session_id": { "type": "string", "description": "Identificatore della sessione (archiviato nei metadati)." }, "session_age_ms": { "type": "number", "description": "Età della sessione in millisecondi." }, "network_context": { "type": "object", "description": "Contesto di rete con indirizzo IP e geolocalizzazione.", "properties": { "ip_address": { "type": "string", "description": "Indirizzo IP del client." }, "ip_country_code": { "type": "string", "description": "Paese geolocalizzato dell'IP (ISO 3166-1 alpha-3)." }, "latitude": { "type": "number", "description": "Latitudine geografica dell'IP." }, "longitude": { "type": "number", "description": "Longitudine geografica dell'IP." } } } } }, "external_party_snapshot": { "type": "object", "nullable": true, "description": "Copia congelata dei dati della parte per le parti `EXTERNAL`. `null` finché la parte è collegata a un utente o a un'azienda Didit." } } }, "description": "Parti della transazione (richiedente, controparte)." }, "payment_methods": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "payment_method_type": { "type": "string", "enum": [ "bank_card", "bank_account", "e_wallet", "crypto_wallet", "unhosted_wallet", "other" ] }, "label": { "type": "string", "nullable": true }, "fingerprint": { "type": "string", "nullable": true, "description": "SHA-256 su `type:account_id:issuing_country` — identificatore stabile per correlare il riutilizzo dello stesso strumento." }, "account_id": { "type": "string", "nullable": true, "description": "Identificativo dell'account (IBAN, indirizzo, token della carta, …)." }, "issuing_country": { "type": "string", "nullable": true }, "owner_kind": { "type": "string", "enum": [ "USER", "BUSINESS", "EXTERNAL" ] }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore per l'utente o l'azienda proprietari." }, "owner_name": { "type": "string", "nullable": true }, "institution_info": { "type": "object" }, "details": { "type": "object", "description": "Oggetto `payment_method` non elaborato così come inviato." }, "external_owner_snapshot": { "type": "object", "nullable": true }, "role": { "type": "string", "enum": [ "SOURCE", "DESTINATION", "FUNDING", "BENEFICIARY" ], "description": "Come è stato utilizzato questo metodo nella transazione. L'endpoint di creazione assegna `SOURCE`/`DESTINATION` in base alla direzione (in uscita: soggetto = SOURCE; in entrata: soggetto = DESTINATION)." } } }, "description": "Metodi di pagamento collegati alla transazione." }, "documents": { "type": "array", "description": "File allegati alla transazione dalla console. `[]` se non ce ne sono.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "uploaded_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL di download firmato di breve durata; recuperalo quando necessario invece di memorizzarlo." }, "original_filename": { "type": "string", "nullable": true }, "file_size": { "type": "integer", "nullable": true } } } } } } }, "activities": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "activity_type": { "type": "string", "description": "Ad es. `TRANSACTION_CREATED`, `TRANSACTION_NOTE_ADDED`, `TRANSACTION_STATUS_CHANGED`." }, "source": { "type": "string" }, "status": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "occurred_at": { "type": "string", "format": "date-time" } } }, "description": "Voci del registro delle attività (creazione, note, revisioni manuali, modifiche di stato)." }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "severity": { "type": "string", "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "status": { "type": "string", "enum": [ "OPEN", "INVESTIGATING", "AWAITING_USER", "PENDING_SAR", "SAR_FILED", "RESOLVED", "DISMISSED" ] }, "source": { "type": "string", "enum": [ "RULE", "PROVIDER", "MANUAL" ] }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time", "nullable": true } } }, "description": "Attualmente sempre vuoto. Un alert aperto è una transazione con stato `IN_REVIEW` o `AWAITING_USER`." }, "rule_runs": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "rule": { "type": "string", "format": "uuid", "description": "UUID della regola eseguita." }, "rule_title": { "type": "string" }, "rule_description": { "type": "string", "nullable": true }, "rule_category": { "type": "string" }, "matched": { "type": "boolean", "description": "Indica se le condizioni della regola corrispondevano a questa transazione. L'esecuzione viene registrata solo per le regole soddisfatte, pertanto le valutazioni in tempo reale riportano sempre `true`." }, "is_test": { "type": "boolean", "description": "True quando la regola è stata eseguita in modalità TEST (nessun effetto su stato/punteggio)." }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ] }, "severity": { "type": "string", "nullable": true }, "score_delta": { "type": "integer", "description": "Punteggio aggiunto dalle azioni `add_score` di questa regola." }, "status_target": { "type": "string", "nullable": true, "description": "Stato impostato da un'azione `change_status`, se presente." }, "action_summary": { "type": "string", "nullable": true, "description": "Riepilogo delle azioni eseguite dalla regola, unite con `; ` (ad es. `score +30; change_status:IN_REVIEW; add_tag:high_risk_country`). Componenti: `score +N`, `change_status:`, `add_tag:`, `add_note`, `add_to_list`, `open_case`. `null` quando la regola non ha eseguito alcuna azione." }, "metadata": { "type": "object", "description": "Dettaglio di valutazione: `scope_match`, `conditions[]` e `aggregations[]`. Ogni voce di condizione include `field`, `operator`, `expected_value`, il `current_value` letto dalla transazione, `matched`, `group_index` e `group_logic`. Ogni voce di aggregazione (frequenza / conteggio / somma) include `metric`, `field`, `operator`, `expected_value`, il `computed_value` a cui è stata valutata l'aggregazione, `window`, `filters`, `matched` e `sample_references`; le aggregazioni asincrone differite hanno `computed_value: null` e `deferred: true`. Un gruppo di condizioni nidificato è una voce `conditions[]` con `operator` `any_of` o `all_of`, `field` null e i risultati dei relativi membri all'interno del proprio `conditions`." }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "Risultati dell'esecuzione per regola: quale regola è scattata, con quale impatto sul punteggio." }, "provider_results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "result_type": { "type": "string", "enum": [ "FIAT_MONITORING", "WALLET_SCREENING", "TRANSACTION_SCREENING", "TRAVEL_RULE", "NETWORK_GRAPH", "CUSTOM" ] }, "status": { "type": "string" }, "severity": { "type": "string", "nullable": true }, "score": { "type": "integer" }, "summary": { "type": "string", "nullable": true }, "payload": { "type": "object", "description": "Payload di risposta del provider non elaborato." }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "Payload non elaborati del provider (screening AML, analisi blockchain, ecc.)." }, "travel_rule": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TransactionTravelRule" } ], "description": "Trasferimento o controllo Travel Rule. Valorizzato quando `travel_rule_details` è stato inviato e anche quando Travel Rule è abilitata e la transazione è stata creata con `transaction_category: travelRule` (Didit avvia lo scambio direttamente, anche senza `travel_rule_details`). `null` quando non esiste alcun trasferimento o controllo. In un trasferimento in entrata, `originator_data` e `beneficiary_data` della controparte rimangono mascherati (`data_masked: true`) finché non viene confermato l'assetto proprietario del wallet." }, "network_snapshot": { "type": "object", "nullable": true, "description": "Snapshot del grafo delle transazioni/parti correlate utilizzato dal motore di regole. È il `network_snapshot` inviato con la transazione oppure il grafo che Didit crea da uno Screening AML del wallet riuscito (che sostituisce quello inviato). `null` quando nessuno dei due è presente.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "nodes": { "type": "array", "items": { "type": "object" } }, "edges": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "object" } } }, "remediation": { "type": "object", "nullable": true, "description": "Sessione di remediation offerta all'utente quando è richiesta una nuova verifica. Sostituita da `action_required`, che costituisce il blocco canonico; mantenuta per retrocompatibilità.", "properties": { "session_id": { "type": "string" }, "session_token": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string" } } }, "action_required": { "type": "object", "nullable": true, "description": "Azione richiesta all'utente finale e ancora in sospeso per completare questa transazione, oppure null quando non ce n'è alcuna. Gli SDK di Didit avviano automaticamente l'azione per impostazione predefinita e aggiornano la transazione al termine. Due varianti, distinte da `type`: `verification_session` (una sessione di verifica ospitata creata da un'azione di una regola) e `wallet_ownership` (una sessione del widget di proprietà del wallet generata automaticamente per un trasferimento Travel Rule che richiede la prova di controllo del wallet, regolata dall'impostazione Travel Rule `auto_wallet_verification`). Quando potrebbero essere applicate entrambe, `wallet_ownership` ha la precedenza perché blocca lo scambio Travel Rule.", "oneOf": [ { "$ref": "#/components/schemas/TransactionVerificationSessionAction" }, { "$ref": "#/components/schemas/TransactionWalletOwnershipAction" } ], "discriminator": { "propertyName": "type", "mapping": { "verification_session": "#/components/schemas/TransactionVerificationSessionAction", "wallet_ownership": "#/components/schemas/TransactionWalletOwnershipAction" } } }, "cost_breakdown": { "type": "object", "nullable": true, "description": "Costo di questa transazione: `total_price` e `items`, uno per ogni addebito, ciascuno con `usage_type`, `price`, `details` e `created_at`. Un nuovo screening della stessa transazione costituisce una nuova voce." } } }, "TravelRuleSettingsDetail": { "type": "object", "properties": { "is_enabled": { "type": "boolean", "description": "Indica se il flusso gestito di negoziazione Travel Rule è attivo per le transazioni `travelRule` in uscita su questa applicazione." }, "jurisdiction": { "type": "string", "maxLength": 8, "description": "Il codice della giurisdizione operativa del tuo VASP. Predefinito `\"EU\"`. Didit lo mappa nel regime che appone sulle tue transazioni Travel Rule come `travel_rule_regime` (ad esempio `EU` o il codice di un paese membro dell'UE diventa `eu`), su cui le regole di transazione possono basarsi. Gli altri clienti Didit lo vedono come la tua giurisdizione nella directory dei VASP una volta che la rete Didit inserisce il tuo profilo nella directory." }, "name_matching_strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Il livello di rigore con cui i nomi dei beneficiari devono corrispondere prima che un trasferimento possa raggiungere lo stato COMPLETED. `CONTAINS` accetta un nome le cui parole compaiono tutte nell'altro." }, "confirmation_timeout_hours": { "type": "integer", "minimum": 1, "description": "Ore durante le quali un trasferimento AWAITING_COUNTERPARTY può rimanere non confermato prima che il processo periodico di pulizia lo dichiari scaduto. Valore predefinito: 48." }, "timeout_outcome": { "type": "string", "enum": [ "HOLD", "REJECT", "PROCEED" ], "description": "Cosa succede alla transazione sottostante quando un trasferimento scade. Valore predefinito HOLD. sunrise_policy e non_responsive_policy hanno la precedenza quando sono applicabili e configurate." }, "threshold_amount": { "type": "string", "description": "Stringa decimale, nella valuta predefinita della tua applicazione. Importo minimo di trasferimento che attiva uno scambio gestito; i trasferimenti inferiori ad esso si risolvono direttamente in NOT_APPLICABLE. Didit confronta l'importo della transazione convertito nella tua valuta predefinita, o l'importo `amount_in_default_currency` inviato; quando non è disponibile alcun importo convertito, la soglia non si applica. Il valore predefinito è \"0.00\" (il TFR dell'UE non applica alcun importo minimo)." }, "ownership_validation_mode": { "type": "string", "enum": [ "FULL", "SIMPLIFIED", "AUTOMATED" ], "description": "Il livello di prova richiesto per l'assetto proprietario di un wallet. `FULL` richiede sempre una prova (messaggio firmato, deposito di prova o screenshot verificato), mai la sola dichiarazione dell'utente finale. `SIMPLIFIED` accetta un'autodichiarazione al di sotto di `simplified_validation_threshold` e una prova al di sopra. `AUTOMATED` consente alla rubrica e a prove precedenti di rispondere autonomamente, incluse le autodichiarazioni quando `allow_self_declaration` è true. Il valore predefinito è `AUTOMATED`." }, "simplified_validation_threshold": { "type": "string", "description": "Stringa decimale, valore predefinito \"0.00\". In modalità `SIMPLIFIED`, un trasferimento inferiore a questo importo (nella valuta della soglia) accetta un'autodichiarazione. Un trasferimento senza importo in tale valuta viene considerato superiore ad essa." }, "data_sharing_fields": { "$ref": "#/components/schemas/TravelRuleDataSharingFields" }, "matching_rules": { "$ref": "#/components/schemas/TravelRuleMatchingRules" }, "legal_name": { "type": "string", "description": "La ragione sociale del tuo VASP. Obbligatoria (non vuota) per impostare is_enabled su true." }, "lei": { "type": "string", "description": "Il tuo Legal Entity Identifier, visibile nella directory dei VASP." }, "compliance_email": { "type": "string", "format": "email", "description": "Email di contatto per la compliance per il tuo profilo VASP. La rete Didit mostra il tuo profilo solo dopo che questo indirizzo è stato confermato tramite un link inviato via email (POST /v3/travel-rule/settings/compliance-email/confirmation/); la modifica richiede una nuova conferma." }, "is_discoverable": { "type": "boolean", "description": "Indica se il tuo profilo VASP può essere elencato nella rete Didit: trovato in GET /v3/travel-rule/vasps/ da altri clienti Didit e raggiunto tramite il canale INTERNAL. L'inserimento nell'elenco richiede inoltre un'applicazione attiva, Travel Rule abilitata, una ragione sociale e un'email di compliance confermata; didit_network indica quali requisiti mancano. Predefinito true." }, "inbound_auto_accept": { "type": "boolean", "description": "Se true, un'indagine TRP in entrata il cui wallet beneficiario è una voce verificata della rubrica con un nome corrispondente viene approvata automaticamente. Se false, tale indagine rimane in ON_HOLD in attesa che tu la approvi o la rifiuti con l'endpoint dell'assetto proprietario. I trasferimenti su canale INTERNAL e successivi al deposito non sono interessati. Il valore predefinito è true." }, "allow_self_declaration": { "type": "boolean", "description": "Se true, il widget di titolarità del wallet offre l'autodichiarazione come metodo di prova di riserva. Il valore predefinito è true." }, "allow_screenshot_proof": { "type": "boolean", "description": "Se true, il widget di titolarità del wallet offre il caricamento di screenshot come metodo di prova dell'assetto proprietario. Il valore predefinito è true." }, "auto_wallet_verification": { "type": "boolean", "description": "Se true, l'invio di un trasferimento Travel Rule in uscita che richiede la prova del controllo del wallet da parte dell'utente finale genera automaticamente una sessione del widget di titolarità del wallet associata alla transazione e la espone nel blocco action_required della transazione. Il valore predefinito è true." }, "vasp_attribution_enabled": { "type": "boolean", "description": "Se true, un trasferimento Travel Rule in uscita che nessun canale può instradare viene attribuito tramite analisi blockchain: il wallet di destinazione viene ricondotto al VASP che lo possiede, l'entità viene registrata sul trasferimento e nella directory VASP, e i canali vengono rieseguiti una volta con il nome attribuito. Il valore predefinito è true." }, "counterparty_screening_enabled": { "type": "boolean", "description": "Screening opzionale su sanzioni e notizie negative dei VASP di controparte, fatturato per screening al prezzo di Screening AML per aziende. Se attivo, Didit esegue lo screening della controparte raggiunta da un trasferimento in uscita (riutilizzando uno screening effettuato da meno di 30 giorni) e puoi eseguirne uno con POST /v3/travel-rule/vasps/{vasp_id}/screening/. Il valore predefinito è false: non viene eseguito alcuno screening né addebitato alcun costo." }, "sunrise_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "Effetto di un trasferimento scaduto sulla relativa transazione quando la controparte è una voce di directory in una giurisdizione presente in sunrise_jurisdictions, che non applica ancora la Travel Rule: HOLD lo sposta in revisione, REJECT lo rifiuta, PROCEED ne lascia inalterato lo stato. Se vuoto (impostazione predefinita), segue timeout_outcome. Si applica prima di non_responsive_policy." }, "sunrise_jurisdictions": { "type": "array", "items": { "type": "string" }, "readOnly": true, "description": "Sola lettura. I paesi (ISO 3166 alpha-2) che Didit considera in un periodo di entrata in vigore per la Travel Rule (sunrise period), in cui si applica sunrise_policy. Attualmente CO, KH e VN. Qualsiasi altra giurisdizione, nonché una vuota o sconosciuta, segue timeout_outcome." }, "non_responsive_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "Effetto di un trasferimento scaduto sulla relativa transazione quando la controparte è una voce di directory la cui capacità di risposta è UNRESPONSIVE: HOLD, REJECT o PROCEED, come per timeout_outcome. Se vuoto (impostazione predefinita), segue timeout_outcome. sunrise_policy si applica per prima se entrambe sono pertinenti." }, "travel_address": { "type": "string", "description": "Sola lettura. Il Travel Address del tuo VASP: l'endpoint codificato per le richieste TRP in entrata utilizzato dagli altri VASP per contattarti. Vuoto finché `is_enabled` è false." }, "disabled_networks": { "type": "array", "items": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "description": "Reti escluse dall'adesione alla piattaforma. Non disabilita le proprie adesioni connesse né effettua il provisioning di reti non disponibili.", "default": [] }, "networks": { "type": "object", "readOnly": true, "description": "Per ciascuna rete, come questa applicazione invierebbe e perché non può farlo. Nessuna rete, inclusa GTR, è inclusa per impostazione predefinita: una rete è raggiungibile tramite la tua adesione connessa, oppure tramite l'adesione di Didit una volta che l'adesione di Didit a tale rete è attiva e il tuo partecipante su di essa è attivo. Non si tratta di un controllo di stato o consegna in tempo reale.", "properties": { "gtr": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "trust": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "verifyvasp": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "sygna": { "$ref": "#/components/schemas/TravelRuleNetworkState" } } }, "didit_network": { "type": "object", "readOnly": true, "description": "Indica se la rete Didit elenca il tuo profilo VASP, in modo che altri clienti Didit possano trovarlo nella directory e raggiungerlo sul canale INTERNAL, e ciascuna condizione che ancora non soddisfa.", "properties": { "listed": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "travel_rule_off", "sandbox_application", "not_discoverable", "legal_name_missing", "compliance_email_missing", "compliance_email_unconfirmed", "excluded_by_staff", "internal_organization" ] }, "description": "Vuoto quando presente nell'elenco. compliance_email_unconfirmed: invia la conferma con POST /v3/travel-rule/settings/compliance-email/confirmation/ e apri il link ricevuto via email. excluded_by_staff: Didit ha contrassegnato l'applicazione come di test, demo o interna." }, "compliance_email_confirmed": { "type": "boolean", "description": "Indica se l'attuale compliance_email è stata confermata tramite il link inviato via email." } } } } }, "TravelRuleSettingsUpdate": { "type": "object", "properties": { "is_enabled": { "type": "boolean" }, "legal_name": { "type": "string", "maxLength": 255 }, "lei": { "type": "string", "maxLength": 20 }, "jurisdiction": { "type": "string", "maxLength": 8 }, "name_matching_strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "`CONTAINS` accetta un nome le cui parole compaiono tutte nell'altro." }, "confirmation_timeout_hours": { "type": "integer", "minimum": 1 }, "timeout_outcome": { "type": "string", "enum": [ "HOLD", "REJECT", "PROCEED" ] }, "compliance_email": { "type": "string", "format": "email", "description": "Email di contatto per la compliance per il tuo profilo VASP. La rete Didit mostra il tuo profilo solo dopo che questo indirizzo è stato confermato tramite un link inviato via email (POST /v3/travel-rule/settings/compliance-email/confirmation/); la modifica richiede una nuova conferma." }, "is_discoverable": { "type": "boolean", "description": "Indica se il tuo profilo VASP può essere elencato nella rete Didit: trovato in GET /v3/travel-rule/vasps/ da altri clienti Didit e raggiunto tramite il canale INTERNAL. L'inserimento nell'elenco richiede inoltre un'applicazione attiva, Travel Rule abilitata, una ragione sociale e un'email di compliance confermata; didit_network indica quali requisiti mancano. Predefinito true." }, "threshold_amount": { "type": "string", "description": "Stringa decimale, pari o superiore a zero, nella valuta predefinita della tua applicazione. Importo minimo di trasferimento che attiva uno scambio gestito." }, "ownership_validation_mode": { "type": "string", "enum": [ "FULL", "SIMPLIFIED", "AUTOMATED" ], "description": "Vedere il campo di risposta con lo stesso nome." }, "simplified_validation_threshold": { "type": "string", "description": "Stringa decimale, pari o superiore a 0." }, "data_sharing_fields": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleDataSharingFields" } ], "description": "Unito per tipo di entità: un tipo di entità che ometti mantiene la scelta corrente. Una scelta che non soddisfa gli obblighi relativi all'ordinante previsti dal regime della tua `jurisdiction` (EU TFR o FATF Recommendation 16), inclusa una lista vuota, viene rifiutata con `400`." }, "matching_rules": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleMatchingRules" } ], "description": "Unito per tipo di entità e per campo al suo interno. Un campo che tale tipo di entità non confronta (ad esempio `date_of_birth` per `company`) viene rifiutato con `400`." }, "inbound_auto_accept": { "type": "boolean" }, "allow_self_declaration": { "type": "boolean" }, "allow_screenshot_proof": { "type": "boolean", "description": "Se true, il widget di titolarità del wallet offre il caricamento di screenshot come metodo di prova dell'assetto proprietario. Il valore predefinito è true." }, "auto_wallet_verification": { "type": "boolean" }, "vasp_attribution_enabled": { "type": "boolean" }, "counterparty_screening_enabled": { "type": "boolean", "description": "Screening opzionale su sanzioni e notizie negative dei VASP di controparte, fatturato per screening al prezzo di Screening AML per aziende. Se attivo, Didit esegue lo screening della controparte raggiunta da un trasferimento in uscita (riutilizzando uno screening effettuato da meno di 30 giorni) e puoi eseguirne uno con POST /v3/travel-rule/vasps/{vasp_id}/screening/. Il valore predefinito è false: non viene eseguito alcuno screening né addebitato alcun costo." }, "sunrise_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "HOLD, REJECT, PROCEED o vuoto per seguire timeout_outcome. Consulta il campo di risposta con lo stesso nome." }, "non_responsive_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "HOLD, REJECT, PROCEED o vuoto per seguire timeout_outcome. Consulta il campo di risposta con lo stesso nome." }, "disabled_networks": { "type": "array", "items": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "description": "Reti escluse dall'adesione alla piattaforma. Non disabilita le proprie adesioni connesse né effettua il provisioning di reti non disponibili.", "default": [] } }, "description": "Tutti i campi sono opzionali; PUT applica un aggiornamento parziale." }, "WalletAddressEntry": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "address": { "type": "string", "description": "L'indirizzo del wallet; `\"\"` per una voce importata solo tramite il suo hash. Univoco per applicazione, rete e memo, confrontando l'indirizzo senza fare distinzione tra maiuscole e minuscole. Dopo aver eliminato una voce, puoi registrare nuovamente lo stesso indirizzo." }, "chain": { "type": "string", "description": "Token di chain per l'indirizzo, ad esempio `ETH` o `BTC`. Quando Didit instrada o registra un trasferimento, associa le voci della rubrica in base all'indirizzo e, quando il trasferimento include una chain, anche su questo valore, ignorando maiuscole e minuscole. La chain di un trasferimento è `beneficiary_data.chain`, compilata a partire dalla chain crypto o dal simbolo della valuta della transazione (ad esempio `ETH`) quando non la invii, oppure la `chain` di una registrazione successiva al deposito, quindi usa lo stesso token ovunque. Una voce con una chain vuota corrisponde a qualsiasi chain. Un beneficiario Lightning (un id di nodo o un indirizzo Lightning) registrato su bitcoin viene memorizzato in minuscolo su `LIGHTNING`, dove vengono associati i trasferimenti Lightning. Le chain note vengono memorizzate con un identificatore canonico indipendentemente da come vengono scritte: \"ethereum\", \"Ethereum\" ed \"ERC20\" sono tutte memorizzate come ETH, \"BNB Smart Chain\" e \"BEP20\" come BNB, \"tron\" come TRX. Un nome di chain sconosciuto viene mantenuto così come fornito." }, "holder_vendor_data": { "type": "string", "description": "Il tuo identificatore interno per il titolare." }, "holder_name": { "type": "string", "description": "Nome del titolare del wallet, utilizzato per la corrispondenza del nome del beneficiario." }, "entity_type": { "type": "string", "description": "Testo libero, il valore predefinito è \"individual\"." }, "is_ownership_verified": { "type": "boolean", "description": "Sola lettura. Indica se la proprietà di questo indirizzo è stata comprovata." }, "created_at": { "type": "string", "format": "date-time" }, "travel_address": { "type": "string", "description": "Il Travel Address del VASP di controparte per questo wallet, se noto. Consente a Didit di instradare i trasferimenti di questo beneficiario tramite il canale TRP, per gli asset supportati da TRP (BTC, ETH e USDC su una rete specifica)." }, "address_hash": { "type": "string", "description": "Sola lettura. SHA-256 dell'indirizzo in caratteri minuscoli, in formato esadecimale minuscolo. Una voce importata unicamente tramite il suo hash viene confrontata in base a questo valore." }, "memo": { "type": "string", "description": "Il destination tag o memo che fa parte del wallet su una rete con memo (XRP, XLM, EOS, ATOM, HBAR); `\"\"` per l'intero indirizzo. Una voce con un memo corrisponde solo ai trasferimenti che indicano tale memo; una voce senza memo corrisponde all'intero indirizzo." }, "receiving_travel_address": { "type": "string", "readOnly": true, "description": "Il tuo Travel Address per questo wallet: forniscilo al VASP mittente affinché la sua richiesta TRP indichi questo wallet. Vuoto per un wallet registrato come appartenente a un altro VASP, quando la Travel Rule è disattivata e prima che il tuo profilo VASP sia salvato." } } }, "WalletAddressEntryCreate": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "maxLength": 128, "description": "L'indirizzo del wallet. Un indirizzo X-address XRP viene memorizzato come indirizzo classico e relativo tag, in modo da corrispondere ai trasferimenti che specificano uno dei due formati." }, "chain": { "type": "string", "maxLength": 32, "description": "Token della blockchain per l'indirizzo, ad esempio `ETH` o `BTC`. Quando Didit instrada o registra un trasferimento, confronta le voci della rubrica sull'indirizzo del wallet e, quando il trasferimento include una blockchain, anche su questo valore, ignorando maiuscole e minuscole. La blockchain di un trasferimento è `beneficiary_data.chain`, compilata a partire dalla blockchain crypto o dal simbolo di valuta della transazione (ad esempio `ETH`) quando non la invii, oppure la `chain` di una registrazione post-deposito, quindi usa lo stesso token ovunque. Una voce con una blockchain vuota corrisponde a qualsiasi blockchain. Le blockchain note sono memorizzate sotto un unico identificatore canonico indipendentemente dall'ortografia inviata: \"ethereum\", \"Ethereum\" e \"ERC20\" sono tutte memorizzate come ETH, \"BNB Smart Chain\" e \"BEP20\" come BNB, \"tron\" come TRX. Il nome di una blockchain sconosciuta viene mantenuto così come fornito." }, "holder_vendor_data": { "type": "string", "maxLength": 255 }, "holder_name": { "type": "string", "maxLength": 255 }, "entity_type": { "type": "string", "default": "individual", "maxLength": 16 }, "self_declared": { "type": "boolean", "default": false, "description": "Sola scrittura. Quando true, la voce viene creata con l'assetto proprietario già verificato tramite una prova SELF_DECLARATION. Restituisce 400 quando `allow_self_declaration` è disattivato nelle impostazioni della Travel Rule." }, "travel_address": { "type": "string", "description": "Opzionale. Il Travel Address del VASP della controparte per questo wallet, abilitando l'instradamento TRP per gli asset gestiti da TRP (BTC, ETH e USDC su una rete specificata). Un Travel Address non valido restituisce 400.", "maxLength": 512 }, "memo": { "type": "string", "maxLength": 256, "description": "Opzionale. Il destination tag o memo che fa parte del wallet. XRP: un destination tag, un numero intero da 0 a 4294967295 (è accettato un numero JSON). XLM: un memo di testo fino a 28 byte, un ID a 64 bit o un hash a 32 byte in esadecimale. EOS: fino a 256 byte. ATOM: fino a 256 caratteri. HBAR: fino a 100 byte. I wallet Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning non accettano memo: specificarne uno restituisce `400`. Alias: `destinationTag` o `destination_tag`." } } }, "WalletAddressEntryUpdate": { "type": "object", "properties": { "holder_name": { "type": "string", "maxLength": 255 }, "holder_vendor_data": { "type": "string", "maxLength": 255 }, "entity_type": { "type": "string", "maxLength": 16 }, "travel_address": { "type": "string", "maxLength": 512 } }, "description": "PATCH è un aggiornamento parziale; la risposta restituisce solo holder_name, holder_vendor_data, entity_type, travel_address, receiving_travel_address, label e owner_type." }, "TravelRuleTransferDetail": { "type": "object", "description": "Oggetto di trasferimento completo restituito dagli endpoint di conferma della titolarità e di completamento/annullamento. Finché la titolarità del wallet di un trasferimento in entrata non è confermata, i campi `originator_data` e `beneficiary_data` della controparte vengono restituiti mascherati (viene mantenuta la prima lettera di ogni parola; il wallet, la chain e l'instradamento VASP rimangono leggibili) e `data_masked` è true.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "AWAITING_COUNTERPARTY", "ON_HOLD", "COMPLETED", "FINISHED", "CANCELLED", "EXPIRED", "COUNTERPARTY_MISMATCHED_DATA", "COUNTERPARTY_VASP_NOT_FOUND", "COUNTERPARTY_VASP_NOT_REACHABLE", "UNCONFIRMED_OWNERSHIP", "COUNTERPARTY_VASP_GENERAL_DECLINE", "NOT_ENOUGH_COUNTERPARTY_DATA", "NOT_APPLICABLE" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "rail": { "type": "string", "nullable": true, "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "TEST_VASP", null ], "description": "Il canale (rail) su cui è stato instradato il trasferimento, o null quando non è stato selezionato alcun canale (ad esempio sotto la soglia, un wallet della controparte in autocustodia, una registrazione post-deposito o nessuna controparte raggiungibile). INTERNAL indica che entrambe le parti sono applicazioni Didit; EMAIL indica che la controparte è stata raggiunta tramite un link di ritiro inviato via email. TEST_VASP indica che il Didit Test VASP ha risposto al trasferimento sandbox. Tramite GTR, VERIFYVASP e SYGNA, Didit legge la risposta della controparte dalla risposta della rete o effettuando un polling ogni 5 minuti. TRUST invia soltanto, quindi un trasferimento TRUST rimane AWAITING_COUNTERPARTY fino alla scadenza. Un canale di rete viene utilizzato solo dopo aver collegato la propria iscrizione per tale rete. Viene scelto dopo che la creazione della transazione ha restituito risposta, quindi è null in tale risposta." }, "protocol": { "type": "string", "nullable": true }, "ivms_version": { "type": "string", "example": "ivms101.2023" }, "required": { "type": "boolean" }, "ownership_confirmed": { "type": "boolean", "nullable": true }, "deadline_at": { "type": "string", "format": "date-time", "nullable": true }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "detail": { "type": "string" }, "name_match": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleNameMatch" } ], "nullable": true, "description": "Il confronto dei nomi che ha determinato questa voce, accanto a `detail`. Assente nelle voci che non hanno confrontato alcun nome." }, "reason": { "type": "string", "description": "Presente solo sulla voce di una transizione causata da una mancata consegna: `email_undeliverable` o `delivery_failed`, il valore riportato da `reason` del trasferimento." } } } }, "counterparty_vasp": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "lei": { "type": "string" }, "dd_score": { "type": "integer", "description": "Punteggio di due diligence da 0 a 100, dove un valore più alto è migliore. Stessa scala utilizzata nella directory dei VASP." }, "dd_score_breakdown": { "type": "object", "description": "Contributi per componente a dd_score, un oggetto per componente come nella directory VASP (giurisdizione, verifica, protocollo, lei, cronologia, elementi essenziali, reattività), ciascuno con {points, max, reason, detail}. {} finché la controparte non è stata valutata.", "additionalProperties": { "type": "object", "properties": { "points": { "type": "number", "description": "Punti assegnati per questo componente." }, "max": { "type": "integer", "description": "Punti massimi che questo componente può assegnare." }, "reason": { "type": "string", "description": "Codice leggibile dalla macchina dell'esito del componente." }, "detail": { "type": "string", "description": "Motivo leggibile dall'utente per i punti assegnati." } } } }, "dd_assessed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultima esecuzione della valutazione di adeguata verifica. Null finché la controparte non è stata valutata." } } }, "originator_data": { "type": "object", "description": "Soggetto ordinante. Per un trasferimento in entrata, i valori della controparte sono oscurati fino alla conferma dell'assetto proprietario." }, "beneficiary_data": { "type": "object", "description": "Parte beneficiaria. Per un trasferimento in entrata i valori della controparte sono mascherati fino a quando non viene confermato l'assetto proprietario." }, "name_match": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleNameMatch" } ], "nullable": true, "description": "Il confronto dei nomi che ha determinato il trasferimento, o null fino all'esecuzione. Mentre le parti sono oscurate, e sulla copia dell'altro cliente di uno scambio INTERNAL, `transfer_name`, `compared_name`, `matched_names` e `mismatched_names` rimangono nascosti. `score` e `matched` possono discordare: `matched` segue il livello di rigore, `score` è la somiglianza dei due nomi completi." }, "data_match": { "$ref": "#/components/schemas/TravelRuleDataMatch" }, "mismatched_fields": { "type": "array", "items": { "type": "string" }, "description": "Scorciatoia per `data_match.mismatched_fields`. Vuoto quando non ci sono differenze." }, "data_unmasked": { "$ref": "#/components/schemas/TravelRuleDataUnmasked" }, "data_masked": { "type": "boolean", "description": "True mentre i dati personali della controparte sono mascherati in questa risposta." }, "created_at": { "type": "string", "format": "date-time" }, "delivery": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TravelRuleDelivery" } ], "description": "Lo stato dell'ultimo messaggio dovuto da questo trasferimento alla controparte. Null quando il trasferimento non ha mai dovuto inviarne uno (ad esempio al di sotto di `threshold_amount`, un wallet in autocustodia dichiarato o una registrazione sunrise)." }, "discovery": { "type": "array", "description": "Modalità con cui Didit ha cercato la controparte, una voce per ogni passaggio eseguito. Vuoto se non è stata eseguita alcuna ricerca, ad esempio per un trasferimento in entrata.", "items": { "$ref": "#/components/schemas/TravelRuleDiscoveryStep" } }, "reason": { "type": "string", "description": "Il motivo per cui un trasferimento `COUNTERPARTY_VASP_NOT_FOUND` o `COUNTERPARTY_VASP_NOT_REACHABLE` è bloccato; `\"\"` per qualsiasi altro stato. Una consegna non riuscita lo determina per prima, solo su `COUNTERPARTY_VASP_NOT_REACHABLE`: `email_undeliverable` (il provider di posta ha rifiutato l'email di compliance e non è rimasto alcun indirizzo da provare: quando è stata inviata, in un promemoria o come bounce permanente segnalato successivamente) o `delivery_failed` (il canale che effettuava la consegna è fallito definitivamente: un canale di rete ha rifiutato il messaggio o ha esaurito i tentativi, un host di identità `TRP` non ha risposto o l'host `TRP` della controparte non ha accettato la richiesta). Altrimenti lo determina la traccia di `discovery`: `awaiting_end_user` (nessun passaggio ha indicato una controparte raggiungibile da Didit), `directory_match_no_route` (un passaggio ha indicato un VASP della directory privo di rotta), `picked_member_without_proven_wallet` (l'utente finale ha scelto un cliente Didit che non ha dimostrato il controllo del wallet) o `no_directory_match` quando la traccia non fornisce altri motivi. Un nuovo invio fa avanzare il trasferimento, quindi il motivo viene azzerato. Consulta [Perché un trasferimento è bloccato](/it/transaction-monitoring/travel-rule#perché-un-trasferimento-è-bloccato)." }, "next_actions": { "type": "array", "description": "Cosa fa procedere il trasferimento; `[]` per qualsiasi stato tranne `COUNTERPARTY_VASP_NOT_FOUND` o `COUNTERPARTY_VASP_NOT_REACHABLE`. `email_undeliverable` propone `update_compliance_email`, poi `resend`. `delivery_failed` propone `resend`. Un motivo di discovery propone `select_counterparty_vasp`, `declare_self_hosted`, `add_vasp_hint` e `resend`.", "items": { "$ref": "#/components/schemas/TravelRuleNextAction" } }, "chain_details": { "$ref": "#/components/schemas/TravelRuleChainDetails" } } }, "TravelRuleOwnershipConfirmRequest": { "type": "object", "required": [ "confirmed" ], "properties": { "confirmed": { "type": "boolean", "description": "true per confermare l'assetto proprietario, false per negarlo." }, "wallet_address": { "type": "string", "default": "", "description": "Trasferimenti TRP in entrata: l'indirizzo di pagamento restituito da Didit al VASP ordinante al momento dell'approvazione. Il valore predefinito corrisponde all'indirizzo della voce della rubrica corrispondente, quindi a beneficiary_data.wallet_address. Nel caso di un trasferimento dichiarato verso un wallet in autocustodia che non specifica un wallet di controparte, il wallet di cui hai verificato l'assetto proprietario; in sua assenza la richiesta viene rifiutata con 400. Ignorato per altri trasferimenti." } } }, "TravelRuleTransferPatchRequest": { "type": "object", "description": "Fornisci esattamente uno tra: payment_txn_id (finish), action=cancel, action=resend, action=update_compliance_email con compliance_email, action=update_originator_wallet con wallet_address o action=beneficiary_vasp con beneficiary_vasp.", "properties": { "payment_txn_id": { "type": "string", "description": "L'hash della transazione on-chain. Richiede che il trasferimento sia un trasferimento in uscita con stato COMPLETED." }, "action": { "type": "string", "enum": [ "cancel", "resend", "update_compliance_email", "update_originator_wallet", "beneficiary_vasp" ], "description": "\"cancel\" annulla un trasferimento non definitivo. \"resend\" esegue nuovamente l'instradamento per un trasferimento in uscita bloccato in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE o NOT_ENOUGH_COUNTERPARTY_DATA. \"update_compliance_email\" sostituisce l'email di compliance a cui viene inviata la richiesta, per un trasferimento in uscita in uno di questi tre stati; invia successivamente \"resend\". \"update_originator_wallet\" registra il wallet da cui sono effettivamente partiti i fondi (`wallet_address`, `memo`). \"beneficiary_vasp\" indica direttamente il VASP di controparte (richiede `beneficiary_vasp`) per un trasferimento in uscita in uno di questi stati: viene instradato verso quel VASP e inviato di nuovo." }, "compliance_email": { "type": "string", "format": "email", "maxLength": 254, "description": "Obbligatorio con `action: update_compliance_email`. Mantenuto come `beneficiary_data.counterparty_vasp_email` di questo trasferimento: appartiene esclusivamente a questo trasferimento e non viene aggiunto a nessuna voce di directory né ad alcuna lista di contatti." }, "wallet_address": { "type": "string", "maxLength": 128, "description": "Con `action: update_originator_wallet`: il wallet da cui sono partiti i fondi. Quando gli input UTXO del trasferimento sono noti, deve essere uno di essi." }, "memo": { "type": "string", "maxLength": 256, "description": "Con `action: update_originator_wallet`: il memo o tag del wallet su una rete memo. Opzionale." }, "beneficiary_vasp": { "type": "string", "format": "uuid", "description": "Obbligatorio con action=beneficiary_vasp: l'`id` di un VASP della directory, ottenuto da `GET /v3/travel-rule/vasps/`. La tua scelta ha la priorità su ogni passaggio di rilevamento automatico, che non la sovrascrive mai." } } }, "VaspDirectoryEntry": { "type": "object", "description": "Un VASP della directory o un membro della rete Didit, con i percorsi a disposizione della tua applicazione per raggiungerlo. Un cliente è membro della rete Didit solo finché la sua applicazione è in produzione, la sua Travel Rule è attiva, il suo profilo è individuabile, possiede una ragione sociale e un'email di compliance confermata, e Didit non ha contrassegnato l'applicazione come test, demo o interna. Ogni riga include inoltre la valutazione condivisa di due diligence (dd_score, risk_level, responsiveness, essential_checks) e la decisione, lo screening dell'entità e i questionari specifici della tua applicazione, che nessun altro cliente può visualizzare.", "properties": { "id": { "type": "string", "format": "uuid", "description": "L'ID della voce, per GET /v3/travel-rule/vasps/{vasp_id}/." }, "kind": { "type": "string", "enum": [ "directory", "didit" ], "description": "directory per una voce della directory condivisa; didit per un membro della rete Didit." }, "name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string", "description": "Codice paese ISO 3166, così come fornito dalla fonte." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "I domini web del VASP. Sempre vuoto per i membri della rete Didit." }, "reachable": { "type": "boolean", "description": "Indica se la tua applicazione dispone di una route disponibile verso questo VASP o verso una delle sue entità per un brand. Sempre true per un membro della rete Didit, tranne su un'applicazione sandbox, dove ogni riga è false." }, "aliases": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "trading_name", "other_legal_name", "network_name", "attribution", "merged", "staff" ], "description": "trading_name, other_legal_name (dal registro LEI globale), network_name (il nome su una rete Travel Rule), attribution (il nome dell'entità attribuito ai wallet del VASP dalle analisi blockchain), merged (il nome di una voce duplicata unita a questa) o staff." } } }, "description": "Altri nomi con cui viene individuato il VASP." }, "networks": { "type": "array", "items": { "type": "object", "description": "Un elenco corrente di questo VASP nella directory dei membri di una rete Travel Rule. Un elenco TRISA indica chi sia il VASP su TRISA; Didit non dispone di una via TRISA, quindi non costituisce mai un percorso.", "properties": { "network": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA", "TRISA" ] }, "code": { "type": "string", "description": "L'identificatore del VASP su tale rete." }, "listed_name": { "type": "string", "description": "Il nome con cui la rete elenca il VASP." }, "country": { "type": "string", "description": "Il paese indicato dalla rete, se disponibile." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il personale di Didit ha verificato la voce. Null per le voci lette da un elenco pubblico." }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando la fonte ha mostrato la voce per l'ultima volta. Una voce che la fonte non mostra per tre settimane viene rimossa." }, "source": { "type": "string", "enum": [ "trisa_directory", "staff" ], "description": "L'origine dell'elenco: la directory pubblica TRISA o il personale di Didit." } } } }, "routes": { "type": "array", "items": { "type": "object", "description": "Una modalità con cui la tua applicazione può recapitare i dati della Travel Rule a questo VASP, nell'ordine in cui vengono provati dal dispatch. Un percorso di rete richiede un'adesione a tale rete: la tua (connessa nel Marketplace) o quella di Didit una volta che Didit ne dispone. Senza di essa, il percorso è indicato come non disponibile con la relativa motivazione, mai come modalità per raggiungere il VASP.", "properties": { "rail": { "type": "string", "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL" ] }, "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "reason": { "type": "string", "enum": [ "", "no_membership", "network_switched_off", "sandbox_application" ], "description": "Il motivo per cui una rotta non disponibile non può essere utilizzata: no_membership (né tu né Didit avete un'adesione a quella rete), network_switched_off (hai disattivato quella rete nelle tue impostazioni) o sandbox_application (un'applicazione sandbox invia solo al VASP di test di Didit, pertanto non è disponibile alcuna rotta verso di essa). Vuoto quando la rotta è disponibile." }, "via": { "type": "string", "enum": [ "", "own_membership", "didit_membership", "directory", "contact", "didit_network" ], "description": "Come viene raggiunto un percorso disponibile: own_membership o didit_membership per un canale di rete, directory per un endpoint TRP verificato dalla directory, contact per il canale EMAIL, didit_network per un membro della rete Didit. Vuoto quando il percorso non è disponibile." } } } }, "umbrella": { "type": "object", "nullable": true, "description": "Il brand di cui questa voce è un'entità regolamentata. Null quando non ne fa parte.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "entities": { "type": "array", "items": { "type": "object", "description": "Un'entità regolamentata di un brand: la persona giuridica che riceve un trasferimento.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string" }, "reachable": { "type": "boolean", "description": "Indica se la tua applicazione dispone di una route disponibile verso di essa." } } }, "description": "Per un brand, le entità regolamentate che ricevono i suoi trasferimenti. Un trasferimento che menziona il brand va all'entità raggiungibile nella giurisdizione dichiarata (beneficiary_data.counterparty_vasp_jurisdiction), altrimenti all'entità collegata al wallet di destinazione tramite l'attribuzione di analisi blockchain, altrimenti all'unica entità raggiungibile quando non è dichiarata alcuna giurisdizione. In caso di due entità ugualmente compatibili, non viene mai fatta un'ipotesi arbitraria." }, "contacts": { "type": "array", "items": { "type": "object", "description": "Un contatto di compliance a cui la via EMAIL può scrivere.", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "staff", "application", "learned" ], "description": "staff: curato da Didit; application: aggiunto dalla tua applicazione; learned: un indirizzo che ha risposto a una richiesta Travel Rule tramite il relativo link di risposta." }, "scope": { "type": "string", "enum": [ "platform", "application" ], "description": "I contatti della piattaforma sono utilizzati per i trasferimenti di ogni cliente Didit; i contatti dell'applicazione sono privati per la tua applicazione, che vede solo i propri." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando qualcuno a questo indirizzo ha risposto a una richiesta. Null se non è ancora successo." } } }, "description": "I contatti della piattaforma per questo VASP e quelli della tua applicazione." }, "dd_status": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "REJECTED" ], "description": "Stato di verifica della voce secondo Didit, valutato dalla componente di verifica di dd_score. Sempre COMPLETED per un membro della rete Didit." }, "dd_score": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 100, "description": "Il punteggio di due diligence condiviso di una voce dell'elenco, da 0 a 100, dove un valore più alto è più sicuro (vedi dd_score_semantic): la somma dei punti in dd_score_breakdown. Null per un membro della rete Didit, che non viene valutato. Una voce non ancora valutata (dd_assessed_at null) mostra 0 con un risk_level vuoto, quindi leggi risk_level anziché il punteggio grezzo." }, "reachable_rails": { "type": "array", "items": { "type": "string", "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL" ] }, "description": "Circuiti registrati nella voce. Consulta le route per sapere cosa può utilizzare oggi la tua applicazione." }, "is_didit_customer": { "type": "boolean", "description": "true per un membro della rete Didit (per questi dd_status è sempre COMPLETED, dd_score è null e risk_level è vuoto) e per una voce della directory collegata a un cliente Didit." }, "dd_score_breakdown": { "type": "object", "description": "Un oggetto per componente di dd_score. Componenti, il loro peso (max) e i relativi codici motivo: jurisdiction, 25 (jurisdiction_not_high_risk, jurisdiction_high_risk, jurisdiction_unknown); verification, 15 (dd_status_completed, dd_status_in_progress, dd_status_not_started, dd_status_rejected); protocol, 15 (native_rail, email_only, no_rail); lei, 10 (lei_valid, lei_missing); history, 10 (history, no_history); essentials, 15 (essential_checks, no_essential_checks); responsiveness, 10 (responsive, unresponsive, responsiveness_unknown). Vuoto per un membro della rete Didit.", "additionalProperties": { "type": "object", "properties": { "points": { "type": "number", "description": "Punti con cui il componente contribuisce, arrotondati a un decimale." }, "max": { "type": "integer", "description": "Il peso del componente: i punti massimi con cui contribuisce." }, "reason": { "type": "string", "description": "Codice leggibile dalla macchina dell'esito del componente." }, "detail": { "type": "string", "description": "Spiegazione su una riga in lingua inglese." } } } }, "dd_assessed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultimo calcolo di dd_score, risk_level e responsiveness: dopo che uno scambio con la voce viene completato, termina, scade, non corrisponde o viene rifiutato, quando Didit aggiorna o gestisce la voce e durante l'aggiornamento settimanale della directory. Null per un membro della rete Didit." }, "dd_score_semantic": { "type": "string", "enum": [ "higher_is_safer" ], "description": "In quale direzione punta dd_score: sempre higher_is_safer." }, "risk_level": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "" ], "description": "La fascia in cui ricade dd_score: LOW (70 o superiore), MEDIUM (da 40 a 69) o HIGH (inferiore a 40). Vuoto per un membro della rete Didit e per una voce non ancora valutata. Puoi filtrarlo con risk. Uno screening contrassegnato da te non modifica mai questo valore condiviso: imposta invece counterparty_risk_level su HIGH nelle tue regole." }, "responsiveness": { "type": "object", "description": "Indica se il VASP risponde alle richieste Travel Rule: la quota delle richieste avviate dai clienti Didit verso di esso negli ultimi 90 giorni a cui ha risposto. Contano solo le richieste inviate tramite un canale di rete o di protocollo, oppure via email a un indirizzo condiviso (l'indirizzo di compliance della voce o un contatto della piattaforma); una richiesta inviata a un indirizzo digitato da un cliente, o al contatto privato di un cliente, non conta mai. Una richiesta scaduta è considerata senza risposta; uno scambio completato, un rifiuto o una mancata corrispondenza dei dati costituiscono una risposta; una richiesta annullata o un canale irraggiungibile non sono né l'uno né l'altro. Sempre UNKNOWN con conteggi a zero per un membro della rete Didit.", "properties": { "status": { "type": "string", "enum": [ "RESPONSIVE", "UNRESPONSIVE", "UNKNOWN" ], "description": "UNKNOWN con meno di 5 richieste decise nella finestra temporale; UNRESPONSIVE quando è stata data risposta a meno del 10 percento di esse; RESPONSIVE altrimenti." }, "answered": { "type": "integer", "description": "Richieste decise nella finestra a cui il VASP ha risposto." }, "total": { "type": "integer", "description": "Richieste decise nella finestra: con risposta più scadute." }, "computed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "essential_checks": { "type": "object", "description": "Il report dei controlli essenziali di una voce della directory, generato esclusivamente dalle fonti verificate della piattaforma: registrazione (un registro ufficiale include il VASP: il registro provvisorio MiCA dell'UE, la directory pubblica TRISA o il registro globale LEI), licenza (un'autorizzazione MiCA è registrata e in corso di validità), dominio (il dominio della voce corrisponde al relativo endpoint TRP o al sito web indicato nel registro) e lei (il record LEI è attivo, emesso e coerente con i nomi e il paese della voce). La componente essentials di dd_score rappresenta la percentuale dei controlli valutati che sono stati superati. Rimane vuoto finché l'aggiornamento settimanale della directory non controlla per la prima volta la voce, ed è sempre vuoto per i membri della rete Didit.", "properties": { "level": { "type": "string", "enum": [ "essential" ] }, "checked_at": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "registration", "licence", "domain", "lei" ] }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown" ], "description": "unknown quando nessuna fonte registrata è in grado di determinare il controllo." }, "reason": { "type": "string", "description": "Codice leggibile dalla macchina dell'esito." }, "detail": { "type": "string", "description": "Spiegazione su una riga in lingua inglese." } } } }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "unknown": { "type": "integer" }, "total": { "type": "integer" } } }, "decision": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyDecision" } ], "nullable": true, "description": "La decisione della tua applicazione su questo VASP oppure, per un'entità senza una propria decisione, quella del rispettivo brand (inherited_from indica il brand). Null se assente. Privata per la tua applicazione." }, "entity_screening": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyScreening" } ], "nullable": true, "description": "Lo screening delle sanzioni e notizie negative più recente eseguito dalla tua applicazione su questo VASP. Null se non è mai stato sottoposto a screening. Privato per la tua applicazione." }, "questionnaires": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaire" }, "description": "I questionari di due diligence della tua applicazione con questo VASP, dal più recente al meno recente. Privati per la tua applicazione." } }, "example": { "id": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "kind": "directory", "name": "Example Counterparty VASP", "lei": "529900EXAMPLECPTY001", "jurisdiction": "DE", "domains": [ "counterparty.example" ], "reachable": true, "aliases": [ { "name": "Example Counterparty", "kind": "trading_name" } ], "networks": [ { "network": "GTR", "code": "EXAMPLE01", "listed_name": "Example Counterparty VASP", "country": "DE", "verified_at": "2026-10-12T09:30:00Z", "last_seen_at": "2026-10-12T09:30:00Z", "source": "staff" } ], "routes": [ { "rail": "GTR", "status": "unavailable", "reason": "no_membership", "via": "" }, { "rail": "EMAIL", "status": "available", "reason": "", "via": "contact" } ], "umbrella": null, "entities": [], "contacts": [ { "id": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b", "email": "travelrule@counterparty.example", "name": "Travel Rule desk", "source": "staff", "scope": "platform", "verified_at": null } ], "dd_status": "NOT_STARTED", "dd_score": 62, "dd_score_breakdown": { "jurisdiction": { "points": 25.0, "max": 25, "reason": "jurisdiction_not_high_risk", "detail": "DEU is not on the high-risk jurisdiction list" }, "verification": { "points": 3.8, "max": 15, "reason": "dd_status_not_started", "detail": "due diligence status NOT_STARTED" }, "protocol": { "points": 6.0, "max": 15, "reason": "email_only", "detail": "reachable over the email fallback only" }, "lei": { "points": 10.0, "max": 10, "reason": "lei_valid", "detail": "valid LEI on record" }, "history": { "points": 5.0, "max": 10, "reason": "no_history", "detail": "no exchange history" }, "essentials": { "points": 7.5, "max": 15, "reason": "no_essential_checks", "detail": "no decided essential check yet" }, "responsiveness": { "points": 5.0, "max": 10, "reason": "responsiveness_unknown", "detail": "0 decided recent requests, too few to judge" } }, "dd_assessed_at": "2026-10-12T09:30:00Z", "dd_score_semantic": "higher_is_safer", "risk_level": "MEDIUM", "responsiveness": { "status": "UNKNOWN", "answered": 0, "total": 0, "computed_at": "2026-10-12T09:30:00Z" }, "essential_checks": {}, "reachable_rails": [ "GTR", "EMAIL" ], "is_didit_customer": false, "decision": { "decision": "APPROVED", "reason": "Licensed in DE, questionnaire reviewed", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": null }, "entity_screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "Approved", "total_hits": 0, "score": null, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": false }, "questionnaires": [ { "id": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "status": "ANSWERED", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-09-02T08:00:00Z", "expires_at": "2026-10-02T08:00:00Z", "answered_at": "2026-09-04T15:20:00Z", "valid_until": "2027-09-04T15:20:00Z", "current": true, "answers": { "legal_name": "Example Counterparty VASP, incorporated in the example jurisdiction.", "licensing": "Crypto-asset service provider authorised under MiCA by its national regulator, licence active.", "jurisdictions": "EU and EEA. We do not serve the United States.", "aml_program": "Written AML/CFT policy, annual independent review, last completed in March 2026.", "compliance_officer": "Head of Compliance, reachable at compliance@counterparty.example.", "sanctions_screening": "Customers at onboarding and daily; counterparties on every transfer.", "transaction_monitoring": "Rule-based monitoring with analyst review; suspicious activity reports filed with the FIU.", "travel_rule": "TRP and email; we answer requests within one business day.", "custody": "Segregated customer wallets held with a qualified custodian, insured.", "ownership": "No shareholder holds 25 percent or more; parent company Example Holding Group.", "record_keeping": "Five-year record-keeping for Travel Rule and transaction data, as our regulator requires.", "data_protection": "Encrypted at rest and in transit, stored in the EU." } } ] } }, "TravelRuleCounterpartyDecision": { "type": "object", "description": "La decisione della tua applicazione su un VASP di controparte. Privata per la tua applicazione: non modifica mai la voce condivisa della directory e gli altri clienti non la vedono mai. Agisce solo tramite le tue regole di transazione (il campo regola counterparty_dd_status e i preset travel-rule-counterparty-blocked e travel-rule-counterparty-restricted); non modifica mai la modalità di instradamento di un trasferimento.", "properties": { "decision": { "type": "string", "enum": [ "APPROVED", "RESTRICTED", "BLOCKED" ], "description": "APPROVED: il tuo team ha approvato la controparte. RESTRICTED: i trasferimenti verso di essa possono procedere previa revisione. BLOCKED: il tuo team l'ha rifiutata." }, "reason": { "type": "string", "maxLength": 255, "description": "Motivo in formato testo libero fornito da te, vuoto se non specificato." }, "decided_by": { "type": "string", "description": "L'utente della console che ha preso o modificato per ultimo la decisione. Vuoto se è stata presa tramite chiave API." }, "updated_at": { "type": "string", "format": "date-time" }, "inherited_from": { "type": "object", "nullable": true, "description": "Il brand di cui questa entità segue la decisione perché non ne è stata presa alcuna sull'entità stessa. Null quando la decisione appartiene alla controparte stessa.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } }, "TravelRuleCounterpartyDecisionResponse": { "type": "object", "properties": { "decision": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyDecision" } ], "nullable": true, "description": "La decisione che si applica alla controparte per la tua applicazione: la propria, altrimenti (per un'entità di un brand) quella del brand. Null quando non ce n'è alcuna." } } }, "TravelRuleCounterpartyDecisionRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "APPROVED", "RESTRICTED", "BLOCKED" ] }, "reason": { "type": "string", "maxLength": 255, "description": "Opzionale. Sostituisce il motivo precedente; omettilo per cancellarlo." } } }, "TravelRuleCounterpartyScreening": { "type": "object", "description": "Uno screening per sanzioni e notizie negative dell'entità della controparte, eseguito e fatturato per la tua applicazione. Riservato alla tua applicazione: nessun altro cliente potrà mai vederlo.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Approvata: nessuna possibile corrispondenza richiede attenzione. In revisione o Rifiutata: una possibile corrispondenza con liste di sanzioni o notizie negative." }, "total_hits": { "type": "integer", "description": "Quante corrispondenze potenziali ha restituito lo screening." }, "score": { "type": "number", "nullable": true, "description": "Il punteggio di rischio più elevato tra le possibili corrispondenze. Null quando non c'è stata alcuna corrispondenza." }, "screened_at": { "type": "string", "format": "date-time" }, "fresh": { "type": "boolean", "description": "Indica se lo screening è più recente di fresh_days (30 giorni). Uno screening recente viene riutilizzato anziché fatturato nuovamente." }, "flagged": { "type": "boolean", "description": "true mentre lo screening è recente e il suo stato è In Review o Declined. Quando l'ultimo screening è segnalato e lo screening della controparte rimane attivo, counterparty_risk_level è HIGH nelle tue regole." } } }, "TravelRuleCounterpartyScreeningStatus": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "L'impostazione Travel Rule counterparty_screening_enabled. Disattivata per impostazione predefinita; finché è disattivata non viene eseguito alcuno screening né addebitato alcun costo." }, "price": { "type": "string", "description": "Stringa decimale, in USD: il costo di un singolo screening per la tua organizzazione, ovvero il prezzo di Screening AML per aziende." }, "fresh_days": { "type": "integer", "description": "Quanti giorni uno screening rimane valido e viene riutilizzato." }, "screening": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyScreening" } ], "nullable": true, "description": "Il tuo ultimo screening della controparte. Null se non è mai stato eseguito." } } }, "TravelRuleCounterpartyScreeningRequest": { "type": "object", "properties": { "refresh": { "type": "boolean", "default": false, "description": "true esegue nuovamente lo screening (e lo fattura nuovamente) anche quando esiste uno screening recente." } } }, "TravelRuleCounterpartyScreeningResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "screened", "reused" ], "description": "screened: è stato eseguito e fatturato un nuovo screening (201). reused: è stato restituito uno screening recente e non è stato fatturato nulla (200)." }, "screening": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreening" } } }, "TravelRuleCounterpartyQuestionnaire": { "type": "object", "description": "Un questionario di due diligence inviato dalla tua applicazione alla controparte: il questionario standard di Didit, inviato via email a un indirizzo di compliance registrato con un link di risposta monouso. Riservato alla tua applicazione.", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "SENT", "ANSWERED", "EXPIRED" ], "description": "SENT: in attesa di risposte. ANSWERED: la controparte ha risposto a tutte le domande. EXPIRED: il link di risposta è stato chiuso senza risposta (il termine è scaduto oppure è stato sostituito da un questionario più recente), oppure le risposte hanno superato valid_until." }, "form_version": { "type": "string", "description": "Versione del questionario standard di Didit a cui appartengono le risposte. Attualmente 1." }, "sent_to": { "type": "string", "format": "email" }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "La scadenza per la risposta, 30 giorni dopo l'invio. Il link smette di funzionare dopo tale termine." }, "answered_at": { "type": "string", "format": "date-time", "nullable": true }, "valid_until": { "type": "string", "format": "date-time", "nullable": true, "description": "Periodo di validità delle risposte: 365 giorni dopo la risposta. Null fino a quando non viene fornita una risposta." }, "current": { "type": "boolean", "description": "true mentre il questionario è ANSWERED e valid_until non è trascorso." }, "answers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Le risposte associate all'ID della domanda: legal_name, licensing, jurisdictions, aml_program, compliance_officer, sanctions_screening, transaction_monitoring, travel_rule, custody, ownership, record_keeping, data_protection. Ciascuna risposta può contenere fino a 2.000 caratteri. Vuote finché non viene fornita una risposta." } } }, "TravelRuleCounterpartyQuestionnaireRequest": { "type": "object", "properties": { "sent_to": { "type": "string", "format": "email", "description": "Opzionale. Un indirizzo di compliance registrato per la controparte: per una voce della rubrica il suo indirizzo di compliance o un contatto visibile alla tua applicazione, per un membro della rete Didit la sua email di compliance confermata. Valore predefinito: l'indirizzo a cui viene inviata un'email di Travel Rule alla controparte (prima il tuo contatto, poi un contatto della piattaforma, infine l'indirizzo di compliance della voce)." } } }, "TravelRuleCounterpartyQuestionnaireList": { "type": "object", "properties": { "questionnaires": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaire" }, "description": "I più recenti per primi." } } }, "TravelRulePickupInfo": { "type": "object", "description": "Lo scambio in sospeso associato a un link di ritiro inviato via email, come mostrato nella pagina di risposta della controparte.", "properties": { "reference": { "type": "string", "format": "uuid", "description": "L'uuid del trasferimento, come mostrato nella console del VASP mittente." }, "requested_at": { "type": "string", "format": "date-time" }, "originator_vasp_name": { "type": "string" }, "originator_vasp_lei": { "type": "string" }, "recipient_vasp_name": { "type": "string", "description": "Il VASP di controparte a cui è indirizzata la richiesta." }, "language": { "type": "string", "description": "La lingua dell'email di richiesta e della pagina di risposta, ricavata dalla giurisdizione della controparte." }, "amount": { "type": "string" }, "currency": { "type": "string" }, "fiat_amount": { "type": "string", "description": "Il valore convertito fornito dal mittente, oppure vuoto." }, "fiat_currency": { "type": "string" }, "chain": { "type": "string" }, "beneficiary_wallet": { "type": "string" }, "status": { "type": "string" }, "ivms_version": { "type": "string" }, "deadline_at": { "type": "string", "format": "date-time", "description": "Quando il link smette di rispondere." }, "reminders_sent": { "type": "integer" }, "contact": { "type": "string", "description": "Il valore `?contact=` del link, restituito tal quale; vuoto se il link non ne contiene." }, "decline_reasons": { "type": "array", "items": { "type": "string", "enum": [ "data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other" ] }, "description": "I valori accettati da `decline_reason`." }, "join_invitation": { "type": "object", "description": "Indica se la controparte dispone di un invito attivo per iscriversi gratuitamente a Didit. Il link di invito viaggia solo nell'email inviata all'indirizzo invitato, quindi `url` è vuoto qui.", "properties": { "eligible": { "type": "boolean" }, "url": { "type": "string" } } }, "originator_data": { "type": "object", "description": "I campi dell'ordinante condivisi dal VASP mittente (`data_sharing_fields`). Il nome e il wallet sono sempre inclusi." }, "beneficiary_data": { "type": "object" }, "ivms_request": { "type": "object", "description": "La stessa richiesta sotto forma di oggetto IVMS 101. Omessa quando `data_masked` è true." }, "data_masked": { "type": "boolean", "description": "Sempre false su questo endpoint: una richiesta email è in uscita e l'utente del mittente non viene mai mascherato." } } }, "TravelRulePickupRespondRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "accept", "decline" ] }, "beneficiary_name": { "type": "string", "description": "Il nome del beneficiario registrato nei tuoi archivi, elaborato tramite la regola sui nomi del VASP ordinante. `ivms_response` ha la precedenza se indica il beneficiario.", "maxLength": 255 }, "decline_reason": { "type": "string", "enum": [ "", "data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other" ], "description": "Il motivo per cui rifiuti. Registrato nella cronologia dei trasferimenti del VASP mittente. Vuoto (valore predefinito) se non indichi alcun motivo." }, "decline_detail": { "type": "string", "maxLength": 512, "description": "Testo libero; obbligatorio quando `decision` è `decline` e `decline_reason` è `other`." }, "ivms_response": { "type": "object", "description": "La tua risposta IVMS 101 completa. Il rispettivo nome del beneficiario ha la precedenza su `beneficiary_name`." }, "contact": { "type": "string", "format": "uuid", "description": "Il contatto a cui è stato inviato il link, ricavato dal valore `?contact=` del link. Quando il body lo omette, viene utilizzato il parametro di query `contact`." } } }, "TravelRuleInboundRequest": { "type": "object", "required": [ "chain", "txid", "wallet_address", "amount", "currency" ], "properties": { "chain": { "type": "string", "description": "Chain su cui è stato regolato il deposito, ad esempio `ETH`. Memorizzata in minuscolo e confrontata senza distinzione tra maiuscole e minuscole con le voci della tua rubrica dei wallet, quindi usa lo stesso token di chain anche lì.", "maxLength": 32 }, "txid": { "type": "string", "description": "Hash della transazione on-chain. Deduplicato insieme a wallet_address.", "maxLength": 128 }, "wallet_address": { "type": "string", "description": "Il wallet di destinazione su cui hai ricevuto il deposito. Un X-address XRP viene suddiviso nel relativo indirizzo classico e tag.", "maxLength": 128 }, "amount": { "type": "string", "description": "Importo del deposito come stringa decimale, pari a zero o superiore, con un massimo di 18 cifre decimali." }, "currency": { "type": "string", "description": "Asset di deposito, ad es. \"USDC\".", "maxLength": 16 }, "originator_data": { "type": "object", "description": "Dettagli dell'ordinante forniti dal VASP mittente, se noti, sotto forma di oggetto piatto come `{\"name\": \"...\"}`. Didit legge da esso name (o full_name), first_name, last_name e vendor_data.", "additionalProperties": true }, "beneficiary_data": { "type": "object", "description": "Dettagli del beneficiario (il tuo cliente), come oggetto piatto ad esempio `{\"name\": \"...\"}`. Didit confronta name con holder_name della voce corrispondente nella rubrica e imposta wallet_address e chain a partire dalla richiesta.", "additionalProperties": true }, "originating_vasp": { "type": "object", "description": "Descrizione opzionale del VASP mittente. Rimane solo su questo trasferimento (`metadata.originating_vasp`, e il VASP ordinante del trasferimento in GET /v3/travel-rule/transfers/); non crea, modifica o collega mai una voce condivisa della directory VASP.", "properties": { "name": { "type": "string", "maxLength": 255 }, "lei": { "type": "string", "maxLength": 20, "description": "Opzionale. Un LEI ISO 17442 valido di 20 caratteri, oppure vuoto." }, "travel_address": { "type": "string", "description": "Il Travel Address del mittente, registrato su questo trasferimento.", "maxLength": 512 } } }, "memo": { "type": "string", "maxLength": 256, "description": "Opzionale. Il destination tag o memo del deposito su una rete con memo: su un indirizzo di deposito condiviso è ciò che distingue i tuoi clienti, e viene associata la voce della rubrica corrispondente a quel memo. XRP: un destination tag, un numero intero da 0 a 4294967295 (è accettato un numero JSON). XLM: un memo testuale fino a 28 byte, un ID a 64 bit o un hash a 32 byte in formato esadecimale. EOS: fino a 256 byte. ATOM: fino a 256 caratteri. HBAR: fino a 100 byte. I wallet Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning non accettano memo: inserirne uno restituisce un `400`. Alias: `destinationTag` o `destination_tag`." }, "utxo": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleUtxo" } ], "description": "Opzionale, solo per blockchain UTXO. Gli input e gli output della transazione di deposito: il wallet del mittente è il `originator_data.wallet_address` dichiarato, altrimenti l'input maggiore." } } }, "TravelRuleInboundResponse": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "UUID della transazione Didit per il deposito in entrata." }, "txn_id": { "type": "string", "description": "txn_id della transazione in entrata: generato da Didit quando Didit ha creato la transazione, oppure il tuo quando è stato riutilizzato un deposito non reclamato." }, "created": { "type": "boolean", "description": "true quando questa chiamata ha registrato il trasferimento (HTTP 201); false quando esisteva già un trasferimento per gli stessi txid e wallet_address (HTTP 200)." }, "travel_rule": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } }, "TravelRuleTestVaspInboundRequest": { "type": "object", "required": [ "beneficiary_wallet_address" ], "properties": { "beneficiary_wallet_address": { "type": "string", "description": "L'indirizzo del wallet di destinazione. Il Test VASP di Didit invia verso questo indirizzo, confrontandolo con la rubrica dei wallet dell'asset sulla relativa blockchain. Un wallet senza una voce corrispondente viene accettato e la transazione in entrata viene registrata con stato ON_HOLD." }, "scenario": { "type": "string", "enum": [ "accept", "name_mismatch" ], "default": "accept", "description": "Cosa dichiara il Didit Test VASP in merito al beneficiario. `accept` dichiara il nome effettivo del titolare; `name_mismatch` dichiara un nome con cui nessun titolare concorda. La decisione finale spetta sempre a te." }, "chain": { "type": "string", "default": "ETH", "description": "Chain dell'asset." }, "amount": { "type": "string", "default": "1", "description": "Importo come stringa decimale." }, "currency": { "type": "string", "default": "ETH", "description": "Codice dell'asset." }, "reference": { "type": "string", "description": "Chiave di idempotenza opzionale. Una ripetizione con lo stesso valore restituisce il trasferimento prenotato dalla prima chiamata." } } }, "TravelRuleTestVaspInboundResponse": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "UUID della transazione Didit per il trasferimento in entrata." }, "txn_id": { "type": "string", "description": "txn_id generato da Didit." }, "scenario": { "type": "string", "description": "Lo scenario eseguito." }, "travel_rule_status": { "type": "string", "description": "Lo stato stabilito dalla decisione della tua applicazione." }, "detail": { "type": "string", "description": "Il motivo per cui il trasferimento si è risolto in tale stato." }, "test_vasp": { "type": "boolean", "description": "Sempre true: il mittente era il Didit Test VASP." }, "travel_rule": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } }, "TravelRuleWidgetSessionCreate": { "type": "object", "properties": { "wallet_address": { "type": "string", "description": "L'indirizzo del wallet da verificare. Facoltativo; se vuoto, l'indirizzo deve essere fornito all'avvio di una prova.", "maxLength": 128 }, "chain": { "type": "string", "description": "Token della blockchain per l'indirizzo, ad esempio `ETH`, `BTC` o `SOL`. Usa lo stesso token presente nella rubrica del tuo wallet. La firma del messaggio e il Satoshi test sono offerti solo per una blockchain supportata. La voce della rubrica verificata dalla prova memorizza il token sotto il suo identificatore canonico (ETH, BTC, SOL, TRX).", "maxLength": 32 }, "holder_name": { "type": "string", "description": "Nome del titolare del wallet, utilizzato per la corrispondenza del nome del beneficiario.", "maxLength": 255 }, "vendor_data": { "type": "string", "description": "Il tuo identificatore interno per il titolare, trasferito nella voce della rubrica creata.", "maxLength": 255 }, "transaction_id": { "type": "string", "format": "uuid", "description": "Opzionale. UUID della transazione Didit di un trasferimento Travel Rule da far avanzare quando la prova viene verificata.", "nullable": true }, "satoshi_deposit_address": { "type": "string", "description": "Opzionale. Un indirizzo di deposito sotto il tuo controllo; fornirlo abilita il metodo di prova SATOSHI_TEST.", "maxLength": 128 }, "callback_url": { "type": "string", "description": "Opzionale. URL assoluto http(s) a cui il widget reindirizza il cliente al completamento.", "maxLength": 512 }, "expires_in_minutes": { "type": "integer", "description": "Opzionale. Durata del link generato, in minuti. Estesa automaticamente per coprire l'intervallo temporale del test di Satoshi quando viene offerto SATOSHI_TEST.", "default": 60, "minimum": 5, "maximum": 10080 } } }, "TravelRuleWidgetSessionResponse": { "type": "object", "properties": { "widget_session_id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "Token di sessione opaco incorporato nell'URL del widget." }, "url": { "type": "string", "description": "L'URL del widget ospitato per la titolarità del wallet. Aprilo esattamente com'è nel browser di sistema (mai all'interno di una webview dell'SDK mobile)." }, "expires_at": { "type": "string", "format": "date-time" } } }, "TravelRuleWidgetContext": { "type": "object", "properties": { "vasp_name": { "type": "string", "description": "Ragione sociale ricavata dal profilo VASP, mostrata al cliente nel widget. Vuota quando non è presente alcun profilo." }, "wallet_address": { "type": "string" }, "chain": { "type": "string", "description": "La chain con cui è stata generata la sessione, così come l'hai inviata." }, "chain_family": { "type": "string", "nullable": true, "enum": [ "EVM", "BTC", "SOL", "TRON", null ], "description": "La famiglia di chiavi alla base della chain: EVM (Ethereum, BNB Chain, Polygon, Arbitrum, Base, Optimism, Avalanche, Linea e le altre chain EVM), BTC, SOL o TRON. Una singola chiave EVM controlla lo stesso indirizzo su ogni chain EVM. Null quando non è possibile verificare alcuna firma sulla chain." }, "holder_name": { "type": "string" }, "allowed_methods": { "type": "array", "items": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SCREENSHOT", "SATOSHI_TEST", "SELF_DECLARATION" ] }, "description": "Metodi di prova disponibili per questa sessione. MESSAGE_SIGNING richiede una chain con una chain_family, SATOSHI_TEST richiede un satoshi_deposit_address sulla sessione e una chain i cui depositi possono essere letti da Didit, SCREENSHOT richiede l'impostazione allow_screenshot_proof e SELF_DECLARATION richiede l'impostazione allow_self_declaration." }, "transfer_status": { "type": "string", "nullable": true, "description": "Stato del trasferimento Travel Rule collegato. Null quando la sessione è stata creata senza un transaction_id." }, "callback_url": { "type": "string", "description": "Indica dove il widget reindirizza il cliente dopo il completamento. Vuoto se non impostato." }, "expires_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Non nullo una volta che la prova è stata verificata." }, "proofs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleWidgetProofSummary" } }, "max_attempts": { "type": "integer", "description": "Prove di possesso del wallet rifiutate consentite da questa sessione." }, "attempts_used": { "type": "integer", "description": "Prove rifiutate finora." }, "attempts_remaining": { "type": "integer", "description": "Quando è 0, l'avvio di un'altra prova risponde con 409 e generi una nuova sessione di widget." }, "customization": { "type": "object", "nullable": true, "description": "La personalizzazione White label dell'applicazione (colori, logo, famiglia di caratteri) quando il White label è abilitato: il widget viene visualizzato con la stessa identità visiva del flusso di verifica. Null in caso contrario." } } }, "TravelRuleWidgetProofSummary": { "type": "object", "properties": { "proof_id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ], "description": "PENDING: l'utente finale ha scelto questo metodo e la prova non è ancora decisa. Una firma non riuscita o un deposito di prova non ancora leggibile o confermato mantiene la prova in stato PENDING con un failure_reason, consentendo all'utente finale di riprovare; un deposito SATOSHI_TEST inviato viene ricontrollato automaticamente fino alla chiusura della relativa finestra temporale, mentre uno SCREENSHOT inviato rimane in attesa della tua revisione. VERIFIED: l'assetto proprietario è dimostrato. REJECTED: il deposito di prova è effettivamente errato (un altro mittente, importo non corrispondente a quello previsto verso l'indirizzo di deposito, anteriore alla richiesta di verifica o transazione che ha già provato un altro wallet) oppure il tuo revisore ha rifiutato lo screenshot; failure_reason specifica quale. Una prova rifiutata è definitiva e consuma uno dei tentativi della sessione. EXPIRED: la prova non può più essere decisa (la finestra temporale si è chiusa, l'utente finale ha cambiato metodo, la sessione del widget è scaduta o il titolare del wallet è cambiato); failure_reason specifica quale." }, "wallet_address": { "type": "string" }, "chain": { "type": "string", "description": "Identificatore canonico della rete blockchain della voce della rubrica a cui si riferisce la prova, ad es. ETH, BTC, SOL, TRX." }, "deposit_address": { "type": "string", "nullable": true, "description": "Indirizzo di deposito a cui il cliente deve inviare l'importo del test Satoshi. Presente solo su una prova SATOSHI_TEST." }, "expected_amount": { "type": "string", "nullable": true, "description": "Importo on-chain esatto, nella valuta nativa del deposito, a cui il deposito di test Satoshi deve corrispondere. Presente solo su una prova SATOSHI_TEST." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Scadenza per la finestra del Satoshi test di questa prova. Presente solo su una prova SATOSHI_TEST; il valore expires_at della sessione del widget viene esteso per coprirla quando viene offerto SATOSHI_TEST." }, "challenge": { "type": "string", "nullable": true, "description": "Messaggio emesso da Didit che il cliente firma con il proprio wallet. Presente solo in una prova MESSAGE_SIGNING." }, "rejection_reason": { "type": "string", "description": "Il motivo per cui la prova è stata rifiutata, come frase in inglese per l'utente finale. Presente solo quando `status` è REJECTED; vuoto quando il tuo revisore ha rifiutato uno screenshot (la tua nota rimane visibile solo a te)." }, "created_at": { "type": "string", "format": "date-time" }, "attempts": { "type": "integer", "description": "Quante volte sono state inviate prove per questa prova (firme, ID di transazione, caricamenti)." }, "failure_reason": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "Perché l'ultimo tentativo non è andato a buon fine, o perché la prova si è conclusa. Vuoto se non si è verificato alcun errore." } } }, "CaseSubject": { "type": "object", "nullable": true, "description": "L'unico utente o azienda a cui è associato il caso.", "properties": { "type": { "type": "string", "enum": [ "user", "business" ] }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "external_id": { "type": "string", "nullable": true, "description": "Il vendor_data del soggetto." }, "country": { "type": "string", "nullable": true, "description": "Codice paese a tre lettere del soggetto (ISO 3166-1 alpha-3), oppure null se non noto. Per un'azienda, il paese di costituzione. Per una persona, il paese di emissione di un documento d'identità proveniente dalle sue verifiche; per una persona con documenti provenienti da diversi paesi ne viene mostrato uno e possono comparire codici documento ICAO come `XXA`.", "example": "ESP" }, "portrait": { "type": "string", "format": "uri", "nullable": true, "description": "URL firmato di breve durata dell'immagine del ritratto della persona. Sempre null per un'azienda e null per una persona senza ritratto. L'URL scade, quindi scarica l'immagine quando leggi il caso invece di memorizzare l'URL." } } }, "CaseAssignee": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "CaseBlueprintSummary": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 24 } } }, "CaseContentConfig": { "type": "object", "description": "Le sei sezioni attivabili/disattivabili che determinano quali schede e campi compaiono nella pagina del caso. Le sezioni o chiavi sconosciute vengono rifiutate.", "properties": { "checklist": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "optional": { "type": "boolean", "description": "Se true, un caso può essere risolto anche con elementi della checklist incompleti." }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "order": { "type": "integer" } } } } } }, "aml_control": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "financial": { "type": "boolean" }, "identity": { "type": "boolean" } } }, "identity": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "personal_information": { "type": "boolean" }, "applicant_tags": { "type": "boolean" }, "contact_information": { "type": "boolean" }, "risk_overview": { "type": "boolean" }, "poi_documents": { "type": "boolean" }, "poa_documents": { "type": "boolean" } } }, "verifications": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "summary": { "type": "boolean" } } }, "reporting": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "fiu_reports": { "type": "boolean" } } }, "financial": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "payment_methods": { "type": "boolean" }, "transactions": { "type": "boolean" } } } } }, "CaseNote": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "comment": { "type": "string" }, "actor_email": { "type": "string", "format": "email", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "is_internal": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "s3_key": { "type": "string" }, "filename": { "type": "string" }, "file_size": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "CaseEvent": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "enum": [ "CREATED", "STATUS_CHANGED", "ASSIGNED", "UNASSIGNED", "RESOLVED", "REOPENED", "LINK_ADDED", "LINK_REMOVED", "NOTE_ADDED", "NOTE_PINNED", "NOTE_UNPINNED", "PRIORITY_CHANGED", "DUE_DATE_CHANGED", "TAG_ADDED", "TAG_REMOVED", "ESCALATED", "TRANSFERRED", "CHECKLIST_COMPLETED", "REPORT_CREATED", "REPORT_FINALIZED", "SUBMITTED_FOR_APPROVAL", "APPROVAL_GRANTED", "APPROVAL_REJECTED", "ENTITY_ACTION", "APPROVAL_INVALIDATED", "CUSTOMER_REQUEST", "STAGE_CHANGED", "TEAM_CHANGED", "CHECKER_ASSIGNED", "CHECKER_UNASSIGNED" ] }, "actor_email": { "type": "string", "format": "email", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "previous_status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ], "nullable": true }, "new_status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ], "nullable": true }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } }, "CaseLink": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "linked_entity_type": { "type": "string", "enum": [ "session", "business_session", "transaction" ], "nullable": true }, "linked_entity_uuid": { "type": "string", "format": "uuid", "nullable": true }, "linked_entity_summary": { "type": "object", "nullable": true, "description": "session_id/session_number/status per i link session e business_session; uuid/txn_id/status per i link transaction." }, "created_at": { "type": "string", "format": "date-time" } } }, "CaseChecklistItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string", "maxLength": 255 }, "is_completed": { "type": "boolean" }, "completed_by": { "type": "string", "format": "email", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "order": { "type": "integer" } } }, "CaseBlueprintListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "nullable": true }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "max_active_cases": { "type": "integer", "nullable": true }, "escalation_enabled": { "type": "boolean" }, "transfer_enabled": { "type": "boolean" }, "require_resolution_note": { "type": "boolean" }, "is_active": { "type": "boolean" }, "preset_key": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "readOnly": true }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760 } } }, "CaseBlueprintDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "nullable": true }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "max_active_cases": { "type": "integer", "nullable": true }, "escalation_enabled": { "type": "boolean" }, "transfer_enabled": { "type": "boolean" }, "require_resolution_note": { "type": "boolean" }, "is_active": { "type": "boolean" }, "preset_key": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "escalation_blueprint_name": { "type": "string", "nullable": true }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "four_eyes_checker_blueprint_name": { "type": "string", "nullable": true }, "content_config": { "type": "object", "description": "Le sei sezioni attivabili/disattivabili che determinano quali schede e campi compaiono nella pagina del caso. Le sezioni o chiavi sconosciute vengono rifiutate.", "properties": { "checklist": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "optional": { "type": "boolean", "description": "Se true, un caso può essere risolto anche con elementi della checklist incompleti." }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "order": { "type": "integer" } } } } } }, "aml_control": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "financial": { "type": "boolean" }, "identity": { "type": "boolean" } } }, "identity": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "personal_information": { "type": "boolean" }, "applicant_tags": { "type": "boolean" }, "contact_information": { "type": "boolean" }, "risk_overview": { "type": "boolean" }, "poi_documents": { "type": "boolean" }, "poa_documents": { "type": "boolean" } } }, "verifications": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "summary": { "type": "boolean" } } }, "reporting": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "fiu_reports": { "type": "boolean" } } }, "financial": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "payment_methods": { "type": "boolean" }, "transactions": { "type": "boolean" } } } } }, "creation_sources": { "type": "array", "description": "Connettori che attualmente instradano nuovi casi in questo modello.", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "aml", "rule", "workflow" ] }, "id": { "type": "string" }, "name": { "type": "string" } } } }, "receives_escalation_from": { "type": "array", "description": "Altri blueprint il cui target di escalation punta a questo.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "readOnly": true }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760 } } }, "CaseListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true, "description": "Assegnato automaticamente, es. CS-0001." }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ], "nullable": true }, "pending_resolution": { "type": "object", "nullable": true, "description": "Impostato solo mentre una risoluzione a 4 occhi è predisposta sul blueprint checker, in attesa di approvazione o rifiuto dell'approvazione.", "properties": { "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ] }, "resolution_notes": { "type": "string", "nullable": true }, "maker_email": { "type": "string", "format": "email", "nullable": true, "description": "Email del responsabile che ha inviato la risoluzione. Null se inviata tramite chiave API: tale risoluzione non ha un autore registrato, pertanto approve e reject-approval restituiscono 403 per ogni chiamante." }, "maker_name": { "type": "string", "nullable": true }, "maker_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID utente membro del responsabile che ha inviato la risoluzione. Null quando è stata inviata tramite una chiave API. Tale membro non può essere designato come `checker`." }, "maker_blueprint_id": { "type": "string", "format": "uuid" }, "staged_at": { "type": "string", "format": "date-time" } } }, "checker": { "$ref": "#/components/schemas/CaseChecker" }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "source": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "$ref": "#/components/schemas/CaseSubject" }, "assigned_to": { "$ref": "#/components/schemas/CaseAssignee" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true }, "team": { "$ref": "#/components/schemas/CaseTeamSummary" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by_email": { "type": "string", "nullable": true }, "created_by_name": { "type": "string", "nullable": true }, "blueprint": { "$ref": "#/components/schemas/CaseBlueprintSummary" }, "links_count": { "type": "integer" }, "notes_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "application_id": { "type": "string", "format": "uuid" }, "application_name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" } } }, "CaseDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ], "nullable": true }, "resolution_notes": { "type": "string", "nullable": true }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "source": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "$ref": "#/components/schemas/CaseSubject" }, "assigned_to": { "$ref": "#/components/schemas/CaseAssignee" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true }, "team": { "$ref": "#/components/schemas/CaseTeamSummary" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_by_email": { "type": "string", "nullable": true }, "pending_resolution": { "type": "object", "nullable": true, "description": "Impostato solo mentre una risoluzione a 4 occhi è predisposta sul blueprint checker, in attesa di approvazione o rifiuto dell'approvazione.", "properties": { "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ] }, "resolution_notes": { "type": "string", "nullable": true }, "maker_email": { "type": "string", "format": "email", "nullable": true, "description": "Email del responsabile che ha inviato la risoluzione. Null se inviata tramite chiave API: tale risoluzione non ha un autore registrato, pertanto approve e reject-approval restituiscono 403 per ogni chiamante." }, "maker_name": { "type": "string", "nullable": true }, "maker_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID utente membro del responsabile che ha inviato la risoluzione. Null quando è stata inviata tramite una chiave API. Tale membro non può essere designato come `checker`." }, "maker_blueprint_id": { "type": "string", "format": "uuid" }, "staged_at": { "type": "string", "format": "date-time" } } }, "checker": { "$ref": "#/components/schemas/CaseChecker" }, "metadata": { "type": "object" }, "blueprint": { "$ref": "#/components/schemas/CaseBlueprintDetail" }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/CaseNote" }, "description": "Le 50 note più recenti." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CaseEvent" }, "description": "I 100 eventi più recenti." }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/CaseLink" } }, "links_count": { "type": "integer" }, "notes_count": { "type": "integer" }, "checklist_items": { "type": "array", "items": { "$ref": "#/components/schemas/CaseChecklistItem" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ReportTemplateDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Codice paese ISO 3166-1 alpha-2." }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "report_type_display": { "type": "string" }, "field_config": { "type": "object", "description": "Impostazioni predefinite riutilizzabili per l'intestazione goAML. Campi obbligatori a livello di modello: rentity_id, submission_code e currency_code_local (3 lettere). Facoltativi: enabled_fields (quali blocchi di report opzionali includere) oltre ai valori predefiniti per reporting_person, location, reason e action. I campi di intestazione specifici per ogni invio (action, submission_date, transactions, jurisdiction) vengono verificati al momento della validazione o della finalizzazione del report, non sul modello." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RegulatoryReportDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "case_uuid": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "report_type_display": { "type": "string" }, "report_code": { "type": "string", "description": "Codice report goAML derivato da report_type, ad es. STR, CTR, BCR." }, "report_number": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "DRAFT", "VALIDATED", "FINALIZED" ] }, "status_display": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2 }, "rentity_id": { "type": "string", "nullable": true, "description": "ID dell'entità segnalante rilasciato dalla FIU." }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ] }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "description": "Sezioni narrative delle cinque W.", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } }, "transactions": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "validation_errors": { "type": "array", "description": "Risultato della validazione più recente; ogni voce è un oggetto {field, message}.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } }, "validated_at": { "type": "string", "format": "date-time", "nullable": true }, "finalized_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by_email": { "type": "string", "nullable": true }, "created_by_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TransactionRuleCondition": { "type": "object", "required": [ "field", "operator" ], "properties": { "field": { "type": "string", "description": "Percorso del campo della transazione da valutare. Campi principali: amount, currency, direction, action_type, score, severity, transaction_type, payment_details, preferred_currency_amount (utilizza amount_in_default_currency come fallback), default_currency_code, subject_country, counterparty_country, subject_vendor_data, counterparty_vendor_data, subject_device_fingerprint, counterparty_device_fingerprint, subject_browser_family, subject_browser_version, subject_platform, subject_accept_language, subject_session_age_ms, subject_ip_country, counterparty_ip_country, subject_ip_address, counterparty_ip_address, subject_payment_method_type, subject_payment_method_country, subject_payment_method_fingerprint, subject_payment_method_account_id (e i corrispettivi counterparty_payment_method_*), travel_rule_status, travel_rule_required, travel_rule_obligations_count, counterparty_dd_status (la tua decisione sulla controparte Travel Rule: APPROVED, RESTRICTED o BLOCKED, un'entità conforme al suo marchio), counterparty_risk_level (LOW, MEDIUM o HIGH; HIGH mentre il tuo screening della controparte è contrassegnato con un flag), counterparty_jurisdiction (il paese del VASP di controparte), counterparty_responsiveness (RESPONSIVE, UNRESPONSIVE o UNKNOWN), subject_days_since_previous_transaction, tags e custom_values. per qualsiasi chiave inviata in custom_properties durante la creazione della transazione. I campi con codice paese accettano ISO-2 o ISO-3; entrambi i lati vengono normalizzati a ISO-3 prima del confronto." }, "operator": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte", "in", "not_in", "contains", "not_contains", "contains_any", "regex", "fuzzy_match", "exists", "is_not_empty", "is_not_null", "not_exists", "is_empty", "is_null" ], "description": "Operatore di confronto. in/not_in verificano l'appartenenza (il valore può essere un elenco o un singolo scalare). contains/not_contains sono controlli di sottostringa senza distinzione tra maiuscole e minuscole rispetto a un valore stringa. contains_any accetta un elenco di stringhe e trova una corrispondenza se una qualsiasi è una sottostringa senza distinzione tra maiuscole e minuscole del valore del campo. regex confronta il pattern del valore con il campo. fuzzy_match effettua il confronto con la stringa del valore con la soglia di punteggio (`score`) richiesta (0-100). gt/gte/lt/lte non trovano mai corrispondenze se uno dei due lati è mancante. exists/is_not_empty/is_not_null (alias) e not_exists/is_empty/is_null (alias) sono controlli di presenza che ignorano `value`." }, "value": { "description": "Valore di confronto. La sua struttura dipende dall'operatore e da value_type; omettilo per gli operatori di controllo di presenza. Tutti gli altri operatori richiedono un valore che non sia `null` o un elenco vuoto, altrimenti la regola viene rifiutata con `400`. `contains_any` richiede un elenco di stringhe, mentre `contains`, `not_contains` e `regex` richiedono una singola stringa." }, "value_type": { "type": "string", "enum": [ "list", "field", "relative_date" ], "description": "Interpretazione opzionale del valore. `list`: il valore è l'UUID di un elenco e le voci dell'elenco diventano il valore di confronto. `field`: il valore è il percorso di un altro campo, confrontato campo per campo. `relative_date`: il valore è un oggetto data relativa, ad es. {\"direction\": \"past\", \"unit\": \"days\", \"amount\": 30}." }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Obbligatorio quando operator è fuzzy_match: la soglia di similarità da 0 a 100." }, "group_index": { "type": "integer", "description": "Logica raggruppata opzionale. Quando una qualsiasi condizione include group_index, le condizioni che condividono un indice formano un gruppo e la valutazione raggruppata sostituisce evaluation_mode." }, "group_logic": { "type": "string", "enum": [ "AND", "OR" ], "default": "AND", "description": "Come si combinano le condizioni ALL'INTERNO di un gruppo." }, "groups_logic": { "type": "string", "enum": [ "AND", "OR" ], "default": "OR", "description": "Come si combinano i risultati TRA i gruppi. Letto dalla prima condizione." } }, "description": "Una condizione legge solo la transazione valutata: non filtra mai la finestra di aggregazione." }, "TransactionRuleAggregation": { "type": "object", "required": [ "value" ], "properties": { "metric": { "type": "string", "enum": [ "count", "sum", "max", "min", "avg", "distinct_count" ], "default": "count", "description": "In che modo vengono aggregate le transazioni storiche corrispondenti. unique_count è accettato come alias di distinct_count." }, "field": { "type": "string", "default": "amount", "description": "Campo aggregato tramite sum/max/min/avg/distinct_count. Ignorato per count." }, "operator": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ], "default": "eq", "description": "Confronto applicato alla metrica calcolata." }, "value": { "type": "number", "description": "Soglia con cui viene confrontata la metrica calcolata." }, "window": { "type": "string", "pattern": "^\\d+(m|h|d)$", "default": "1d", "description": "Finestra retrospettiva che termina alla data txn_date della transazione: m (MINUTI, non mesi), h (ore) o d (giorni), ad es. 30m, 24h, 7d, 30d." }, "filters": { "type": "object", "additionalProperties": true, "description": "Limita quali transazioni storiche vengono aggregate. Le chiavi sono percorsi di campo dal catalogo dei campi di condizione; un valore pari a \"__current__\" fa riferimento al valore dello stesso campo sulla transazione in fase di valutazione (ad es. {\"subject_vendor_data\": \"__current__\"} delimita l'intervallo allo stesso soggetto), e un valore di tipo elenco indica l'appartenenza. I record senza il valore raggruppato non vengono mai raggruppati insieme: quando la transazione in fase di valutazione non ha alcun valore per un campo \"__current__\" (nessuna controparte, nessuna impronta digitale del dispositivo), l'aggregazione non corrisponde, indipendentemente dal suo operatore. I filtri confrontano SOLO per uguaglianza o appartenenza: non esiste un filtro lt/gte, quindi un intervallo come \"transazioni storiche inferiori a 10.000\" non può essere espresso qui. Imposta invece l'intervallo sulla metrica (la metrica max con operatore lt mantiene ogni transazione nell'intervallo al di sotto della soglia)." } }, "description": "Controllo di velocità sulle transazioni storiche dell'applicazione all'interno della finestra temporale. Ogni voce di aggregazione deve corrispondere affinché la regola corrisponda, indipendentemente da evaluation_mode. Un'aggregazione vincola solo la finestra; la transazione in fase di valutazione è vincolata dall'ambito e dalle condizioni, quindi ripeti direction, currency o transaction_type su entrambe le metà quando la regola li prevede." }, "TransactionRuleScope": { "type": "object", "properties": { "transaction_types": { "type": "array", "items": { "type": "string" }, "description": "Limita ai tipi di transazione, ad es. finance, kyc, travel_rule, user_event. Vuoto o mancante = nessuna limitazione." }, "directions": { "type": "array", "items": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "description": "Limita alle direzioni della transazione (senza distinzione tra maiuscole e minuscole in scrittura)." }, "action_types": { "type": "array", "items": { "type": "string" }, "description": "Limita ai tuoi valori di action_type, ad es. withdrawal, deposit." } }, "description": "A quali transazioni si applica la regola. Sono accettate solo queste tre chiavi." }, "TransactionRuleAction": { "oneOf": [ { "$ref": "#/components/schemas/TransactionRuleActionAddScore" }, { "$ref": "#/components/schemas/TransactionRuleActionChangeStatus" }, { "$ref": "#/components/schemas/TransactionRuleActionAddTags" }, { "$ref": "#/components/schemas/TransactionRuleActionAddNote" }, { "$ref": "#/components/schemas/TransactionRuleActionAddToList" }, { "$ref": "#/components/schemas/TransactionRuleActionOpenCase" } ], "discriminator": { "propertyName": "type", "mapping": { "add_score": "#/components/schemas/TransactionRuleActionAddScore", "change_status": "#/components/schemas/TransactionRuleActionChangeStatus", "add_tags": "#/components/schemas/TransactionRuleActionAddTags", "add_note": "#/components/schemas/TransactionRuleActionAddNote", "add_to_list": "#/components/schemas/TransactionRuleActionAddToList", "open_case": "#/components/schemas/TransactionRuleActionOpenCase" } }, "description": "Un'azione della regola. Una regola può averne diverse; vengono tutte applicate insieme in caso di corrispondenza. Le regole in modalità TEST registrano ciò che avrebbero fatto senza applicare alcuna azione." }, "TransactionRuleCreateRequest": { "type": "object", "required": [ "title", "category", "mode" ], "properties": { "title": { "type": "string", "description": "Nome della regola. Univoco per applicazione tra le regole non eliminate; i duplicati restituiscono 400." }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "Tema di rischio utilizzato per il raggruppamento e la reportistica, ad es. finance, aml_ctf, anomaly_detection, fatf, device_intelligence, crypto_monitoring, travel_rule, responsible_gaming, e_commerce." }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ], "description": "ACTIVE valuta in produzione. TEST valuta e registra le esecuzioni delle regole senza mai modificare punteggio o stato: è la modalità iniziale consigliata. DISABLED viene ignorato." }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL", "description": "Indica se ogni condizione deve corrispondere (ALL) o almeno una (ANY). Viene ignorato quando le condizioni utilizzano group_index." }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object", "description": "Metadati a struttura libera memorizzati sulla regola." } }, "description": "Crea una regola CUSTOM. Le regole in modalità ACTIVE diventano immediatamente effettive per le nuove transazioni: creale in modalità TEST ed esegui prima il backtest." }, "TransactionRuleUpdateRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "Nome della regola. Univoco per applicazione tra le regole non eliminate; i duplicati restituiscono 400." }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "Tema di rischio utilizzato per il raggruppamento e la reportistica, ad es. finance, aml_ctf, anomaly_detection, fatf, device_intelligence, crypto_monitoring, travel_rule, responsible_gaming, e_commerce." }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ], "description": "ACTIVE valuta in produzione. TEST valuta e registra le esecuzioni delle regole senza mai modificare punteggio o stato: è la modalità iniziale consigliata. DISABLED viene ignorato." }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL", "description": "Indica se ogni condizione deve corrispondere (ALL) o almeno una (ANY). Viene ignorato quando le condizioni utilizzano group_index." }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object", "description": "Metadati a struttura libera memorizzati sulla regola." } }, "description": "Aggiornamento parziale. Le regole personalizzate accettano ogni campo; le regole della libreria (PRESET) accettano solo mode: qualsiasi altra cosa restituisce 400." }, "TransactionRuleDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "description": "Nome della regola. Univoco per applicazione tra le regole non eliminate; i duplicati restituiscono 400." }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "Tema di rischio utilizzato per il raggruppamento e la reportistica, ad es. finance, aml_ctf, anomaly_detection, fatf, device_intelligence, crypto_monitoring, travel_rule, responsible_gaming, e_commerce." }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ], "description": "ACTIVE valuta in produzione. TEST valuta e registra le esecuzioni delle regole senza mai modificare punteggio o stato: è la modalità iniziale consigliata. DISABLED viene ignorato." }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL", "description": "Indica se ogni condizione deve corrispondere (ALL) o almeno una (ANY). Viene ignorato quando le condizioni utilizzano group_index." }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object", "description": "Metadati a struttura libera memorizzati sulla regola." }, "severity": { "type": "string", "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "nullable": true, "description": "Gravità informativa applicata dalle regole di libreria; non impostabile per le regole personalizzate." }, "source": { "type": "string", "enum": [ "PRESET", "CUSTOM" ], "description": "Le regole PRESET provengono dalla libreria (installazione/disinstallazione, modifiche solo alla modalità); le regole CUSTOM sono interamente tue." }, "library_key": { "type": "string", "nullable": true, "description": "Identificatore stabile di libreria; null per le regole personalizzate." }, "latest_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "run_count": { "type": "integer", "description": "Quante transazioni corrispondono a questa regola." }, "approved_count": { "type": "integer" }, "reviewed_count": { "type": "integer" }, "declined_count": { "type": "integer" }, "awaiting_user_count": { "type": "integer" }, "approved_pct": { "type": "number" }, "reviewed_pct": { "type": "number" }, "declined_pct": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TransactionRuleBacktestRequest": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" }, "default": [] }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" }, "default": [] }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL" }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "period_days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } }, "description": "Configurazione ipotetica della regola da valutare rispetto alle transazioni recenti. Di sola lettura e gratuita: non viene creato né modificato nulla. Invia le stesse condizioni, aggregazione, evaluation_mode E ambito (scope) della regola che intendi attivare. Condizioni, aggregazione e ambito omessi non aggiungono vincoli propri; tralasciare l'ambito può includere direzioni o tipi di transazione che la regola salvata salta. L'evaluation_mode omesso assume per impostazione predefinita il valore ALL (il che può ridurre le corrispondenze per una regola ANY), e period_days omesso assume per impostazione predefinita il valore di 90 giorni, non una cronologia illimitata." }, "TransactionRuleBacktestResult": { "type": "object", "properties": { "evaluated": { "type": "integer", "description": "Transazioni valutate (dalla più recente, con limite)." }, "matched": { "type": "integer", "description": "Transazioni per le quali la configurazione avrebbe trovato corrispondenza." }, "affected_entities": { "type": "integer", "description": "Soggetti distinti (in base a vendor_data) tra le corrispondenze." }, "period_days": { "type": "integer" } } }, "TransactionRuleLibraryEntry": { "type": "object", "properties": { "library_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string" }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ] }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object" }, "bundle": { "type": "string", "nullable": true, "description": "Famiglia funzionale, ad es. finance, aml_ctf, crypto_monitoring, travel_rule, responsible_gaming." }, "tags": { "type": "array", "items": { "type": "string" } }, "industries": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "is_installed": { "type": "boolean", "description": "Indica se questo preset è attualmente installato nell'applicazione." } } }, "TransactionRuleInstallRequest": { "type": "object", "properties": { "library_keys": { "type": "array", "items": { "type": "string" }, "description": "Preset specifici da installare o disinstallare." }, "bundle": { "type": "string", "description": "Installa o disinstalla invece tutti i preset inclusi in questo bundle." } }, "description": "Fornisci library_keys OPPURE bundle." }, "TransactionRuleInstallResult": { "type": "object", "properties": { "installed_library_keys": { "type": "array", "items": { "type": "string" }, "description": "Solo POST (installazione): preset installati da questa chiamata." }, "installed_count": { "type": "integer", "description": "Solo POST (installazione)." }, "uninstalled_count": { "type": "integer", "description": "Solo per DELETE (disinstallazione): preimpostazioni rimosse da questa chiamata." } } }, "WalletScreeningResult": { "type": "object", "properties": { "provider": { "type": "string", "description": "Provider che ha eseguito lo screening (ad es. `merklescience`, `crystal`)." }, "screening_type": { "type": "string", "enum": [ "WALLET_SCREENING" ], "description": "Sempre `WALLET_SCREENING` per questo endpoint." }, "risk_score": { "type": "integer", "description": "Punteggio di rischio normalizzato da 0 a 100. Un valore più alto indica una maggiore esposizione a entità a rischio. Merkle Science assegna a un indirizzo un punteggio da 0 a 5, mappato su 0, 15, 35, 55, 75 o 95." }, "severity": { "type": "string", "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Fascia di rischio derivata da `risk_score`: `0-9` UNKNOWN, `10-39` LOW, `40-69` MEDIUM, `70-89` HIGH, `90-100` CRITICAL. `UNKNOWN` è la fascia più bassa, non uno stato separato di assenza di dati: un `risk_score` pari a 0 (il caso comune di indirizzo pulito) indica l'assenza di valutazioni avverse, mentre un punteggio diverso da zero compreso tra 1 e 9 è un segnale reale ma inferiore a LOW: leggi il `risk_score`, non solo la fascia. Non considerare mai `UNKNOWN` come una valutazione affermativa di basso rischio o di esito positivo; non visualizzarlo come superato." }, "status": { "type": "string", "enum": [ "SCREENED", "PENDING", "ERROR" ], "description": "Stato dell'esito dello screening." }, "summary": { "type": "string", "description": "Riepilogo leggibile dall'utente del risultato dello screening." }, "wallet_address": { "type": "string", "description": "L'indirizzo sottoposto a screening, restituito come conferma." }, "transaction_hash": { "type": "string", "nullable": true, "description": "Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre `null` nel risultato dello screening dei wallet." }, "blockchain": { "type": "string", "description": "La blockchain sottoposta a screening." }, "block_timestamp": { "type": "string", "nullable": true, "description": "Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre `null` nel risultato dello screening dei wallet." }, "total_value_usd": { "type": "number", "nullable": true, "description": "Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre `null` nel risultato dello screening dei wallet." }, "fee_usd": { "type": "number", "nullable": true, "description": "Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre `null` nel risultato dello screening dei wallet." }, "sender_rows": { "type": "array", "items": { "type": "object" }, "description": "Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre vuoto nel risultato dello screening dei wallet." }, "receiver_rows": { "type": "array", "items": { "type": "object" }, "description": "Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre vuoto nel risultato dello screening dei wallet." }, "transaction_flows": { "type": "array", "items": { "type": "object" }, "description": "Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre vuoto nel risultato dello screening dei wallet." }, "transaction_flows_status": { "type": "string", "nullable": true, "description": "Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre `null` nel risultato dello screening dei wallet." }, "transaction_flows_error": { "type": "string", "nullable": true, "description": "Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre `null` nel risultato dello screening dei wallet." }, "source_of_funds": { "type": "array", "description": "Da dove l'indirizzo ha ricevuto fondi, attribuiti per entità. Ogni voce rappresenta una suddivisione dell'esposizione.", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Categoria di rischio normalizzata, ad es. `exchange_licensed`, `dex`, `defi`, `payment_processor`, `mixer`, `darknet_market`, `sanctioned`, `stolen_funds`, `high_risk_exchange`." }, "percentage": { "type": "number", "description": "Quota dell'esposizione totale della direzione, 0-100." }, "amount_usd": { "type": "number", "nullable": true, "description": "Valore in USD attribuito a questa entità." }, "entity_name": { "type": "string", "nullable": true, "description": "Nome dell'entità attribuita, ad esempio un exchange, un mixer o un gruppo sanzionato." }, "entity_type": { "type": "string", "nullable": true, "description": "Tipo di entità del provider (ad es. `Exchange`, `DeFi`, `Sanctions`, `Theft`)." }, "entity_subtype": { "type": "string", "nullable": true, "description": "Sottotipo più granulare (ad es. `Mandatory KYC and AML`, `OFAC`, `Yield Aggregator`)." }, "hops": { "type": "integer", "nullable": true, "description": "Numero di passaggi (hop) verso l'entità (1 per una controparte diretta), quando il provider ne segnala uno. Sempre `null` per Merkle Science, che indica solo se l'esposizione è diretta o indiretta: utilizza `exposure_type`." }, "description": { "type": "string", "nullable": true, "description": "`entity_type / entity_subtype`, come il provider etichetta l'entità." }, "is_direct": { "type": "boolean", "description": "True quando `exposure_type` è `direct`." }, "exposure_direction": { "type": "string", "enum": [ "incoming", "outgoing", "connected" ], "description": "Indica se i fondi provenivano da (`incoming`) o sono andati a (`outgoing`) questa entità." }, "exposure_type": { "type": "string", "enum": [ "direct", "indirect" ], "description": "Esposizione `direct` (1 hop) o `indirect` (multi-hop)." }, "provider_entity_id": { "type": "string", "nullable": true, "description": "L'identificatore del provider per l'entità." }, "provider_entity_type_id": { "type": "string", "nullable": true, "description": "L'identificatore del provider per `entity_type`." }, "provider_entity_subtype_id": { "type": "string", "nullable": true, "description": "L'identificatore del provider per `entity_subtype`." }, "country": { "type": "string", "nullable": true, "description": "Paese principale ISO 3166-1 alpha-2 dell'entità. Vuoto o `null` se il fornitore non lo conosce." }, "raw_amount": { "type": "number", "nullable": true, "description": "Importo nell'unità dell'asset, quando il fornitore lo riporta." }, "raw_currency": { "type": "string", "nullable": true, "description": "Unità di `raw_amount`, quando segnalata dal provider." } } } }, "destination_of_funds": { "type": "array", "description": "A chi l'indirizzo ha inviato fondi, attribuiti per entità. Stessa struttura degli elementi di `source_of_funds` con `exposure_direction` = `outgoing`.", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "Categoria di rischio normalizzata, ad es. `exchange_licensed`, `dex`, `defi`, `payment_processor`, `mixer`, `darknet_market`, `sanctioned`, `stolen_funds`, `high_risk_exchange`." }, "percentage": { "type": "number", "description": "Quota dell'esposizione totale della direzione, 0-100." }, "amount_usd": { "type": "number", "nullable": true, "description": "Valore in USD attribuito a questa entità." }, "entity_name": { "type": "string", "nullable": true, "description": "Nome dell'entità attribuita, ad esempio un exchange, un mixer o un gruppo sanzionato." }, "entity_type": { "type": "string", "nullable": true, "description": "Tipo di entità del provider (ad es. `Exchange`, `DeFi`, `Sanctions`, `Theft`)." }, "entity_subtype": { "type": "string", "nullable": true, "description": "Sottotipo più granulare (ad es. `Mandatory KYC and AML`, `OFAC`, `Yield Aggregator`)." }, "hops": { "type": "integer", "nullable": true, "description": "Numero di passaggi (hop) verso l'entità (1 per una controparte diretta), quando il provider ne segnala uno. Sempre `null` per Merkle Science, che indica solo se l'esposizione è diretta o indiretta: utilizza `exposure_type`." }, "description": { "type": "string", "nullable": true, "description": "`entity_type / entity_subtype`, come il provider etichetta l'entità." }, "is_direct": { "type": "boolean", "description": "True quando `exposure_type` è `direct`." }, "exposure_direction": { "type": "string", "enum": [ "incoming", "outgoing", "connected" ], "description": "Indica se i fondi provenivano da (`incoming`) o sono andati a (`outgoing`) questa entità." }, "exposure_type": { "type": "string", "enum": [ "direct", "indirect" ], "description": "Esposizione `direct` (1 hop) o `indirect` (multi-hop)." }, "provider_entity_id": { "type": "string", "nullable": true, "description": "L'identificatore del provider per l'entità." }, "provider_entity_type_id": { "type": "string", "nullable": true, "description": "L'identificatore del provider per `entity_type`." }, "provider_entity_subtype_id": { "type": "string", "nullable": true, "description": "L'identificatore del provider per `entity_subtype`." }, "country": { "type": "string", "nullable": true, "description": "Paese principale ISO 3166-1 alpha-2 dell'entità. Vuoto o `null` se il fornitore non lo conosce." }, "raw_amount": { "type": "number", "nullable": true, "description": "Importo nell'unità dell'asset, quando il fornitore lo riporta." }, "raw_currency": { "type": "string", "nullable": true, "description": "Unità di `raw_amount`, quando segnalata dal provider." } } } }, "counterparty_connections": { "type": "array", "description": "Entità a cui il provider attribuisce l'indirizzo esaminato. Per Merkle Science queste provengono dai tag di proprietario e utente dell'indirizzo stesso, quindi la stessa entità può comparire due volte, e non riportano flussi di fondi: `received_usd`, `sent_usd`, `received_hops` e `sent_hops` sono `null` e `percentage` è 0. Non indirizzare qui in base a `risk_level` o `is_direct`: usa `sanctions_hit`, `dominant_risk_category` e `risk_factors[].is_high_risk` per l'esito, e `exposure_type` in `source_of_funds`/`destination_of_funds` per verificare se l'esposizione sia diretta.", "items": { "type": "object", "properties": { "entity_name": { "type": "string", "nullable": true, "description": "Nome dell'entità attribuita." }, "entity_type": { "type": "string", "nullable": true, "description": "Tipo di entità del provider." }, "entity_subtype": { "type": "string", "nullable": true, "description": "Sottotipo di entità del provider." }, "risk_level": { "type": "string", "description": "In lettere minuscole e dipendente dal provider. Per Merkle Science corrisponde al livello di rischio 0-5 dell'indirizzo stesso (`no_risk`, `low`, `medium_low`, `medium`, `high`, `critical`), innalzato ad `high` quando la categoria dell'entità è ad alto rischio; non si tratta di una valutazione separata dell'entità." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Categorie di rischio normalizzate dell'entità." }, "received_usd": { "type": "number", "nullable": true, "description": "USD ricevuti dall'entità, quando comunicati dal provider." }, "sent_usd": { "type": "number", "nullable": true, "description": "USD inviati all'entità, quando comunicati dal provider." }, "received_hops": { "type": "integer", "nullable": true, "description": "Salti verso l'entità sul lato ricevente, quando il provider li segnala." }, "sent_hops": { "type": "integer", "nullable": true, "description": "Salti verso l'entità sul lato mittente, quando il provider li segnala." }, "percentage": { "type": "number", "description": "Quota dell'esposizione dell'indirizzo, quando riportata dal fornitore; altrimenti 0." }, "is_direct": { "type": "boolean", "description": "Sempre `true` per Merkle Science, le cui connessioni sono attribuzioni anziché controparti." }, "country": { "type": "string", "nullable": true, "description": "Paese dell'entità, se noto." }, "provider_entity_id": { "type": "string", "nullable": true, "description": "L'identificatore del provider per l'entità." } } } }, "network_nodes": { "type": "array", "items": { "type": "object" }, "description": "Nodi del grafo di esposizione per lo screening delle transazioni. Vuoto nei risultati dello screening dei wallet." }, "network_edges": { "type": "array", "items": { "type": "object" }, "description": "Archi del grafo di esposizione per lo screening delle transazioni. Vuoto nel risultato dello screening dei wallet." }, "sanctions_hit": { "type": "boolean", "description": "True se l'indirizzo ha un'esposizione diretta o indiretta a sanzioni." }, "pep_counterparty": { "type": "boolean", "description": "Esposizione come persona politicamente esposta. `null` quando non è disponibile alcun riscontro PEP, il che corrisponde a ogni risultato attuale poiché nessun provider ne segnala uno; `false` solo per un risultato esplicito negativo dello screening. Non interpretare `null` come un controllo PEP completato.", "nullable": true }, "dominant_risk_category": { "type": "string", "nullable": true, "description": "Categoria ad alto rischio con il peso maggiore, o `null` quando nessuna è dominante (ad es. `sanctioned`, `mixer`, `stolen_funds`)." }, "risk_factors": { "type": "array", "description": "Spiegazione ordinata di `risk_score`: cosa ha determinato questo verdetto. I fornitori valutano un indirizzo in base al proprio modello e restituiscono solo un verdetto (Merkle Science restituisce un numero intero da 0 a 5), quindi il punteggio da solo non è utilizzabile a livello operativo. Ordinata prima in base al rischio elevato, poi per il valore transitato attraverso ciascun fattore, limitata ai cinque più rilevanti; `source_of_funds` e `destination_of_funds` contengono sempre il dettaglio completo. Un valore elevato di `risk_score` senza alcuna voce `is_high_risk` significa che il fornitore non ha segnalato corrispondenze con sanzioni o entità associate e ha valutato l'indirizzo esclusivamente sul proprio modello di esposizione: `summary` lo indica esplicitamente.", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "attribution", "exposure" ], "description": "`attribution` indica ciò che il provider afferma essere l'indirizzo stesso (il suo tag o cluster); `exposure` indica dove si sono effettivamente spostati i suoi fondi." }, "category": { "type": "string", "description": "Categoria di rischio normalizzata, stesso vocabolario del dettaglio dell'esposizione." }, "label": { "type": "string", "description": "La dicitura originale del provider per il driver (ad es. `Gambling / Crypto only`), che corrisponde a quanto visualizzato anche nella console del provider." }, "entity_name": { "type": "string", "nullable": true, "description": "Entità attribuita all'origine del driver, ad esempio un sito di scommesse o un exchange." }, "direction": { "type": "string", "enum": [ "incoming", "outgoing", "connected", "unknown", "attribution" ], "description": "Direzione del flusso di fondi, `attribution` quando il fattore determinante è il tag dell'indirizzo stesso, o `unknown` quando il fornitore non ha riportato una direzione." }, "exposure_type": { "type": "string", "enum": [ "direct", "indirect", "unknown", "attribution" ], "description": "`direct` (1 hop) o `indirect` (multi-hop), `attribution` per il tag dell'indirizzo stesso, oppure `unknown` quando il provider non ha specificato a quanti hop di distanza si trova la controparte. Considera `unknown` come non classificato, non come `direct`." }, "amount_usd": { "type": "number", "format": "float", "nullable": true, "description": "Valore in USD attribuito a questo driver." }, "percentage": { "type": "number", "format": "float", "description": "Quota del volume TOTALE analizzato dell'indirizzo, entrambe le direzioni combinate - a differenza di `percentage` all'interno di `source_of_funds`/`destination_of_funds`, che è normalizzato per direzione. Confrontabile e sommabile nell'intero elenco." }, "is_high_risk": { "type": "boolean", "description": "Indica se la categoria è tra quelle che Didit tratta come ad alto rischio (`sanctioned`, `mixer`, `stolen_funds`, `ransomware`, `scam`, `darknet_market`, `terrorist_financing`, `child_exploitation`, `hacked_exchange`, `high_risk_exchange`, `seized_funds`)." }, "description": { "type": "string", "description": "Rappresentazione su una riga del driver, ad es. `9.01% indirect outgoing exposure to Gambling / Crypto only (Example Gambling)`." } } } }, "raw_response": { "type": "object", "additionalProperties": true, "description": "Il payload proprietario del provider. La sua struttura è specifica del provider e può cambiare senza preavviso: leggi i campi normalizzati invece di effettuarne il parsing." }, "report_signature": { "type": "string", "description": "Firma HMAC-SHA256 opaca su questo risultato esatto, limitata alla tua applicazione. Non ha significato da sola: invia nuovamente il corpo completo della risposta, non modificato e includendo questo campo, a `POST /v3/wallet-screening/pdf/` per generarlo come PDF. L'endpoint PDF rifiuta la richiesta con `400` se `report_signature` manca o se qualsiasi campo firmato (ad es. `risk_score`, `severity`, `sanctions_hit`) è stato modificato prima del nuovo invio." } }, "required": [ "provider", "screening_type", "risk_score", "severity", "status", "summary", "wallet_address", "blockchain", "sanctions_hit", "dominant_risk_category", "source_of_funds", "destination_of_funds", "counterparty_connections", "report_signature" ] }, "NetworkRiskDisplay": { "type": "object", "properties": { "score": { "type": "integer", "description": "Punteggio di rischio, 0-100." }, "band": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Fascia a cui viene assegnato il punteggio. high >= 70, medium >= 40, altrimenti low." }, "bar": { "type": "number", "format": "float", "description": "Valore normalizzato compreso tra 0 e 1 per il rendering di una barra di rischio." } } }, "NetworkNodeTag": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true, "description": "Null per i tag di protezione, il cui token di colore appartiene al renderer." }, "source": { "type": "string", "enum": [ "subject_tag", "session_tag", "transaction_tag", "signal_guard" ], "description": "Da dove proviene il tag: un tag sull'utente/azienda, un tag su una sessione in questa rete, un tag su una transazione a cui appartiene una parte o una condizione di protezione del segnale (ad es. hub, IP di datacenter)." }, "category": { "type": "string", "enum": [ "customer", "quality" ], "nullable": true, "description": "customer per i tag definiti dal cliente, quality per i tag di protezione della qualità del segnale. Null se non applicabile." } } }, "NetworkListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "network_id": { "type": "string", "description": "ID sequenziale per organizzazione leggibile dall'utente, ad es. N-0001." }, "name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "in_review", "resolved", "dismissed" ], "description": "Stato del ciclo di vita della rete. Distinto dall'outcome_status per richiedente all'interno di una rete (approved/in_review/declined/not_completed)." }, "risk": { "$ref": "#/components/schemas/NetworkRiskDisplay" }, "pattern_types": { "type": "array", "items": { "type": "string", "enum": [ "exact_same_device", "similar_device", "same_ip_address", "same_address", "similar_selfie_backgrounds", "similar_poa_documents", "same_document_number", "same_phone_number", "same_email" ] }, "description": "I pattern di clustering rilevati in questa rete." }, "signal_types": { "type": "array", "items": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] }, "description": "I diversi tipi di segnale presenti in questa rete." }, "member_counts": { "type": "object", "description": "Conteggi dei membri per categoria (ad es. totale, per outcome_status)." }, "member_status": { "type": "object", "description": "Suddivisione dei membri per outcome_status." }, "signal_coverage": { "type": "object", "description": "Copertura per signal_type dei membri di questa rete." }, "first_activity_at": { "type": "string", "format": "date-time", "nullable": true }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true } } }, "NetworkDetail": { "allOf": [ { "$ref": "#/components/schemas/NetworkListItem" }, { "type": "object", "properties": { "stats": { "type": "object", "description": "Statistiche aggregate per la rete (ad es. totali dei membri)." }, "fraud_tags": { "type": "array", "items": { "type": "object" }, "description": "Tag dei pattern di frode rilevati sulla rete." }, "risk_signals": { "type": "object", "description": "Riepiloghi dei segnali di rischio: residential_proxy_reuse, email_intelligence, phone_intelligence." }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_by": { "type": "string", "nullable": true }, "review_reason": { "type": "string", "nullable": true } } } ], "properties": { "notes_count": { "type": "integer", "minimum": 0, "readOnly": true, "description": "Numero di note private dell'analista in questa indagine." } } }, "NetworkGraphNode": { "type": "object", "description": "Un nodo soggetto o un nodo segnale, distinti per kind. I nodi soggetto (kind: vendor_user | vendor_business | transaction_party) contengono id, kind, subject, node_status (approved | in_review | declined | not_completed) e tags. I nodi segnale (kind: signal) contengono id, kind, uuid, signal_type, subject_count, coverage, is_hub, is_datacenter_ip, is_high_collision_device, node_status (signal_active | signal_guarded), tags, risk_evidence, first_seen_at e last_seen_at.", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "vendor_user", "vendor_business", "transaction_party", "signal" ] } } }, "NetworkGraphEdge": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "description": "ID del nodo soggetto." }, "target": { "type": "string", "description": "ID del nodo di segnale." }, "subject_kind": { "type": "string", "enum": [ "vendor_user", "vendor_business", "transaction_party" ] }, "signal_type": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] }, "confidence": { "type": "number", "format": "float", "description": "1.0 per una corrispondenza esatta." }, "observation_count": { "type": "integer" }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "NetworkGraph": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/NetworkDetail" }, "depth": { "type": "integer", "nullable": true, "description": "Profondità effettiva applicata, o null se non limitata (depth=all)." }, "truncated": { "type": "boolean", "description": "True se il vicinato è stato troncato a causa della profondità." }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkGraphNode" } }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkGraphEdge" } }, "metrics": { "type": "object", "properties": { "node_count": { "type": "integer" }, "edge_count": { "type": "integer" }, "hub_signal_count": { "type": "integer" } } } } }, "NetworkMember": { "type": "object", "properties": { "subject": { "type": "object", "description": "Il vendor_user, vendor_business o transaction_party rappresentato da questo membro." }, "outcome_status": { "type": "string", "description": "L'esito di verifica/decisione del soggetto." }, "node_status": { "type": "string", "enum": [ "approved", "in_review", "declined", "not_completed", "signal_active", "signal_guarded" ], "description": "Per una riga membro questo è sempre uno dei valori subject-outcome: approved, in_review, declined o not_completed." }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkNodeTag" } }, "risk": { "$ref": "#/components/schemas/NetworkRiskDisplay" }, "signal_coverage": { "type": "object" }, "shared_infrastructure": { "type": "object" }, "joined_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "provenance": { "type": "object", "properties": { "session_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "business_session_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "transaction_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } }, "NetworkSignal": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "signal_type": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] }, "subject_count": { "type": "integer" }, "coverage": { "type": "number", "format": "float" }, "is_hub": { "type": "boolean", "description": "True quando questo segnale collega un numero insolitamente elevato di soggetti." }, "is_datacenter_ip": { "type": "boolean" }, "is_high_collision_device": { "type": "boolean" }, "node_status": { "type": "string", "enum": [ "signal_active", "signal_guarded" ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkNodeTag" } }, "risk_evidence": { "type": "object" }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "NetworkTimelineEvent": { "type": "object", "properties": { "event_type": { "type": "string", "description": "ad es. network_detected, signal_observed, network_in_review, network_resolved, network_dismissed." }, "occurred_at": { "type": "string", "format": "date-time", "nullable": true }, "label": { "type": "string" }, "metadata": { "type": "object" } } }, "NetworkMap": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/NetworkDetail" }, "convergence_count": { "type": "integer", "description": "Numero di punti di indirizzo/posizione distinti su cui convergono i membri." }, "countries": { "type": "array", "items": { "type": "string" } }, "points": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "country": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "float", "nullable": true }, "longitude": { "type": "number", "format": "float", "nullable": true }, "observed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "EntityNetworkMembership": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/NetworkListItem" }, "subject": { "type": "object" }, "signal_types": { "type": "array", "items": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] } }, "signal_count": { "type": "integer" }, "joined_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "RiskSignals": { "type": "object", "description": "Contesto facoltativo di dispositivo e rete rilevato dalla tua applicazione. Tutti i campi sono facoltativi. Fornirli alimenta il rilevamento delle corrispondenze tra sessioni in Reti.", "properties": { "ip": { "type": "string", "format": "ip", "description": "Indirizzo IPv4 o IPv6 rilevato per l'utente finale.", "example": "192.0.2.1" }, "device_id": { "type": "string", "maxLength": 255, "description": "Identificatore stabile del dispositivo raccolto dalla tua applicazione (`ANDROID_ID` per Android, `identifierForVendor` per iOS)." }, "device_platform": { "type": "string", "enum": [ "android", "ios", "ipados", "tvos", "web" ], "description": "Piattaforma del dispositivo dell'utente finale." }, "device_model": { "type": "string", "maxLength": 255, "description": "Modello del dispositivo segnalato dalla tua applicazione." }, "os_version": { "type": "string", "maxLength": 64, "description": "Versione del sistema operativo." }, "app_version": { "type": "string", "maxLength": 64, "description": "Versione della tua applicazione." }, "user_agent": { "type": "string", "maxLength": 512, "description": "User agent del browser o dell'app." } } }, "PhoneRiskRequest": { "type": "object", "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string", "maxLength": 20, "description": "Numero di telefono da valutare. Viene validato e normalizzato in formato E.164.", "example": "+14155552671" }, "country_code": { "type": "string", "maxLength": 3, "description": "Suggerimento facoltativo sul paese ISO 3166-1 alpha-2 o alpha-3 per la copertura dell'intelligence.", "example": "US" }, "signals": { "$ref": "#/components/schemas/RiskSignals" }, "vendor_data": { "type": "string", "description": "Il tuo riferimento stabile per questa richiesta. Memorizzato nella sessione API e restituito nella risposta." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "I tuoi metadati JSON non sensibili. Memorizzati nella sessione API e restituiti nella risposta." }, "enable_social": { "type": "boolean", "default": false, "description": "Se true, cerca anche l'impronta social del numero: le piattaforme di messaggistica, social, e-commerce e professionali su cui è registrato. Fatturato come un'unità `phone_social` per richiesta in aggiunta al prezzo di questo endpoint.", "example": true } } }, "EmailRiskRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Indirizzo email da valutare.", "example": "alice@example.com" }, "country_code": { "type": "string", "maxLength": 3, "description": "Suggerimento facoltativo sul paese ISO 3166-1 alpha-2 o alpha-3 per la copertura dell'intelligence.", "example": "US" }, "signals": { "$ref": "#/components/schemas/RiskSignals" }, "vendor_data": { "type": "string", "description": "Il tuo riferimento stabile per questa richiesta. Memorizzato nella sessione API e restituito nella risposta." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "I tuoi metadati JSON non sensibili. Memorizzati nella sessione API e restituiti nella risposta." }, "enable_social": { "type": "boolean", "default": false, "description": "Se true, cerca anche l'impronta social dell'indirizzo: le piattaforme email, social, professionali, di e-commerce e di intrattenimento su cui è registrato. Fatturato come un'unità `email_social` per richiesta in aggiunta al prezzo di questo endpoint.", "example": true } } }, "IPRiskRequest": { "type": "object", "required": [ "ip_address" ], "properties": { "ip_address": { "type": "string", "format": "ip", "description": "Indirizzo IPv4 o IPv6 a cui assegnare un punteggio.", "example": "8.8.8.8" }, "claimed_country": { "type": "string", "maxLength": 3, "description": "Paese opzionale ISO 3166-1 alpha-2 o alpha-3 dichiarato dall'utente o dalla sessione. Utilizzato per calcolare `country_mismatch`.", "example": "ESP" }, "user_agent": { "type": "string", "maxLength": 512, "description": "User agent rilevato dal tuo backend. Memorizzato come contesto della richiesta; non fornisce il fingerprinting del dispositivo." }, "vendor_data": { "type": "string", "description": "Il tuo riferimento stabile per questa richiesta. Memorizzato nella sessione API e restituito nella risposta." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "I tuoi metadati JSON non sensibili. Memorizzati nella sessione API e restituiti nella risposta." } } }, "RiskWarning": { "type": "object", "required": [ "feature", "risk", "log_type", "short_description", "long_description" ], "properties": { "feature": { "type": "string", "description": "Funzionalità che ha generato l'avviso." }, "risk": { "type": "string", "description": "Codice di rischio leggibile dalla macchina. Nuovi valori possono essere aggiunti nel tempo." }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contesto specifico del rischio, oppure `null`." }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "Gravità utilizzata dalle regole di decisione." }, "short_description": { "type": "string", "description": "Riepilogo su una riga leggibile dall'utente." }, "long_description": { "type": "string", "description": "Spiegazione di facile lettura." } } }, "RiskLifecycleEvent": { "type": "object", "required": [ "type", "timestamp", "details", "fee" ], "properties": { "type": { "type": "string", "description": "Tipo di evento leggibile dalla macchina. Nuovi valori possono essere aggiunti nel tempo." }, "timestamp": { "type": "string", "format": "date-time", "description": "Data e ora in cui si è verificato l'evento." }, "details": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Payload specifico dell'evento, o `null`." }, "fee": { "type": "number", "description": "Importo in USD fatturato per questo evento." } } }, "PhoneMatchItem": { "type": "object", "description": "Un'altra sessione della tua applicazione che ha utilizzato lo stesso numero di telefono con un `vendor_data` diverso.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID sessione dell'altra verifica che ha utilizzato questo numero di telefono." }, "session_number": { "type": "integer", "description": "Numero progressivo di facile lettura di tale sessione." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` di quella sessione." }, "verification_date": { "type": "string", "description": "Data e ora di creazione di quella sessione (`YYYY-MM-DDTHH:MM:SSZ`)." }, "phone_number": { "type": "string", "description": "Il numero di telefono corrispondente." }, "status": { "type": "string", "description": "Stato di quella sessione (ad es., `Approved`, `Declined`, `In Progress`)." }, "is_blocklisted": { "type": "boolean", "description": "Indica se il numero di telefono è presente nella blocklist della tua applicazione." }, "api_service": { "type": "string", "nullable": true, "description": "Per le sessioni di tipo API, l'API standalone che l'ha creata; `null` per le normali sessioni di verifica." }, "source": { "type": "string", "description": "Dove è stata trovata la corrispondenza. Di solito `session`; un riscontro nella blocklist tramite una voce dell'elenco dell'organizzazione utilizza `list_entry`." } } }, "EmailMatchItem": { "type": "object", "description": "Un'altra sessione della tua applicazione che ha utilizzato lo stesso indirizzo email con un `vendor_data` diverso.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "ID sessione dell'altra verifica che ha utilizzato questo indirizzo email." }, "session_number": { "type": "integer", "description": "Numero progressivo di facile lettura di tale sessione." }, "vendor_data": { "type": "string", "nullable": true, "description": "`vendor_data` di quella sessione." }, "verification_date": { "type": "string", "description": "Data e ora di creazione di quella sessione (`YYYY-MM-DDTHH:MM:SSZ`)." }, "email": { "type": "string", "description": "L'indirizzo email corrispondente." }, "status": { "type": "string", "description": "Stato di quella sessione (ad es., `Approved`, `Declined`, `In Progress`)." }, "is_blocklisted": { "type": "boolean", "description": "Indica se l'indirizzo email è presente nella blocklist della tua applicazione." }, "api_service": { "type": "string", "nullable": true, "description": "Per le sessioni di tipo API, l'API standalone che l'ha creata; `null` per le normali sessioni di verifica." }, "source": { "type": "string", "description": "Dove è stata trovata la corrispondenza. Di solito `session`; un riscontro nella blocklist tramite una voce dell'elenco dell'organizzazione utilizza `list_entry`." } } }, "PhoneIntelligence": { "type": "object", "description": "Blocco normalizzato di phone intelligence. Presente solo quando l'add-on di intelligence è stato eseguito per questa ricerca; se presente, è esposto anche sotto l'alias `enrichment` con valori identici.", "properties": { "score": { "type": "number", "nullable": true, "description": "Punteggio di rischio normalizzato da 0 a 100. Più alto è il punteggio, maggiore è il rischio." }, "phone_type_risk": { "type": "string", "nullable": true, "description": "`Low`, `Medium` o `High`, derivato dal punteggio." }, "phone_trust_index": { "type": "number", "nullable": true, "description": "Inverso del punteggio, per le dashboard che preferiscono un valore più alto come migliore." }, "network_stability_index": { "type": "number", "nullable": true, "description": "Stabilità della rete della linea." }, "is_disposable": { "type": "boolean", "nullable": true, "description": "`true` quando il numero sembra essere usa e getta o virtuale." }, "is_ported": { "type": "boolean", "nullable": true, "description": "`true` quando il numero ha cambiato operatore." }, "is_recently_ported": { "type": "boolean", "nullable": true, "description": "`true` quando la portabilità è avvenuta di recente." }, "carrier_type": { "type": "string", "nullable": true, "description": "Classificazione della linea rilevata dalla ricerca (es. `mobile`)." }, "reason_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Identificatore Didit stabile del segnale, ad esempio `IR-5AC67A32`. Opaco: usalo per raggruppare e filtrare, non analizzarlo." }, "value": { "nullable": true, "description": "Per un flag di rischio (ad esempio `voip`, `leaked`, `disposable`, `spam_trap`), il suo valore: un booleano, un livello o una data. Null per un codice motivo con punteggio." }, "direction": { "type": "string", "enum": [ "risk", "trust" ], "description": "Indica se il segnale ha aumentato il rischio o ha aggiunto affidabilità." }, "message": { "type": "string", "description": "Spiegazione di facile lettura del segnale, in inglese." }, "impact_level": { "type": "string", "nullable": true, "description": "Con quale intensità il segnale ha modificato il punteggio, ad esempio `low`, `medium` o `high`." } } }, "description": "Segnali che spiegano il punteggio, ciascuno con un codice Didit stabile, una direzione, un messaggio e un livello di impatto. Nel tempo possono comparire nuovi codici, pertanto non rifiutare i codici sconosciuti." } } }, "EmailIntelligence": { "type": "object", "description": "Blocco normalizzato di email intelligence. Presente solo quando l'add-on di intelligence è stato eseguito per questa email; se presente, è esposto anche come alias `enrichment` con valori identici.", "properties": { "score": { "type": "number", "nullable": true, "description": "Punteggio di rischio normalizzato da 0 a 100. Più alto è il punteggio, maggiore è il rischio." }, "deliverable": { "type": "string", "nullable": true, "description": "Fascia di recapitabilità (ad es. `high`)." }, "breach_risk_level": { "type": "string", "nullable": true, "description": "`Low`, `Medium` o `High`." }, "breach_risk_index": { "type": "number", "nullable": true, "description": "Indice numerico del rischio di violazione." }, "is_recent_breach": { "type": "boolean", "nullable": true, "description": "`true` quando l'indirizzo compare in una violazione recente." }, "is_frequent_breached": { "type": "boolean", "nullable": true, "description": "`true` quando l'indirizzo compare in numerose violazioni." }, "is_disposable": { "type": "boolean", "nullable": true, "description": "`true` quando il dominio è un provider usa e getta." }, "is_free_domain": { "type": "boolean", "nullable": true, "description": "`true` quando il dominio è un provider di email gratuito." }, "is_breached": { "type": "boolean", "nullable": true, "description": "`true` quando l'indirizzo compare in violazioni note." }, "no_of_breaches": { "type": "number", "nullable": true, "description": "Numero di violazioni note che contengono l'indirizzo." }, "reason_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Identificatore Didit stabile del segnale, ad esempio `IR-5AC67A32`. Opaco: usalo per raggruppare e filtrare, non analizzarlo." }, "value": { "nullable": true, "description": "Per un flag di rischio (ad esempio `voip`, `leaked`, `disposable`, `spam_trap`), il suo valore: un booleano, un livello o una data. Null per un codice motivo con punteggio." }, "direction": { "type": "string", "enum": [ "risk", "trust" ], "description": "Indica se il segnale ha aumentato il rischio o ha aggiunto affidabilità." }, "message": { "type": "string", "description": "Spiegazione di facile lettura del segnale, in inglese." }, "impact_level": { "type": "string", "nullable": true, "description": "Con quale intensità il segnale ha modificato il punteggio, ad esempio `low`, `medium` o `high`." } } }, "description": "Segnali che spiegano il punteggio, ciascuno con un codice Didit stabile, una direzione, un messaggio e un livello di impatto. Nel tempo possono comparire nuovi codici, pertanto non rifiutare i codici sconosciuti." } } }, "IPRiskResult": { "type": "object", "description": "Risultato del rischio IP. I singoli campi di arricchimento possono essere `null` quando la ricerca non ha restituito dati utilizzabili.", "required": [ "status", "threat" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review" ], "description": "`In Review` quando il paese rilevato è in conflitto con `claimed_country` o quando l'indirizzo è associato a un'infrastruttura VPN, Tor o data center. Altrimenti `Approved`." }, "ip_address": { "type": "string", "nullable": true, "description": "L'indirizzo valutato. `null` quando nessuna fonte di arricchimento ha restituito dati utilizzabili." }, "ip_country": { "type": "string", "nullable": true, "description": "Nome del paese risolto." }, "ip_country_code": { "type": "string", "nullable": true, "description": "Codice paese risolto. Confronta i paesi tramite `country_mismatch` invece di confrontare manualmente le stringhe dei paesi non elaborate." }, "ip_state": { "type": "string", "nullable": true, "description": "Stato o regione determinati." }, "ip_city": { "type": "string", "nullable": true, "description": "Città risolta." }, "latitude": { "type": "number", "nullable": true, "description": "Geolocalizzazione di rete approssimativa, non la posizione precisa del dispositivo." }, "longitude": { "type": "number", "nullable": true, "description": "Geolocalizzazione di rete approssimativa, non la posizione precisa del dispositivo." }, "isp": { "type": "string", "nullable": true, "description": "Provider di servizi Internet che fornisce il servizio all'indirizzo." }, "organization": { "type": "string", "nullable": true, "description": "Organizzazione proprietaria del blocco di indirizzi." }, "is_vpn_or_tor": { "type": "boolean", "nullable": true, "description": "`true` quando l'indirizzo è associato a un'infrastruttura VPN o Tor." }, "is_data_center": { "type": "boolean", "nullable": true, "description": "`true` quando l'indirizzo appartiene a una rete di hosting o data center." }, "time_zone": { "type": "string", "nullable": true, "description": "Fuso orario della posizione risolta." }, "time_zone_offset": { "type": "string", "nullable": true, "description": "Offset UTC della posizione risolta." }, "asn_number": { "type": "number", "nullable": true, "description": "Numero di sistema autonomo." }, "asn_organization": { "type": "string", "nullable": true, "description": "Organizzazione che gestisce il sistema autonomo." }, "connection_type": { "type": "string", "nullable": true, "description": "Classificazione della connessione (ad es. `cellular`, `hosting`)." }, "carrier": { "type": "string", "nullable": true, "description": "Operatore mobile quando l'indirizzo si trova su una rete mobile." }, "proxy_type": { "type": "string", "nullable": true, "description": "Classificazione proxy quando l'indirizzo si trova dietro un proxy." }, "claimed_country": { "type": "string", "nullable": true, "description": "Eco del `claimed_country` inviato." }, "country_mismatch": { "type": "boolean", "nullable": true, "description": "`true` quando il paese determinato differisce da `claimed_country`. `null` quando non sono disponibili dati di arricchimento o non è disponibile alcun paese dichiarato." }, "threat": { "type": "object", "additionalProperties": true, "description": "Evidenze di minaccia di rete a struttura libera dalla fonte di arricchimento (ad es. `is_proxy`, `is_tor`). Oggetto vuoto quando non sono disponibili dati di arricchimento. Consideralo un dettaglio diagnostico, non un contratto stabile." } } }, "PhoneRiskResponse": { "type": "object", "required": [ "request_id", "status", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione API creata per questa richiesta. Memorizzalo con `vendor_data` se hai bisogno di correlare il risultato con i webhook successivi o con l'attività nella console." }, "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Decisione finale per questa sessione API. Di norma `Approved`; la valutazione del rischio può produrre `In Review` o `Declined`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, `null` se non ne hai inviato alcuno." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco del `metadata` inviato, `null` se non ne hai inviato alcuno." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp di questa risposta." }, "phone": { "type": "object", "description": "Report normalizzato del telefono, lo stesso blocco utilizzato dalle risposte di Verifica telefonica.", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Decisione per questo numero di telefono. Rispecchia lo `status` di primo livello." }, "phone_number_prefix": { "type": "string", "description": "Prefisso telefonico internazionale del paese con `+` iniziale (es. `+1`).", "example": "+1" }, "phone_number": { "type": "string", "description": "Numero nazionale senza prefisso telefonico internazionale.", "example": "4155552671" }, "full_number": { "type": "string", "description": "Numero completo in formato E.164.", "example": "+14155552671" }, "country_code": { "type": "string", "nullable": true, "description": "Paese ISO 3166-1 alpha-2 del numero.", "example": "US" }, "country_name": { "type": "string", "description": "Nome completo del paese ricavato da `country_code`.", "example": "United States" }, "carrier": { "type": "object", "nullable": true, "description": "Rete attuale che serve il numero. `null` quando la ricerca non è riuscita a identificare un operatore.", "properties": { "name": { "type": "string", "description": "Nome dell'operatore telefonico. Stringa vuota quando la ricerca non è riuscita a identificarlo." }, "type": { "type": "string", "description": "Tipo di linea restituito dalla ricerca: `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate` o simile." } } }, "is_disposable": { "type": "boolean", "description": "`true` quando il numero appartiene a un servizio di numeri temporanei o usa e getta." }, "is_virtual": { "type": "boolean", "description": "`true` quando il tipo di linea è virtuale (`voip`, `isp` o `vpn`)." }, "verification_method": { "type": "string", "nullable": true, "description": "Canale OTP della verifica sottostante. `null` per le ricerche sul rischio, che non inviano mai un codice." }, "verification_attempts": { "type": "integer", "description": "Invii di OTP per questo numero. `0` per le ricerche del rischio." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il numero è stato verificato l'ultima volta tramite OTP. `null` per le ricerche di rischio." }, "warnings": { "type": "array", "description": "Avvisi di rischio registrati per questa richiesta. Array vuoto se non ne è presente alcuno.", "items": { "$ref": "#/components/schemas/RiskWarning" } }, "lifecycle": { "type": "array", "description": "Traccia di audit cronologica della richiesta. Array vuoto per le consultazioni del rischio senza eventi di invio.", "items": { "$ref": "#/components/schemas/RiskLifecycleEvent" } }, "matches": { "type": "array", "description": "Altre sessioni della tua applicazione in cui lo stesso numero di telefono è stato utilizzato da un utente diverso (`vendor_data` differente). Fino a 5 voci. Array vuoto quando non ci sono corrispondenze.", "items": { "$ref": "#/components/schemas/PhoneMatchItem" } }, "phone_intelligence": { "$ref": "#/components/schemas/PhoneIntelligence" }, "enrichment": { "$ref": "#/components/schemas/PhoneIntelligence" }, "phone_social": { "$ref": "#/components/schemas/PhoneSocialFootprint" } } } } }, "EmailRiskResponse": { "type": "object", "required": [ "request_id", "status", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione API creata per questa richiesta. Memorizzalo con `vendor_data` se hai bisogno di correlare il risultato con i webhook successivi o con l'attività nella console." }, "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Decisione finale per questa sessione API. Di norma `Approved`; la valutazione del rischio può produrre `In Review` o `Declined`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, `null` se non ne hai inviato alcuno." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco del `metadata` inviato, `null` se non ne hai inviato alcuno." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp di questa risposta." }, "email": { "type": "object", "description": "Report normalizzato di verifica email, lo stesso blocco utilizzato dalle risposte di Verifica email.", "required": [ "status", "email", "is_breached", "breaches", "is_disposable", "is_undeliverable" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "Decisione per questo indirizzo email. Rispecchia lo `status` di primo livello." }, "email": { "type": "string", "description": "L'indirizzo valutato.", "example": "alice@example.com" }, "is_breached": { "type": "boolean", "description": "Indica se l'indirizzo compare in una violazione nota delle credenziali." }, "breaches": { "type": "array", "description": "Fino a 5 delle violazioni note più recenti contenenti questo indirizzo. Array vuoto quando `is_breached` è `false`.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Identificatore della violazione." }, "domain": { "type": "string", "description": "Dominio del servizio violato." }, "breach_date": { "type": "string", "format": "date", "description": "Data in cui si è verificata la violazione." }, "breach_emails_count": { "type": "integer", "description": "Numero totale di account esposti nella violazione dei dati." }, "description": { "type": "string", "description": "Descrizione di facile lettura della violazione (può contenere markup HTML)." }, "logo_path": { "type": "string", "description": "URL del logo del servizio violato." }, "data_classes": { "type": "array", "items": { "type": "string" }, "description": "Categorie di dati esposti, in snake_case (ad es., `email_addresses`, `passwords`)." }, "is_verified": { "type": "boolean", "description": "Indica se la violazione è stata verificata come legittima." } } } }, "is_disposable": { "type": "boolean", "description": "Indica se il dominio appartiene a un provider usa e getta." }, "is_undeliverable": { "type": "boolean", "description": "Indica se l'indirizzo è risultato non recapitabile." }, "verification_attempts": { "type": "integer", "description": "Invii di OTP per questo indirizzo. `0` per le ricerche del rischio." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultima verifica dell'indirizzo tramite OTP. `null` per le ricerche di rischio." }, "warnings": { "type": "array", "description": "Avvisi di rischio registrati per questa richiesta. Array vuoto se non ne è presente alcuno.", "items": { "$ref": "#/components/schemas/RiskWarning" } }, "lifecycle": { "type": "array", "description": "Traccia di audit cronologica della richiesta. Array vuoto per le consultazioni del rischio senza invii.", "items": { "$ref": "#/components/schemas/RiskLifecycleEvent" } }, "matches": { "type": "array", "description": "Altre sessioni della tua applicazione in cui lo stesso indirizzo email è stato utilizzato da un utente diverso (`vendor_data` differente). Fino a 5 voci. Array vuoto quando non ci sono corrispondenze.", "items": { "$ref": "#/components/schemas/EmailMatchItem" } }, "email_intelligence": { "$ref": "#/components/schemas/EmailIntelligence" }, "enrichment": { "$ref": "#/components/schemas/EmailIntelligence" }, "email_social": { "$ref": "#/components/schemas/EmailSocialFootprint" } } } } }, "IPRiskResponse": { "type": "object", "required": [ "request_id", "status", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "ID della sessione API creata per questa richiesta. Memorizzalo con `vendor_data` se hai bisogno di correlare il risultato con i webhook successivi o con l'attività nella console." }, "status": { "type": "string", "enum": [ "Approved", "In Review" ], "description": "Decisione per questa sessione API: `In Review` in caso di rischio di rete o mancata corrispondenza del paese, altrimenti `Approved`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato, `null` se non ne hai inviato alcuno." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco del `metadata` inviato, `null` se non ne hai inviato alcuno." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp di questa risposta." }, "ip": { "type": "object", "description": "Risultato del rischio IP. I singoli campi di arricchimento possono essere `null` quando la ricerca non ha restituito dati utilizzabili.", "required": [ "status", "threat" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review" ], "description": "`In Review` quando il paese rilevato è in conflitto con `claimed_country` o quando l'indirizzo è associato a un'infrastruttura VPN, Tor o data center. Altrimenti `Approved`." }, "ip_address": { "type": "string", "nullable": true, "description": "L'indirizzo valutato. `null` quando nessuna fonte di arricchimento ha restituito dati utilizzabili." }, "ip_country": { "type": "string", "nullable": true, "description": "Nome del paese risolto." }, "ip_country_code": { "type": "string", "nullable": true, "description": "Codice paese risolto. Confronta i paesi tramite `country_mismatch` invece di confrontare manualmente le stringhe dei paesi non elaborate." }, "ip_state": { "type": "string", "nullable": true, "description": "Stato o regione determinati." }, "ip_city": { "type": "string", "nullable": true, "description": "Città risolta." }, "latitude": { "type": "number", "nullable": true, "description": "Geolocalizzazione di rete approssimativa, non la posizione precisa del dispositivo." }, "longitude": { "type": "number", "nullable": true, "description": "Geolocalizzazione di rete approssimativa, non la posizione precisa del dispositivo." }, "isp": { "type": "string", "nullable": true, "description": "Provider di servizi Internet che fornisce il servizio all'indirizzo." }, "organization": { "type": "string", "nullable": true, "description": "Organizzazione proprietaria del blocco di indirizzi." }, "is_vpn_or_tor": { "type": "boolean", "nullable": true, "description": "`true` quando l'indirizzo è associato a un'infrastruttura VPN o Tor." }, "is_data_center": { "type": "boolean", "nullable": true, "description": "`true` quando l'indirizzo appartiene a una rete di hosting o data center." }, "time_zone": { "type": "string", "nullable": true, "description": "Fuso orario della posizione risolta." }, "time_zone_offset": { "type": "string", "nullable": true, "description": "Offset UTC della posizione risolta." }, "asn_number": { "type": "number", "nullable": true, "description": "Numero di sistema autonomo." }, "asn_organization": { "type": "string", "nullable": true, "description": "Organizzazione che gestisce il sistema autonomo." }, "connection_type": { "type": "string", "nullable": true, "description": "Classificazione della connessione (ad es. `cellular`, `hosting`)." }, "carrier": { "type": "string", "nullable": true, "description": "Operatore mobile quando l'indirizzo si trova su una rete mobile." }, "proxy_type": { "type": "string", "nullable": true, "description": "Classificazione proxy quando l'indirizzo si trova dietro un proxy." }, "claimed_country": { "type": "string", "nullable": true, "description": "Eco del `claimed_country` inviato." }, "country_mismatch": { "type": "boolean", "nullable": true, "description": "`true` quando il paese determinato differisce da `claimed_country`. `null` quando non sono disponibili dati di arricchimento o non è disponibile alcun paese dichiarato." }, "threat": { "type": "object", "additionalProperties": true, "description": "Evidenze di minaccia di rete a struttura libera dalla fonte di arricchimento (ad es. `is_proxy`, `is_tor`). Oggetto vuoto quando non sono disponibili dati di arricchimento. Consideralo un dettaglio diagnostico, non un contratto stabile." } } } } }, "SocialFootprintPlatform": { "type": "object", "properties": { "platform": { "type": "string", "description": "Identificatore della piattaforma.", "example": "whatsapp" }, "category": { "type": "string", "description": "Categoria della piattaforma, ad es. MESSAGING, SOCIAL_MEDIA, ECOMMERCE, PROFESSIONAL, EMAIL_PROVIDER.", "example": "MESSAGING" }, "scope": { "type": "string", "enum": [ "global", "local" ], "description": "`global` per piattaforme globali, `local` per quelle specifiche di una regione.", "example": "global" } } }, "SocialFootprintCategorySummary": { "type": "object", "properties": { "registered": { "type": "integer", "nullable": true, "description": "Piattaforme in questa categoria in cui la registrazione è confermata.", "example": 2 }, "ratio": { "type": "number", "format": "float", "nullable": true, "description": "Quota delle piattaforme verificate della categoria con una registrazione, 0.0-1.0.", "example": 0.6667 } } }, "SocialFootprintProfile": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Nome del profilo, se esposto dalla piattaforma." }, "photo": { "type": "string", "nullable": true, "description": "URL della foto del profilo, se esposto dalla piattaforma." }, "about": { "type": "string", "nullable": true, "description": "Testo della bio/sezione informazioni del profilo, se esposto dalla piattaforma." }, "privacy_status": { "type": "string", "nullable": true, "enum": [ "PUBLIC", "PRIVATE", null ], "description": "Visibilità del profilo, se esposta dalla piattaforma." }, "business_account": { "type": "boolean", "nullable": true, "description": "Indica se il profilo è un account aziendale, quando la piattaforma lo rende disponibile." } } }, "PhoneSocialFootprint": { "type": "object", "nullable": true, "description": "Impronta social del numero di telefono: le piattaforme online su cui risulta registrato. Presente solo quando è stato impostato `enable_social` e il controllo è stato completato. Ciascun conteggio può essere null se non sono stati restituiti dati al riguardo. `profiles_registered: 0` indica che le piattaforme sono state controllate e il numero di telefono non è stato trovato su nessuna di esse: una risposta valida e fatturabile, nonché un tipico segnale di identità sintetica.", "properties": { "profiles_registered": { "type": "integer", "nullable": true, "description": "Piattaforme in cui il numero di telefono risulta registrato.", "example": 5 }, "profiles_checked": { "type": "integer", "nullable": true, "description": "Piattaforme valutate per la registrazione.", "example": 14 }, "names_found": { "type": "integer", "nullable": true, "description": "Piattaforme che hanno restituito un nome associato.", "example": 0 }, "photos_found": { "type": "integer", "nullable": true, "description": "Piattaforme che hanno restituito una foto del profilo.", "example": 0 }, "communication_breadth": { "type": "integer", "nullable": true, "description": "Piattaforme di comunicazione con presenza rilevata.", "example": 2 }, "digital_footprint_diversity": { "type": "integer", "nullable": true, "description": "Categorie di piattaforma distinte con presenza rilevata.", "example": 5 }, "digital_sophistication_index": { "type": "integer", "nullable": true, "description": "Indicatore composito di maturità digitale, 0-10.", "example": 5 }, "engagement_depth_index": { "type": "integer", "nullable": true, "description": "Indicatore della ricchezza del profilo, 0-10.", "example": 3 }, "subscription_affordability_index": { "type": "integer", "nullable": true, "description": "Mix di piattaforme gratuite rispetto a quelle a pagamento, 0-10.", "example": 2 }, "free_platforms": { "type": "integer", "nullable": true, "description": "Registrazioni su piattaforme gratuite.", "example": 4 }, "full_paid_platforms": { "type": "integer", "nullable": true, "description": "Registrazioni su piattaforme a pagamento completo.", "example": 0 }, "partial_paid_platforms": { "type": "integer", "nullable": true, "description": "Registrazioni su piattaforme freemium.", "example": 1 }, "whatsapp_profile_completeness": { "type": "string", "nullable": true, "enum": [ "Basic", "Partial", "Complete", "Not Present", null ], "description": "Completezza del profilo WhatsApp. Solo telefono; null per email.", "example": "Partial" }, "registered_platforms": { "type": "array", "description": "Piattaforme in cui la registrazione è confermata.", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "not_registered_platforms": { "type": "array", "description": "Piattaforme verificate con esito negativo.", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "categories": { "type": "object", "description": "Numero di registrazioni e percentuale per categoria di piattaforma.", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintCategorySummary" } }, "profiles": { "type": "object", "description": "Dettagli del profilo per piattaforma, indicizzati per piattaforma, quando la piattaforma li rende disponibili.", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintProfile" } } } }, "EmailSocialFootprint": { "type": "object", "nullable": true, "description": "Impronta social dell'indirizzo email: le piattaforme online su cui risulta registrato. Presente solo quando è stato impostato `enable_social` e il controllo è stato completato. Ciascun conteggio può essere null se non sono stati restituiti dati al riguardo. `profiles_registered: 0` indica che le piattaforme sono state controllate e l'indirizzo email non è stato trovato su nessuna di esse: una risposta valida e fatturabile, nonché un tipico segnale di identità sintetica.", "properties": { "profiles_registered": { "type": "integer", "nullable": true, "description": "Piattaforme in cui l'indirizzo email risulta registrato.", "example": 5 }, "profiles_checked": { "type": "integer", "nullable": true, "description": "Piattaforme valutate per la registrazione.", "example": 14 }, "names_found": { "type": "integer", "nullable": true, "description": "Piattaforme che hanno restituito un nome associato.", "example": 0 }, "photos_found": { "type": "integer", "nullable": true, "description": "Piattaforme che hanno restituito una foto del profilo.", "example": 0 }, "communication_breadth": { "type": "integer", "nullable": true, "description": "Piattaforme di comunicazione con presenza rilevata.", "example": 2 }, "digital_footprint_diversity": { "type": "integer", "nullable": true, "description": "Categorie di piattaforma distinte con presenza rilevata.", "example": 5 }, "digital_sophistication_index": { "type": "integer", "nullable": true, "description": "Indicatore composito di maturità digitale, 0-10.", "example": 5 }, "engagement_depth_index": { "type": "integer", "nullable": true, "description": "Indicatore della ricchezza del profilo, 0-10.", "example": 3 }, "subscription_affordability_index": { "type": "integer", "nullable": true, "description": "Mix di piattaforme gratuite rispetto a quelle a pagamento, 0-10.", "example": 2 }, "free_platforms": { "type": "integer", "nullable": true, "description": "Registrazioni su piattaforme gratuite.", "example": 4 }, "full_paid_platforms": { "type": "integer", "nullable": true, "description": "Registrazioni su piattaforme a pagamento completo.", "example": 0 }, "partial_paid_platforms": { "type": "integer", "nullable": true, "description": "Registrazioni su piattaforme freemium.", "example": 1 }, "whatsapp_profile_completeness": { "type": "string", "nullable": true, "enum": [ "Basic", "Partial", "Complete", "Not Present", null ], "description": "Completezza del profilo WhatsApp. Solo telefono; null per email.", "example": "Partial" }, "registered_platforms": { "type": "array", "description": "Piattaforme in cui la registrazione è confermata.", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "not_registered_platforms": { "type": "array", "description": "Piattaforme verificate con esito negativo.", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "categories": { "type": "object", "description": "Numero di registrazioni e percentuale per categoria di piattaforma.", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintCategorySummary" } }, "profiles": { "type": "object", "description": "Dettagli del profilo per piattaforma, indicizzati per piattaforma, quando la piattaforma li rende disponibili.", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintProfile" } } } }, "KYBRegistryAddress": { "type": "object", "description": "Un indirizzo indicato dal registro, nello stesso formato per ogni paese e fonte del registro. Tutte le chiavi sono sempre presenti; una parte non pubblicata dal registro è null.", "properties": { "type": { "type": "string", "nullable": true, "description": "Tipo di indirizzo in lettere minuscole: `registered` per la sede legale; altri tipi così come denominati dal registro (ad esempio `postal`, `office`). `null` quando il registro non specifica il tipo di indirizzo." }, "address": { "type": "string", "description": "L'indirizzo completo su una sola riga. Sempre presente per ogni indirizzo." }, "street": { "type": "string", "nullable": true, "description": "Via e numero civico." }, "city": { "type": "string", "nullable": true, "description": "Città o località." }, "postal_code": { "type": "string", "nullable": true, "description": "Codice postale." }, "region": { "type": "string", "nullable": true, "description": "Regione, stato o provincia." }, "country_code": { "type": "string", "nullable": true, "description": "Codice paese ISO 3166-1 alpha-2." }, "description": { "type": "string", "nullable": true, "description": "L'etichetta del registro per l'indirizzo, se fornita." } }, "required": [ "type", "address", "street", "city", "postal_code", "region", "country_code", "description" ] }, "KYBRegistryIndustry": { "type": "object", "description": "Un'attività con cui il registro classifica l'azienda, nello stesso formato per ogni paese e fonte del registro.", "properties": { "code": { "type": "string", "nullable": true, "description": "Codice di attività così come riportato dal registro (ad esempio `73110`)." }, "description": { "type": "string", "nullable": true, "description": "Etichetta dell'attività, se pubblicata dal registro." }, "scheme": { "type": "string", "nullable": true, "description": "Sistema di classificazione, un solo nome per sistema indipendentemente dalla fonte che lo ha segnalato: `UK SIC 2007`, `US SIC`, `NACE Rev. 2`, `NACE Rev. 2.1`, `NAF Rev. 2`, `CNAE`, `SBI`, `NOGA 2008`, `CAE Rev. 4`, `Canada SIC 1977`; gli altri sistemi nazionali mantengono il nome assegnato dal registro. Null quando il registro non specifica il sistema." }, "is_primary": { "type": "boolean", "description": "True per l'attività principale dell'azienda. Esattamente una voce è primaria quando l'elenco non è vuoto." } }, "required": [ "code", "description", "scheme", "is_primary" ] }, "KYBRegistryShareholding": { "type": "object", "nullable": true, "description": "La quota detenuta da un titolare, nello stesso formato per ogni paese e registro di origine. Null quando il registro non indica alcuna partecipazione. Una fascia (ad esempio il 25-50% di un PSC nel Regno Unito) non costituisce una partecipazione: `percentage` è null e la fascia rimane in `ownership_min_shares` / `ownership_max_shares`.", "properties": { "share_class": { "type": "string", "nullable": true, "description": "Classe o tipologia di quota, come denominata dal registro." }, "number_of_shares": { "type": "number", "nullable": true, "description": "Numero di azioni detenute." }, "currency": { "type": "string", "nullable": true, "description": "Valuta ISO 4217 dei valori sottostanti." }, "nominal_value": { "type": "number", "nullable": true, "description": "Valore nominale per azione." }, "total_value": { "type": "number", "nullable": true, "description": "Valore totale della partecipazione." }, "percentage": { "type": "number", "nullable": true, "description": "Quota esatta in percentuale, con quattro cifre decimali." } }, "required": [ "share_class", "number_of_shares", "currency", "nominal_value", "total_value", "percentage" ] }, "KYBRegistryOwnership": { "type": "object", "description": "L'esito del livello relativo all'assetto proprietario (Azionisti / UBO), nello stesso formato per ogni paese e fonte del registro.", "properties": { "status": { "type": "string", "nullable": true, "enum": [ "not_requested", "pending", "delivered", "not_held", "unavailable", null ], "description": "`delivered` quando il registro ha pubblicato l'assetto proprietario; `not_held` quando il registro delle imprese ha risposto e non elenca affatto l'azienda (vedi `unavailable_reason`); `unavailable` quando non ha fornito i dati sull'assetto proprietario per qualsiasi altro motivo (vedi `unavailable_reason`); `pending` mentre il registro lo sta ancora recuperando; `not_requested` per il livello Basic." }, "tier_requested": { "type": "string", "nullable": true, "enum": [ "basic", "shareholders", "ubo", null ], "description": "Il livello ordinato dal workflow." }, "tier_delivered": { "type": "string", "nullable": true, "enum": [ "basic", "shareholders", "ubo", null ], "description": "Il livello fornito dal registro (e fatturato). Una richiesta UBO con risposta contenente solo azionisti diretti è `shareholders`." }, "unavailable_reason": { "type": "string", "nullable": true, "enum": [ "no_owners_on_record", "no_natural_person_owner", "ownership_section_unavailable", "company_not_found", "ambiguous_company_match", "missing_registration_number", "entity_type_not_covered", "provider_unavailable", "other", null ], "description": "Il motivo per cui un livello dell'assetto proprietario richiesto non è stato consegnato. Null a meno che `status` non sia `unavailable` o `pending`." }, "direct_ownership_complete": { "type": "boolean", "nullable": true, "description": "True quando le quote dichiarate degli azionisti diretti ammontano al 100% (entro un punto percentuale dovuto all'arrotondamento); false quando non è così; null quando l'assetto proprietario non è stato fornito o una quota non è dichiarata." }, "unresolved": { "type": "array", "description": "Parti della catena proprietaria che il registro non è riuscito a risolvere, ad esempio nessuna struttura di gruppo registrata sopra i proprietari diretti.", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "section": { "type": "string", "nullable": true } } } } }, "required": [ "status", "tier_requested", "tier_delivered", "unavailable_reason", "direct_ownership_complete", "unresolved" ] }, "KYBRegistryData": { "type": "object", "nullable": true, "description": "Dettaglio normalizzato del registro delle imprese fornito da Didit per l'azienda: l'esito sull'assetto proprietario (`ownership_error`, `section_errors`, `ubo_resolution`, `lite_enrichment`), le correzioni apportate con update-data e i dati di registro privi di un campo dedicato. Non contiene mai il record grezzo della fonte del registro. Ogni chiave è opzionale e presente solo quando l'azienda dispone di un valore corrispondente; potrebbero essere aggiunte nuove chiavi. Fai riferimento ai campi canonici (`addresses`, `industries`, `ownership`, `beneficial_owners[].shareholding`) per tutti i dati coperti da essi.", "properties": { "company_name": { "type": "string", "description": "Ragione sociale corretta nella console." }, "registration_number": { "type": "string", "description": "Numero di registrazione indicato dal registro delle imprese o da una correzione nella console." }, "country_code": { "type": "string", "description": "Paese della registrazione come indicato dal registro o da una correzione della console." }, "region": { "type": "string", "description": "Regione o stato della registrazione." }, "incorporation_date": { "type": "string", "description": "Data di costituzione (ISO 8601)." }, "registration_date": { "type": "string", "description": "Data di registrazione (ISO 8601) quando il registro delle imprese ne indica una distinta rispetto alla data di costituzione." }, "dissolution_date": { "type": "string", "description": "Data di scioglimento (ISO 8601) quando indicata dal registro." }, "tax_number": { "type": "string", "description": "Identificativo fiscale." }, "vat_number": { "type": "string", "description": "Partita IVA." }, "legal_address": { "type": "string", "description": "Sede legale corretta nella console." }, "registered_address": { "type": "string", "description": "Sede legale così come riportata nel registro." }, "company_type": { "type": "string", "description": "Forma giuridica." }, "registry_status": { "type": "string", "description": "Stato dell'azienda presso il registro delle imprese." }, "verification_status": { "type": "string", "description": "Stato della verifica." }, "alternative_names": { "type": "string", "description": "Altre denominazioni con cui l'azienda opera o ha operato in passato." }, "nature_of_business": { "type": "string", "description": "Descrizione dell'attività." }, "registered_capital": { "type": "string", "description": "Capitale sociale come stampato." }, "registered_capital_amount": { "type": "string", "description": "Importo del capitale sociale, come stringa decimale." }, "registered_capital_currency": { "type": "string", "description": "Valuta del capitale sociale (ISO 4217)." }, "website": { "type": "string", "description": "Sito web." }, "email": { "type": "string", "description": "Email di contatto." }, "phone": { "type": "string", "description": "Telefono di contatto." }, "legal_entity_identifier": { "type": "string", "description": "Identificativo dell'entità giuridica (LEI)." }, "location_of_registration": { "type": "string", "description": "Luogo di registrazione." }, "control_scheme": { "type": "string", "description": "Modello di governance quando il registro lo espone." }, "ownership_error": { "type": "string", "enum": [ "no_owners_on_record", "no_natural_person_owner", "ownership_section_unavailable", "company_not_found", "ambiguous_company_match", "missing_registration_number", "entity_type_not_covered", "provider_unavailable", "other" ], "description": "Il motivo per cui un livello dell'assetto proprietario richiesto non è stato consegnato, con gli stessi codici di `ownership.unavailable_reason`. `no_owners_on_record` (il registro ha risposto e non indica alcun proprietario) e `ownership_section_unavailable` (il registro non ha restituito la sezione dell'assetto proprietario) sono esiti differenti." }, "section_errors": { "type": "object", "description": "Sezioni non restituite dal registro delle imprese, indicizzate per sezione (`officers`, `shareholders`, `group_structure`). Una sezione elencata qui non è mai stata consegnata: un elenco vuoto accanto ad essa non indica nulla sull'azienda.", "additionalProperties": { "$ref": "#/components/schemas/KYBRegistrySectionError" } }, "ubo_resolution": { "$ref": "#/components/schemas/KYBRegistryUboResolution" }, "lite_enrichment": { "$ref": "#/components/schemas/KYBRegistryLiteEnrichment" }, "registry_metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "I campi del registro relativi all'azienda, indicizzati con i nomi attribuiti dal registro, come valori semplici (record legacy). Sono inclusi solo i campi revisionati come fatti di registro." }, "registry_sources": { "type": "array", "description": "I registri ufficiali da cui è stato letto il record (record legacy). Le altre fonti non vengono indicate per nome.", "items": { "$ref": "#/components/schemas/KYBRegistrySource" } }, "previous_names": { "type": "array", "items": { "type": "string" }, "description": "Nomi con cui l'azienda era registrata in precedenza (record storici)." }, "parent_companies": { "type": "array", "items": { "type": "string" }, "description": "Società controllanti indicate dal registro (record legacy)." }, "documents_available": { "type": "integer", "description": "Quante pratiche offre il registro per l'azienda (record storici)." } } }, "KYBRegistryGroupCompany": { "type": "object", "description": "Un'azienda del gruppo societario, identificata tramite il registro delle imprese.", "properties": { "name": { "type": "string", "nullable": true, "description": "Ragione sociale." }, "country_code": { "type": "string", "nullable": true, "description": "Paese di registrazione." }, "registration_number": { "type": "string", "nullable": true, "description": "Numero di registrazione." } }, "required": [ "name", "country_code", "registration_number" ] }, "KYBRegistryUboResolution": { "type": "object", "description": "In che modo il livello UBO ha risalito la catena proprietaria a monte dell'azienda.", "properties": { "parent_chain": { "type": "array", "description": "Società controllanti, dalla controllante finale fino all'azienda.", "items": { "$ref": "#/components/schemas/KYBRegistryGroupCompany" } }, "subsidiaries": { "type": "array", "description": "Aziende direttamente controllate dall'azienda all'interno del suo gruppo societario.", "items": { "$ref": "#/components/schemas/KYBRegistryGroupCompany" } }, "unresolved": { "type": "array", "description": "Parti della catena che il registro non è riuscito a risolvere (le stesse voci di `ownership.unresolved`).", "items": { "type": "object", "properties": { "reason": { "type": "string", "description": "Il motivo, ad esempio `no_group_structure_on_record`, `selected_company_not_in_group_structure` o `section_error`." }, "section": { "type": "string", "nullable": true, "description": "La sezione interessata, ad esempio `group_structure`." } }, "required": [ "reason", "section" ] } } }, "required": [ "parent_chain", "subsidiaries", "unresolved" ] }, "KYBRegistrySectionError": { "type": "object", "description": "Una sezione non restituita dal registro.", "properties": { "status_code": { "type": "integer", "nullable": true, "description": "Lo stato restituito dal registro per la sezione." } }, "required": [ "status_code" ] }, "KYBRegistryLiteEnrichment": { "type": "object", "description": "Campi vuoti del profilo Lite compilati da un'altra delle fonti del registro del paese. La fonte non viene specificata.", "properties": { "fields": { "type": "array", "items": { "type": "string" }, "description": "I campi aziendali che sono stati compilati." }, "people_added": { "type": "integer", "description": "Quanti amministratori o titolari sono stati aggiunti." } }, "required": [ "fields", "people_added" ] }, "KYBRegistrySource": { "type": "object", "description": "Un registro ufficiale da cui è stato letto il record. Vengono indicati solo i registri governativi ufficiali, le autorità di regolamentazione e il sistema di identificazione ufficiale; qualsiasi altra fonte viene esclusa.", "properties": { "name": { "type": "string", "description": "Nome del registro, ad esempio `UK Companies House`." }, "source_type": { "type": "string", "enum": [ "official" ], "description": "Sempre `official`." } }, "required": [ "name", "source_type" ] }, "KYBOwnershipStructure": { "type": "object", "nullable": true, "description": "La cap table attestata dal registro, nello stato in cui si trovava al momento della consegna del livello sull'assetto proprietario: `shareholders` e `beneficial_owners` diretti. Null quando il registro non ha attestato alcun assetto proprietario. Non include mai le righe proprie della fonte del registro; consulta `company.beneficial_owners` e `company.ownership` per il record corrente.", "properties": { "shareholders": { "type": "array", "items": { "$ref": "#/components/schemas/KYBOwnershipStructureOwner" } }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/KYBOwnershipStructureOwner" } } }, "required": [ "shareholders", "beneficial_owners" ] }, "KYBOwnershipStructureOwner": { "type": "object", "description": "Un proprietario dello snapshot dell'assetto proprietario: la stessa identità del registro e la stessa quota di `company.beneficial_owners[]`, e la sua `shareholding` canonica.", "properties": { "name": { "type": "string", "nullable": true, "description": "Nome del titolare come indicato nel registro delle imprese." }, "first_name": { "type": "string", "nullable": true, "description": "Nome, per una persona fisica, quando indicato dal registro." }, "last_name": { "type": "string", "nullable": true, "description": "Cognome, per una persona fisica, quando indicato dal registro." }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita (ISO 8601) quando il registro la pubblica." }, "country_of_birth": { "type": "string", "nullable": true, "description": "Paese di nascita quando il registro lo pubblica." }, "company_name": { "type": "string", "nullable": true, "description": "Ragione sociale, per un proprietario persona giuridica." }, "registration_number": { "type": "string", "nullable": true, "description": "Numero di registrazione, per un titolare persona giuridica." }, "entity_type": { "type": "string", "nullable": true, "enum": [ "person", "company", null ], "description": "Indica se il titolare è una persona fisica o un'azienda." }, "nationality": { "type": "string", "nullable": true, "description": "Nazionalità, se indicata dal registro." }, "designation": { "type": "string", "nullable": true, "description": "La qualifica o il ruolo del proprietario così come riportato nel registro." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "`shareholder` per un titolare diretto, `ubo` per un titolare effettivo." }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferiore della quota di partecipazione, in percentuale (uguale al limite superiore per una quota esatta)." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superiore della quota, in percentuale." }, "voting_min_shares": { "type": "string", "nullable": true, "description": "Limite inferiore dei diritti di voto, in percentuale." }, "voting_max_shares": { "type": "string", "nullable": true, "description": "Limite superiore dei diritti di voto, in percentuale." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di inizio della partecipazione o dell'incarico (ISO 8601)." }, "is_active": { "type": "boolean", "nullable": true, "description": "False per un ex titolare." }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } }, "required": [ "name", "first_name", "last_name", "date_of_birth", "country_of_birth", "company_name", "registration_number", "entity_type", "nationality", "designation", "roles", "ownership_min_shares", "ownership_max_shares", "voting_min_shares", "voting_max_shares", "appointment_date", "is_active", "shareholding" ] }, "DigitalIdWalletApiWalletVerificationError": { "type": "object", "properties": { "error": { "type": "string", "description": "Codice stabile leggibile da macchina, es. wallet_unavailable." }, "detail": { "type": "string" } }, "required": [ "detail", "error" ] }, "DigitalIdWalletApiWalletVerificationStartForbidden": { "oneOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" }, { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } ] }, "DigitalIdWalletApiClientCredentialsForbiddenErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Forbidden - User doesn't have permission" } } }, "DigitalIdWalletApiWalletVerificationStartBadRequest": { "oneOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" }, { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationFieldErrors" } ] }, "DigitalIdWalletApiWalletVerificationFieldErrors": { "type": "object", "description": "Errori di validazione della richiesta: ciascun campo rifiutato con i relativi messaggi.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "DigitalIdWalletApiWalletVerificationResponse": { "type": "object", "description": "Una verifica del wallet autonoma, così come restituita da ciascun endpoint di wallet.", "properties": { "request_id": { "type": "string", "format": "uuid" }, "wallet_verification": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResult" }, "vendor_data": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "L'oggetto dei metadati inviato all'avvio, o null." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "created_at", "metadata", "request_id", "vendor_data", "wallet_verification" ] }, "DigitalIdWalletApiWalletVerificationResult": { "type": "object", "properties": { "wallet": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWallet" } ], "readOnly": true }, "country": { "type": "string" }, "status": { "type": "string", "description": "Non completato mentre è in sospeso, poi Approvata (verificata) o Rifiutata." }, "outcome": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResultOutcomeEnum" }, "error": { "type": "string", "nullable": true, "readOnly": true }, "interaction": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiInteractionEnum" } ], "readOnly": true }, "simulated": { "type": "boolean", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time" }, "next_action": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletNextAction" } ], "nullable": true, "readOnly": true }, "identity": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletIdentity" } ], "nullable": true, "readOnly": true }, "attributes": { "type": "object", "additionalProperties": {}, "nullable": true, "readOnly": true }, "level_of_assurance": { "type": "string", "nullable": true }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "signature_valid": { "type": "boolean", "nullable": true, "description": "True dopo che la firma della credenziale è stata verificata; null per una simulata." }, "credential_type": { "type": "string", "nullable": true } }, "required": [ "attributes", "country", "credential_type", "error", "expires_at", "identity", "interaction", "level_of_assurance", "next_action", "outcome", "signature_valid", "simulated", "status", "verified_at", "wallet" ] }, "DigitalIdWalletApiWalletIdentity": { "type": "object", "properties": { "full_name": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "nationality": { "type": "string", "nullable": true, "description": "Nazionalità ISO3, solo quando dichiarata dal wallet (mai dedotta)." }, "issuing_state": { "type": "string", "description": "Paese ISO3 il cui schema ha emesso l'identità." } }, "required": [ "date_of_birth", "first_name", "full_name", "issuing_state", "last_name", "nationality" ] }, "DigitalIdWalletApiWalletNextAction": { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletNextActionTypeEnum" } ], "description": "redirect: reindirizza il browser dell'utente a url. confirm_in_app: mostra verification_code all'utente, che verifica la corrispondenza con il codice nella propria app wallet e conferma lì; quindi esegui il polling. request_digital_credential: con un gesto dell'utente sull'origine da cui hai iniziato, richiedi al wallet con digital_credentials.request, quindi invia ciò che restituisce a POST .../verifications/{request_id}/response/.\n\n* `redirect` - redirect\n* `confirm_in_app` - confirm_in_app\n* `request_digital_credential` - request_digital_credential" }, "url": { "type": "string", "format": "uri", "description": "Solo redirect: dove l'utente effettua l'accesso con il wallet." }, "digital_credentials": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialsRequest" } ], "description": "Solo request_digital_credential: la richiesta da trasmettere al wallet." }, "verification_code": { "type": "string", "description": "Solo confirm_in_app: il codice di confronto a 4 cifre mostrato anche dall'app del wallet." }, "poll_interval_seconds": { "type": "integer", "description": "Solo confirm_in_app: la frequenza con cui chiamare POST .../verifications/{request_id}/poll/ per un feedback immediato. Didit esegue il polling degli accessi in sospeso anche in background, quindi il webhook segnala l'esito anche se non esegui il polling." } }, "required": [ "type" ] }, "DigitalIdWalletApiWalletNextActionTypeEnum": { "enum": [ "redirect", "confirm_in_app", "request_digital_credential" ], "type": "string", "description": "* `redirect` - redirect\n* `confirm_in_app` - confirm_in_app\n* `request_digital_credential` - request_digital_credential" }, "DigitalIdWalletApiInteractionEnum": { "enum": [ "redirect", "in_app", "digital_credentials" ], "type": "string", "description": "* `redirect` - redirect\n* `in_app` - in_app\n* `digital_credentials` - digital_credentials" }, "DigitalIdWalletApiWalletVerificationResultOutcomeEnum": { "enum": [ "pending", "verified", "cancelled", "timeout", "failed" ], "type": "string", "description": "* `pending` - In sospeso\n* `verified` - Verificata\n* `cancelled` - Annullata dall'utente\n* `timeout` - Scaduta per timeout\n* `failed` - Non riuscita" }, "DigitalIdWalletApiWallet": { "type": "object", "properties": { "id": { "type": "string", "description": "Id di catalogo del wallet, ad es. bankid_se." }, "name": { "type": "string" }, "issuing_authority": { "type": "string", "nullable": true } }, "required": [ "id", "issuing_authority", "name" ] }, "DigitalIdWalletApiEudiWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica EUDI Wallet (AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE, ISL, LIE, NOR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartCountryEnum" } ], "description": "Paese ISO 3166-1 alpha-3 dell'identità EUDI Wallet.\n\n* `AUT` - AUT\n* `BEL` - BEL\n* `BGR` - BGR\n* `HRV` - HRV\n* `CYP` - CYP\n* `CZE` - CZE\n* `DNK` - DNK\n* `EST` - EST\n* `FIN` - FIN\n* `FRA` - FRA\n* `DEU` - DEU\n* `GRC` - GRC\n* `HUN` - HUN\n* `IRL` - IRL\n* `ITA` - ITA\n* `LVA` - LVA\n* `LTU` - LTU\n* `LUX` - LUX\n* `MLT` - MLT\n* `NLD` - NLD\n* `POL` - POL\n* `PRT` - PRT\n* `ROU` - ROU\n* `SVK` - SVK\n* `SVN` - SVN\n* `ESP` - ESP\n* `SWE` - SWE\n* `ISL` - ISL\n* `LIE` - LIE\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "country", "return_url" ] }, "DigitalIdWalletApiDeviceEnum": { "enum": [ "same_device", "cross_device" ], "type": "string", "description": "* `same_device` - same_device\n* `cross_device` - cross_device" }, "DigitalIdWalletApiEudiWalletVerificationStartCountryEnum": { "enum": [ "AUT", "BEL", "BGR", "HRV", "CYP", "CZE", "DNK", "EST", "FIN", "FRA", "DEU", "GRC", "HUN", "IRL", "ITA", "LVA", "LTU", "LUX", "MLT", "NLD", "POL", "PRT", "ROU", "SVK", "SVN", "ESP", "SWE", "ISL", "LIE", "NOR" ], "type": "string", "description": "* `AUT` - AUT\n* `BEL` - BEL\n* `BGR` - BGR\n* `HRV` - HRV\n* `CYP` - CYP\n* `CZE` - CZE\n* `DNK` - DNK\n* `EST` - EST\n* `FIN` - FIN\n* `FRA` - FRA\n* `DEU` - DEU\n* `GRC` - GRC\n* `HUN` - HUN\n* `IRL` - IRL\n* `ITA` - ITA\n* `LVA` - LVA\n* `LTU` - LTU\n* `LUX` - LUX\n* `MLT` - MLT\n* `NLD` - NLD\n* `POL` - POL\n* `PRT` - PRT\n* `ROU` - ROU\n* `SVK` - SVK\n* `SVN` - SVN\n* `ESP` - ESP\n* `SWE` - SWE\n* `ISL` - ISL\n* `LIE` - LIE\n* `NOR` - NOR" }, "DigitalIdWalletApiConnectidWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica ConnectID (AUS).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum" } ], "default": "AUS", "description": "Paese ISO 3166-1 alpha-3 dell'identità ConnectID. Il valore predefinito è AUS, l'unico paese servito.\n\n* `AUS` - AUS" }, "authorisation_server_id": { "type": "string", "minLength": 1, "description": "ID del server di autorizzazione selezionato con il selettore bancario di ConnectID. In sandbox il valore predefinito è Mock Bank A.", "maxLength": 36 }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum": { "enum": [ "AUS" ], "type": "string", "description": "* `AUS` - AUS" }, "DigitalIdWalletApiAudkenniWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Auðkenni (ISL).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum" } ], "default": "ISL", "description": "Paese ISO 3166-1 alpha-3 dell'identità Auðkenni. Il valore predefinito è ISL, l'unico paese servito.\n\n* `ISL` - ISL" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum": { "enum": [ "ISL" ], "type": "string", "description": "* `ISL` - ISL" }, "DigitalIdWalletApiFranceconnectWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica FranceConnect (FRA).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum" } ], "default": "FRA", "description": "Paese ISO 3166-1 alpha-3 dell'identità FranceConnect. Il valore predefinito è FRA, l'unico paese servito.\n\n* `FRA` - FRA" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum": { "enum": [ "FRA" ], "type": "string", "description": "* `FRA` - FRA" }, "DigitalIdWalletApiDiiaWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Diia (UKR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum" } ], "default": "UKR", "description": "Paese ISO 3166-1 alpha-3 dell'identità Diia. Il valore predefinito è UKR, l'unico paese servito.\n\n* `UKR` - UKR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum": { "enum": [ "UKR" ], "type": "string", "description": "* `UKR` - UKR" }, "DigitalIdWalletApiMojeidWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica MojeID (CZE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryE2dEnum" } ], "default": "CZE", "description": "Paese ISO 3166-1 alpha-3 dell'identità MojeID. Il valore predefinito è CZE, l'unico paese servito.\n\n* `CZE` - CZE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountryE2dEnum": { "enum": [ "CZE" ], "type": "string", "description": "* `CZE` - CZE" }, "DigitalIdWalletApiBankidCzWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Bank iD (CZE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryE2dEnum" } ], "default": "CZE", "description": "Paese ISO 3166-1 alpha-3 dell'identità Bank iD. Il valore predefinito è CZE, l'unico paese servito.\n\n* `CZE` - CZE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica eParaksts mobile (LVA).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum" } ], "default": "LVA", "description": "Paese ISO 3166-1 alpha-3 dell'identità mobile eParaksts. Il valore predefinito è LVA, l'unico paese servito.\n\n* `LVA` - LVA" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum": { "enum": [ "LVA" ], "type": "string", "description": "* `LVA` - LVA" }, "DigitalIdWalletApiIdcardEeWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica con carta d'identità estone (EST).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum" } ], "default": "EST", "description": "Paese ISO 3166-1 alpha-3 dell'identità con carta d'identità estone. Il valore predefinito è EST, l'unico paese servito.\n\n* `EST` - EST" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum": { "enum": [ "EST" ], "type": "string", "description": "* `EST` - EST" }, "DigitalIdWalletApiMobileIdWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Mobile-ID (EST, LTU).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum" } ], "description": "Paese ISO 3166-1 alpha-3 dell'identità Mobile-ID.\n\n* `EST` - EST\n* `LTU` - LTU" }, "personal_code": { "type": "string", "minLength": 1, "description": "Il codice di identificazione personale nazionale dell'utente. È associato all'app Mobile-ID dell'utente; l'utente conferma il codice di controllo e inserisce il proprio PIN nell'app. Non raccogliere mai il PIN.", "pattern": "^[0-9-]{6,20}$" }, "phone_number": { "type": "string", "minLength": 1, "description": "Il numero di telefono Mobile-ID in formato E.164 (+372... o +370...).", "maxLength": 16 } }, "required": [ "country", "personal_code", "phone_number" ] }, "DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum": { "enum": [ "EST", "LTU" ], "type": "string", "description": "* `EST` - EST\n* `LTU` - LTU" }, "DigitalIdWalletApiSmartIdWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Smart-ID (EST, LVA, LTU, BEL).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum" } ], "description": "Paese ISO 3166-1 alpha-3 dell'identità Smart-ID.\n\n* `EST` - EST\n* `LVA` - LVA\n* `LTU` - LTU\n* `BEL` - BEL" }, "personal_code": { "type": "string", "minLength": 1, "description": "Il codice di identificazione personale nazionale dell'utente. È associato all'app Smart-ID dell'utente; l'utente conferma il codice di controllo e inserisce il proprio PIN nell'app. Non raccogliere mai il PIN.", "pattern": "^[0-9-]{6,20}$" } }, "required": [ "country", "personal_code" ] }, "DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum": { "enum": [ "EST", "LVA", "LTU", "BEL" ], "type": "string", "description": "* `EST` - EST\n* `LVA` - LVA\n* `LTU` - LTU\n* `BEL` - BEL" }, "DigitalIdWalletApiGovukWalletWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica GOV.UK Wallet (GBR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountry520Enum" } ], "default": "GBR", "description": "Paese ISO 3166-1 alpha-3 dell'identità GOV.UK Wallet. Il valore predefinito è GBR, l'unico paese servito.\n\n* `GBR` - GBR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountry520Enum": { "enum": [ "GBR" ], "type": "string", "description": "* `GBR` - GBR" }, "DigitalIdWalletApiOneidWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica OneID (GBR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountry520Enum" } ], "default": "GBR", "description": "Paese ISO 3166-1 alpha-3 dell'identità OneID. Il valore predefinito è GBR, l'unico paese servito.\n\n* `GBR` - GBR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiGovbrWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica gov.br (BRA).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum" } ], "default": "BRA", "description": "Paese ISO 3166-1 alpha-3 dell'identità gov.br. Il valore predefinito è BRA, l'unico paese servito.\n\n* `BRA` - BRA" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum": { "enum": [ "BRA" ], "type": "string", "description": "* `BRA` - BRA" }, "DigitalIdWalletApiUaePassWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica UAE PASS (ARE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum" } ], "default": "ARE", "description": "Paese ISO 3166-1 alpha-3 dell'identità UAE PASS. Il valore predefinito è ARE, l'unico paese servito.\n\n* `ARE` - ARE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum": { "enum": [ "ARE" ], "type": "string", "description": "* `ARE` - ARE" }, "DigitalIdWalletApiFrejaidWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Freja eID (SWE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryEe9Enum" } ], "default": "SWE", "description": "Paese ISO 3166-1 alpha-3 dell'identità Freja eID. Il valore predefinito è SWE, l'unico paese servito.\n\n* `SWE` - SWE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountryEe9Enum": { "enum": [ "SWE" ], "type": "string", "description": "* `SWE` - SWE" }, "DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Personalausweis (DEU).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum" } ], "default": "DEU", "description": "Paese ISO 3166-1 alpha-3 dell'identità Personalausweis. Il valore predefinito è DEU, l'unico paese servito.\n\n* `DEU` - DEU" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum": { "enum": [ "DEU" ], "type": "string", "description": "* `DEU` - DEU" }, "DigitalIdWalletApiFtnWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Finnish Trust Network (FIN).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartCountryEnum" } ], "default": "FIN", "description": "Paese ISO 3166-1 alpha-3 dell'identità Finnish Trust Network. Il valore predefinito è FIN, l'unico paese servito.\n\n* `FIN` - FIN" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiFtnWalletVerificationStartCountryEnum": { "enum": [ "FIN" ], "type": "string", "description": "* `FIN` - FIN" }, "DigitalIdWalletApiIdinWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica iDIN (NLD).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartCountryEnum" } ], "default": "NLD", "description": "Paese ISO 3166-1 alpha-3 dell'identità iDIN. Il valore predefinito è NLD, l'unico paese servito.\n\n* `NLD` - NLD" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiIdinWalletVerificationStartCountryEnum": { "enum": [ "NLD" ], "type": "string", "description": "* `NLD` - NLD" }, "DigitalIdWalletApiItsmeWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica itsme (BEL, LUX, NLD).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum" } ], "description": "Paese ISO 3166-1 alpha-3 dell'identità itsme.\n\n* `BEL` - BEL\n* `LUX` - LUX\n* `NLD` - NLD" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "country", "return_url" ] }, "DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum": { "enum": [ "BEL", "LUX", "NLD" ], "type": "string", "description": "* `BEL` - BEL\n* `LUX` - LUX\n* `NLD` - NLD" }, "DigitalIdWalletApiBuypassWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Buypass ID (NOR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryAfcEnum" } ], "default": "NOR", "description": "Paese ISO 3166-1 alpha-3 dell'identità Buypass ID. Il valore predefinito è NOR, l'unico paese servito.\n\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountryAfcEnum": { "enum": [ "NOR" ], "type": "string", "description": "* `NOR` - NOR" }, "DigitalIdWalletApiVippsWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Vipps (NOR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryAfcEnum" } ], "default": "NOR", "description": "Paese ISO 3166-1 alpha-3 dell'identità Vipps. Il valore predefinito è NOR, l'unico paese servito.\n\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiBankidNoWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica BankID (NOR).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryAfcEnum" } ], "default": "NOR", "description": "Paese ISO 3166-1 alpha-3 dell'identità BankID. Il valore predefinito è NOR, l'unico paese servito.\n\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiBankidSeWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica BankID (SWE).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryEe9Enum" } ], "default": "SWE", "description": "Paese ISO 3166-1 alpha-3 dell'identità BankID. Il valore predefinito è SWE, l'unico paese servito.\n\n* `SWE` - SWE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiMitidWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica MitID (DNK).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartCountryEnum" } ], "default": "DNK", "description": "Paese ISO 3166-1 alpha-3 dell'identità MitID. Il valore predefinito è DNK, l'unico paese servito.\n\n* `DNK` - DNK" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "URL https a cui ritorna il browser dell'utente dopo il wallet, con request_id e result aggiunti in coda. Il rispettivo host deve essere registrato in allowed_return_hosts dell'applicazione (o corrispondere al suo dominio white label). Non fidarti mai di result da solo: leggi l'esito con GET .../verifications/{request_id}/ o tramite il webhook.", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "same_device quando l'utente effettua l'accesso sul dispositivo che mostra la tua pagina, cross_device quando ne utilizza un altro (es. il codice QR di BankID).\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiMitidWalletVerificationStartCountryEnum": { "enum": [ "DNK" ], "type": "string", "description": "* `DNK` - DNK" }, "DigitalIdWalletApiWalletCatalogResponse": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletCatalogEntry" } } }, "required": [ "wallets" ] }, "DigitalIdWalletApiWalletCatalogEntry": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string", "description": "L'endpoint di avvio del wallet." }, "countries": { "type": "array", "items": { "type": "string" } }, "issuing_authority": { "type": "string" }, "level_of_assurance": { "type": "string", "nullable": true }, "interaction": { "$ref": "#/components/schemas/DigitalIdWalletApiInteractionEnum" }, "required_fields": { "type": "array", "items": { "type": "string" } }, "available": { "type": "boolean", "description": "Indica se questa applicazione può avviarlo in questo ambiente in questo momento. L'inclusione nell'elenco non implica che sia attivo." } }, "required": [ "available", "countries", "id", "interaction", "issuing_authority", "level_of_assurance", "name", "path", "required_fields" ] }, "CaseDuplicateCaseDuplicate": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "case_number": { "type": "string", "nullable": true, "maxLength": 32 }, "title": { "type": "string", "maxLength": 255 }, "status": { "$ref": "#/components/schemas/CaseDuplicateStatusEnum" }, "priority": { "$ref": "#/components/schemas/CaseDuplicatePriorityEnum" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "title", "uuid" ] }, "CaseDuplicateCaseDuplicatePage": { "type": "object", "properties": { "count": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicate" } } }, "required": [ "count", "next_offset", "results" ] }, "RoutingPublicationPolicyDraftResponse": { "type": "object", "properties": { "draft": { "allOf": [ { "$ref": "#/components/schemas/RoutingPublicationPolicyDraft" } ], "nullable": true } }, "required": [ "draft" ] }, "RoutingPublicationPolicyDraftWriteRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true }, "changes": { "type": "object", "additionalProperties": {} } }, "required": [ "changes", "expected_revision", "expected_version" ] }, "CasePublicationPolicyDraft": { "type": "object", "properties": { "revision": { "type": "string", "format": "uuid" }, "base_version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "changes": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "base_version", "updated_at" ] }, "CasePublicationPolicyDraftPreconditionRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "expected_revision", "expected_version" ] }, "CaseCollaborationCaseNote": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "comment": { "type": "string" }, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 255 }, "actor_name": { "type": "string", "nullable": true, "maxLength": 255 }, "mentioned_emails": {}, "is_internal": { "type": "boolean" }, "attachments": {}, "tags": {}, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "reply_to": { "allOf": [ { "$ref": "#/components/schemas/CaseCollaborationCaseNoteReply" } ], "nullable": true, "readOnly": true }, "is_pinned": { "type": "boolean" }, "client_reference": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "comment", "created_at", "reply_to", "uuid" ] }, "CustomerMessagingPaginatedCaseRequestList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" } } } }, "FraudCheckResponse": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid", "description": "Sessione di verifica nativa creata per questo controllo." }, "client_reference": { "type": "string", "nullable": true }, "processing_status": { "$ref": "#/components/schemas/FraudProcessingStatusEnum" }, "profile_id": { "type": "string" }, "profile_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckInput" } }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckModuleReport" } }, "attribute_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "compound_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "risk": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckRisk" } }, "network": { "type": "object", "additionalProperties": {} }, "enrichment": { "type": "object", "additionalProperties": {} }, "identity_relationship": { "allOf": [ { "$ref": "#/components/schemas/FraudCheckIdentityRelationship" } ], "nullable": true }, "recommendation": { "$ref": "#/components/schemas/FraudRecommendationEnum" }, "next_action": { "$ref": "#/components/schemas/FraudNextActionEnum" }, "decision_reasons": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "object", "additionalProperties": {} }, "usage": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "vendor_data": { "type": "string", "nullable": true }, "metadata": { "nullable": true } }, "required": [ "attribute_evidence", "check_id", "client_reference", "completed_at", "compound_evidence", "coverage", "created_at", "decision_reasons", "inputs", "modules", "network", "next_action", "processing_status", "profile_id", "profile_version", "recommendation", "risk", "usage" ] }, "CaseReviewTeam": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeamMember" }, "maxItems": 250 }, "is_active": { "type": "boolean" }, "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "CaseActionCaseEntityActionRequest": { "type": "object", "properties": { "client_reference": { "type": "string", "format": "uuid" }, "retry": { "type": "boolean", "default": false }, "action": { "$ref": "#/components/schemas/CaseActionActionEnum" }, "status": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "note": { "type": "string", "nullable": true } }, "required": [ "action" ] }, "RoutingPublicationPaginatedPolicyRevisionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingPublicationPolicyRevision" } } } }, "FraudRecommendationEnum": { "enum": [ "approve", "review", "reject" ], "type": "string", "description": "* `approve` - Approva\n* `review` - Revisiona\n* `reject` - Rifiuta" }, "CustomerMessagingCaseRequestPreviewResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "recipient": { "type": "string", "format": "email" }, "sender": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string" }, "requires_user_action": { "type": "boolean" }, "preview_token": { "type": "string" } }, "required": [ "expires_at", "html", "preview_token", "recipient", "request_id", "requires_user_action", "sender", "subject" ] }, "CustomerMessagingCaseCustomerResponseRequest": { "type": "object", "properties": { "full_name": { "type": "string", "minLength": 1, "maxLength": 512 }, "date_of_birth": { "type": "string", "format": "date" }, "file": { "type": "string", "format": "binary", "writeOnly": true } } }, "CaseCollaborationCaseNoteReply": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "actor_name": { "type": "string", "nullable": true }, "actor_email": { "type": "string", "format": "email", "nullable": true }, "comment": { "type": "string", "maxLength": 300 } }, "required": [ "actor_email", "actor_name", "comment", "uuid" ] }, "FraudCheckModuleReport": { "type": "object", "properties": { "module": { "$ref": "#/components/schemas/FraudExcludeEnum" }, "status": { "$ref": "#/components/schemas/FraudStatusEnum" }, "reason": { "type": "string", "nullable": true }, "latency_ms": { "type": "integer" }, "freshness": { "type": "string", "nullable": true }, "billable_units": { "type": "integer" } }, "required": [ "billable_units", "freshness", "latency_ms", "module", "reason", "status" ] }, "CaseDuplicateEntityTypeEnum": { "enum": [ "session", "business_session", "transaction" ], "type": "string", "description": "* `session` - Sessione\n* `business_session` - Sessione aziendale\n* `transaction` - Transazione" }, "FraudClientCredentialsErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Authentication failed: Invalid client access token." } } }, "FraudAvailabilityEnum": { "enum": [ "available", "not_requested", "no_reference", "insufficient_history", "unsupported_region", "source_unavailable" ], "type": "string", "description": "* `available` - Disponibile\n* `not_requested` - Non richiesto\n* `no_reference` - Nessun riferimento\n* `insufficient_history` - Cronologia insufficiente\n* `unsupported_region` - Area geografica non supportata\n* `source_unavailable` - Fonte non disponibile" }, "CasePublicationPolicyDraftResponse": { "type": "object", "properties": { "draft": { "allOf": [ { "$ref": "#/components/schemas/CasePublicationPolicyDraft" } ], "nullable": true } }, "required": [ "draft" ] }, "FraudCheckAttributesRequest": { "type": "object", "description": "Attributi corroboranti. Tutti facoltativi; ampliano la copertura dei moduli.", "properties": { "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "full_name": { "type": "string", "maxLength": 256 }, "date_of_birth": { "type": "string", "format": "date" }, "nationality": { "type": "string", "maxLength": 3 }, "gender": { "type": "string", "maxLength": 16 }, "address": { "type": "string", "maxLength": 512 }, "city": { "type": "string", "maxLength": 128 }, "state": { "type": "string", "maxLength": 128 }, "postal_code": { "type": "string", "maxLength": 32 } } }, "NetworkNote": { "type": "object", "required": [ "uuid", "actor_email", "comment", "client_reference", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "actor_email": { "type": "string", "format": "email", "readOnly": true, "description": "Autore autenticato, assegnato dal server." }, "comment": { "type": "string", "minLength": 1, "maxLength": 10000 }, "client_reference": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "CaseActionEntityTypeEnum": { "enum": [ "user", "business" ], "type": "string", "description": "* `user` - user\n* `business` - business" }, "CaseRoutingCondition": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "source", "priority", "tags" ] }, "operator": { "type": "string", "enum": [ "equals", "in", "contains" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "field", "operator", "value" ], "description": "Origine e priorità supportano equals o in con i valori supportati. I tag supportano contains con un tag non vuoto." }, "RoutingPublicationPolicyRevision": { "type": "object", "properties": { "version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "snapshot": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "published_at", "snapshot", "version" ] }, "CasePublicationPolicyRevision": { "type": "object", "properties": { "version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "snapshot": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "published_at", "snapshot", "version" ] }, "FraudCheckIdentityRelationship": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/FraudResultEnum" }, "reference_type": { "type": "string" }, "country": { "type": "string" }, "availability": { "$ref": "#/components/schemas/FraudAvailabilityEnum" }, "reason_codes": { "type": "array", "items": { "type": "string" } } }, "required": [ "availability", "country", "reason_codes", "reference_type", "result" ] }, "CasePublicationPaginatedPolicyRevisionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CasePublicationPolicyRevision" } } } }, "CaseDuplicateBlankEnum": { "enum": [ "" ] }, "FraudCheckPlan": { "type": "object", "properties": { "profile_id": { "type": "string" }, "profile_version": { "type": "string" }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckPlannedModule" } }, "estimated_price": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "is_sandbox": { "type": "boolean" }, "can_afford": { "type": "boolean" } }, "required": [ "can_afford", "currency", "estimated_price", "is_sandbox", "modules", "profile_id", "profile_version" ] }, "CaseReviewTeamUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeamMember" }, "maxItems": 250 }, "is_active": { "type": "boolean" } } }, "RoutingPublicationPolicyDraft": { "type": "object", "properties": { "revision": { "type": "string", "format": "uuid" }, "base_version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "changes": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "base_version", "updated_at" ] }, "FraudCheckRequestRequest": { "type": "object", "properties": { "client_reference": { "type": "string", "minLength": 1, "description": "Il tuo riferimento per questo controllo. Funziona anche come chiave di idempotenza: riutilizzarlo con lo stesso corpo della richiesta restituisce il controllo originale senza eseguire né fatturare nuovamente i moduli; riutilizzarlo con un corpo della richiesta diverso restituisce 409.", "maxLength": 255 }, "profile": { "type": "string", "minLength": 1, "default": "standard", "description": "ID del profilo di orchestrazione. Il valore predefinito è il profilo Didit `standard`.", "maxLength": 64 }, "profile_version": { "type": "string", "minLength": 1, "description": "Fissa una versione bloccata del profilo. Il valore predefinito è la versione corrente del profilo.", "maxLength": 32 }, "subject": { "$ref": "#/components/schemas/FraudCheckSubjectRequest" }, "context": { "$ref": "#/components/schemas/FraudCheckContextRequest" }, "checks": { "$ref": "#/components/schemas/FraudCheckModuleSelectionRequest" }, "vendor_data": { "type": "string", "maxLength": 1000 }, "metadata": {} }, "required": [ "subject" ] }, "CaseDuplicateCaseSubjectInputRequest": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CaseDuplicateTypeEnum" }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "type", "uuid" ] }, "CaseReviewTeamMember": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "availability": { "type": "string", "enum": [ "available", "unavailable" ], "default": "available" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "available_from": { "type": "string", "format": "date-time", "nullable": true }, "available_until": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "user_id" ] }, "CaseRoutingPreviewRequest": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "default": "MEDIUM" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 50 }, "rule_uuid": { "type": "string", "format": "uuid" }, "draft": { "$ref": "#/components/schemas/CaseRoutingRuleCreate" } }, "required": [ "source" ] }, "FraudExcludeEnum": { "enum": [ "normalization", "email_risk", "email_social", "phone_social", "phone_risk", "ip_risk", "database_validation", "networks_same_org", "networks_cross_org", "biometric_identity" ], "type": "string", "description": "* `normalization` - Normalizzazione\n* `email_risk` - Rischio email\n* `email_social` - Socialità dell'email\n* `phone_social` - Socialità del telefono\n* `phone_risk` - Rischio telefono\n* `ip_risk` - Rischio IP\n* `database_validation` - Validazione su database\n* `networks_same_org` - Reti della stessa organizzazione\n* `networks_cross_org` - Reti tra organizzazioni diverse\n* `biometric_identity` - Identità biometrica" }, "CaseDuplicateCaseLinkCreateRequest": { "type": "object", "properties": { "entity_type": { "$ref": "#/components/schemas/CaseDuplicateEntityTypeEnum" }, "entity_uuid": { "type": "string", "format": "uuid" } }, "required": [ "entity_type", "entity_uuid" ] }, "CaseDuplicateStatusEnum": { "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ], "type": "string", "description": "* `OPEN` - Aperto\n* `AWAITING_USER` - In attesa dell'utente\n* `RESOLVED` - Risolto" }, "FraudBandEnum": { "enum": [ "low", "medium", "high", "unknown" ], "type": "string", "description": "* `low` - Basso\n* `medium` - Medio\n* `high` - Alto\n* `unknown` - Sconosciuto" }, "CaseDuplicatePriorityEnum": { "enum": [ "LOW", "MEDIUM", "HIGH" ], "type": "string", "description": "* `LOW` - Basso\n* `MEDIUM` - Medio\n* `HIGH` - Alto" }, "FraudStatusEnum": { "enum": [ "planned", "completed", "skipped", "failed" ], "type": "string", "description": "* `planned` - Pianificato\n* `completed` - Completato\n* `skipped` - Saltato\n* `failed` - Non riuscito" }, "FraudCheckInput": { "type": "object", "properties": { "reference": { "type": "string", "description": "Handle oscurato per l'identificatore inviato." }, "type": { "$ref": "#/components/schemas/FraudTypeEnum" }, "namespace": { "type": "object", "additionalProperties": {} }, "quality": { "type": "string" }, "normalization": { "type": "object", "additionalProperties": {} }, "availability": { "$ref": "#/components/schemas/FraudAvailabilityEnum" } }, "required": [ "availability", "namespace", "normalization", "quality", "reference", "type" ] }, "CustomerMessagingPurposesEnum": { "enum": [ "identity_document", "proof_of_address", "business_document", "confirm_details", "review_in_progress" ], "type": "string", "description": "* `identity_document` - identity_document\n* `proof_of_address` - proof_of_address\n* `business_document` - business_document\n* `confirm_details` - confirm_details\n* `review_in_progress` - review_in_progress" }, "FraudTypeEnum": { "enum": [ "email", "phone", "national_id", "tax_number", "passport_number", "driving_licence_number", "residence_permit_number", "voter_id", "external_id" ], "type": "string", "description": "* `email` - Email\n* `phone` - Telefono\n* `national_id` - Documento d'identità nazionale\n* `tax_number` - Numero di identificazione fiscale\n* `passport_number` - Numero di passaporto\n* `driving_licence_number` - Numero della patente di guida\n* `residence_permit_number` - Numero del permesso di soggiorno\n* `voter_id` - Tessera elettorale\n* `external_id` - ID esterno" }, "CaseDuplicateCaseSubjectInput": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CaseDuplicateTypeEnum" }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "type", "uuid" ] }, "CaseReviewTeamCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeamMember" }, "maxItems": 250 }, "is_active": { "type": "boolean" } }, "required": [ "name", "members" ] }, "CaseDuplicateCaseDuplicateQueryRequest": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/CaseDuplicateCaseSubjectInputRequest" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/CaseDuplicateCaseLinkCreateRequest" } }, "offset": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0 } } }, "CaseDuplicateResolutionEnum": { "enum": [ "FALSE_POSITIVE", "VALID_THREAT" ], "type": "string", "description": "* `FALSE_POSITIVE` - Falso positivo\n* `VALID_THREAT` - Minaccia valida" }, "CasePublicationPolicyDraftWriteRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true }, "changes": { "type": "object", "additionalProperties": {} } }, "required": [ "changes", "expected_revision", "expected_version" ] }, "FraudCheckSubjectRequest": { "type": "object", "properties": { "selfie": { "type": "string", "minLength": 1, "description": "Selfie Base64 in formato JPEG, PNG o WebP, fino a 6 MB. Nessuna immagine di riferimento o URL.", "maxLength": 8388672 }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckIdentifierRequest" }, "description": "Uno o più identificatori tipizzati. Uno è sufficiente.", "maxItems": 10, "minItems": 1 }, "attributes": { "$ref": "#/components/schemas/FraudCheckAttributesRequest" } }, "required": [ "identifiers" ] }, "RoutingPublicationRoutingCondition": { "type": "object", "properties": { "field": { "$ref": "#/components/schemas/RoutingPublicationFieldEnum" }, "operator": { "$ref": "#/components/schemas/RoutingPublicationOperatorEnum" }, "value": {} }, "required": [ "field", "operator", "value" ] }, "CaseActionCaseActionReceipt": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "client_reference": { "type": "string", "format": "uuid" }, "action": { "type": "string", "maxLength": 32 }, "status": { "$ref": "#/components/schemas/CaseActionStatusEnum" }, "result": {}, "error": { "type": "string", "maxLength": 255 }, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "attempts": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "action", "client_reference", "created_at", "status", "updated_at", "uuid" ] }, "FraudCheckContextRequest": { "type": "object", "properties": { "ip_address": { "type": "string", "minLength": 1 }, "user_agent": { "type": "string", "maxLength": 512 }, "country": { "type": "string", "description": "Paese in cui il soggetto dichiara di trovarsi. Solo contestuale - mai una prova della titolarità dell'identità.", "maxLength": 3 }, "purpose": { "type": "string", "maxLength": 128 }, "consent_obtained": { "type": "boolean" } } }, "CustomerMessagingCaseCustomerResponseResult": { "type": "object", "properties": { "responded_at": { "type": "string", "format": "date-time" } }, "required": [ "responded_at" ] }, "CustomerMessagingCaseRequestContact": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "verified_at": { "type": "string", "format": "date-time" } }, "required": [ "email", "uuid", "verified_at" ] }, "FraudClientCredentialsForbiddenErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Forbidden - User doesn't have permission" } } }, "CasePublicationAssignmentMethodEnum": { "enum": [ "MANUAL", "AUTOMATIC" ], "type": "string", "description": "* `MANUAL` - Manuale\n* `AUTOMATIC` - Automatico" }, "CaseDuplicateNullEnum": { "enum": [ null ] }, "CustomerMessagingLanguageEnum": { "enum": [ "en", "es", "pt" ], "type": "string", "description": "* `en` - en\n* `es` - es\n* `pt` - pt" }, "CaseDuplicateCaseFraudSourceContextRequest": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "source_section": { "type": "string", "minLength": 1, "pattern": "^[A-Z][A-Z0-9_:-]{0,63}$" } }, "required": [ "check_id", "request_id", "source_section" ] }, "FraudCheckPlannedModule": { "type": "object", "properties": { "module": { "$ref": "#/components/schemas/FraudExcludeEnum" }, "available": { "type": "boolean" }, "availability_reason": { "type": "string", "nullable": true }, "will_run": { "type": "boolean" }, "selection_reason": { "type": "string", "nullable": true }, "estimated_price": { "type": "string", "nullable": true } }, "required": [ "availability_reason", "available", "estimated_price", "module", "selection_reason", "will_run" ] }, "CustomerMessagingCaseRequestOptions": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestContact" } }, "purposes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingPurposesEnum" } }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingLanguagesEnum" } } }, "required": [ "contacts", "languages", "purposes" ] }, "CaseCollaborationPaginatedCaseNoteList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } } }, "FraudProcessingStatusEnum": { "enum": [ "pending", "running", "completed", "failed" ], "type": "string", "description": "* `pending` - In sospeso\n* `running` - In esecuzione\n* `completed` - Completato\n* `failed` - Non riuscito" }, "CasePublicationCaseBlueprint": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "nullable": true }, "assignment_method": { "$ref": "#/components/schemas/CasePublicationAssignmentMethodEnum" }, "assignee_pool": {}, "max_active_cases": { "type": "integer", "maximum": 2147483647, "minimum": 0, "nullable": true }, "escalation_enabled": { "type": "boolean" }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "escalation_blueprint_name": { "type": "string", "readOnly": true }, "transfer_enabled": { "type": "boolean" }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "four_eyes_checker_blueprint_name": { "type": "string", "readOnly": true }, "require_resolution_note": { "type": "boolean" }, "content_config": {}, "version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "default_deadline_hours": { "type": "integer", "maximum": 2147483647, "minimum": 0, "nullable": true }, "is_active": { "type": "boolean" }, "preset_key": { "type": "string", "nullable": true, "maxLength": 64 }, "creation_sources": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "readOnly": true }, "receives_escalation_from": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "creation_sources", "escalation_blueprint_name", "four_eyes_checker_blueprint_name", "name", "receives_escalation_from", "updated_at", "uuid" ] }, "CaseRoutingRuleUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingCondition" }, "maxItems": 20 }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "team": { "type": "string", "format": "uuid", "nullable": true }, "is_active": { "type": "boolean" }, "expected_version": { "type": "integer", "minimum": 1, "writeOnly": true, "description": "Versione aperta dall'editor. Se fornita, le scritture non aggiornate restituiscono 409 senza modificare la regola." } } }, "CustomerMessagingCaseRequestPreviewRequest": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "purpose": { "$ref": "#/components/schemas/CustomerMessagingPurposeEnum" }, "language": { "allOf": [ { "$ref": "#/components/schemas/CustomerMessagingLanguageEnum" } ], "default": "en" } }, "required": [ "contact_id", "purpose" ] }, "CaseDuplicateCaseFraudSourceContext": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "source_section": { "type": "string", "pattern": "^[A-Z][A-Z0-9_:-]{0,63}$" } }, "required": [ "check_id", "request_id", "source_section" ] }, "RoutingPublicationOperatorEnum": { "enum": [ "equals", "in", "contains" ], "type": "string", "description": "* `equals` - uguale a\n* `in` - in\n* `contains` - contiene" }, "CaseRoutingPreview": { "type": "object", "properties": { "rule_uuid": { "type": "string", "format": "uuid", "nullable": true }, "rule_name": { "type": "string", "nullable": true }, "rule_version": { "type": "integer", "nullable": true }, "blueprint_uuid": { "type": "string", "format": "uuid", "nullable": true }, "team_uuid": { "type": "string", "format": "uuid", "nullable": true }, "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true }, "reason": { "type": "string" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "eligible": { "type": "boolean" }, "active_cases": { "type": "integer", "nullable": true }, "reason": { "type": "string", "nullable": true } } } }, "matched_rules": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "priority": { "type": "integer" } } } } } }, "FraudDimensionEnum": { "enum": [ "identity", "contact", "device_network", "behavioral", "fraud_network" ], "type": "string", "description": "* `identity` - Identità\n* `contact` - Contatto\n* `device_network` - Rete e dispositivo\n* `behavioral` - Comportamentale\n* `fraud_network` - Rete di frode" }, "FraudBadRequestErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Bad Request - Invalid request data" } } }, "FraudNextActionEnum": { "enum": [ "none", "manual_review", "step_up", "resubmit_capture" ], "type": "string", "description": "* `none` - Nessuno\n* `manual_review` - Revisione manuale\n* `step_up` - Passaggio a un livello superiore\n* `resubmit_capture` - Invia nuovamente l'acquisizione" }, "RoutingPublicationPolicyDraftPreconditionRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "expected_revision", "expected_version" ] }, "FraudCheckRisk": { "type": "object", "properties": { "dimension": { "$ref": "#/components/schemas/FraudDimensionEnum" }, "score": { "type": "integer", "nullable": true }, "band": { "$ref": "#/components/schemas/FraudBandEnum" }, "availability": { "$ref": "#/components/schemas/FraudAvailabilityEnum" }, "requested_but_unavailable": { "type": "boolean", "description": "True quando la richiesta ha fornito tutto ciò di cui questa dimensione aveva bisogno e la piattaforma non è comunque riuscita a elaborare una risposta. Un controllo del genere non viene mai raccomandato per l'approvazione in base alle dimensioni che hanno fornito una risposta." }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "evidence_indexes": { "type": "array", "items": { "type": "integer" } } }, "required": [ "availability", "band", "dimension", "evidence_indexes", "reason_codes", "requested_but_unavailable", "score" ] }, "CaseDuplicateSourceEnum": { "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ], "type": "string", "description": "* `MANUAL` - Manuale\n* `AML_SCREENING` - Screening AML\n* `TRANSACTION_RULE` - Regola di transazione\n* `WORKFLOW_BUILDER` - Generatore di workflow" }, "CaseCollaborationPatchedCaseNoteUpdateRequest": { "type": "object", "properties": { "is_pinned": { "type": "boolean" } } }, "CustomerMessagingPurposeEnum": { "enum": [ "identity_document", "proof_of_address", "business_document", "confirm_details", "review_in_progress" ], "type": "string", "description": "* `identity_document` - identity_document\n* `proof_of_address` - proof_of_address\n* `business_document` - business_document\n* `confirm_details` - confirm_details\n* `review_in_progress` - review_in_progress" }, "CaseDuplicateTypeEnum": { "enum": [ "user", "business" ], "type": "string", "description": "* `user` - user\n* `business` - business" }, "CaseCollaborationCaseNoteCreateRequest": { "type": "object", "properties": { "comment": { "type": "string", "minLength": 1, "maxLength": 10000 }, "reply_to": { "type": "string", "format": "uuid", "nullable": true }, "client_reference": { "type": "string", "format": "uuid", "nullable": true }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email", "minLength": 1 } }, "is_internal": { "type": "boolean", "default": false }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "comment" ] }, "CustomerMessagingLanguagesEnum": { "enum": [ "en", "es", "pt" ], "type": "string", "description": "* `en` - en\n* `es` - es\n* `pt` - pt" }, "CustomerMessagingCaseRequestConfirmRequest": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "purpose": { "$ref": "#/components/schemas/CustomerMessagingPurposeEnum" }, "language": { "allOf": [ { "$ref": "#/components/schemas/CustomerMessagingLanguageEnum" } ], "default": "en" }, "request_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "preview_token": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "contact_id", "expires_at", "preview_token", "purpose", "request_id" ] }, "CaseRoutingRule": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingCondition" }, "maxItems": 20 }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "team": { "type": "string", "format": "uuid", "nullable": true }, "is_active": { "type": "boolean" }, "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "readOnly": true }, "blueprint_name": { "type": "string", "readOnly": true }, "team_name": { "type": "string", "nullable": true, "readOnly": true } } }, "FraudResultEnum": { "enum": [ "match", "mismatch", "inconclusive", "no_reference" ], "type": "string", "description": "* `match` - Corrispondenza\n* `mismatch` - Mancata corrispondenza\n* `inconclusive` - Non conclusivo\n* `no_reference` - Nessun riferimento" }, "CaseRoutingRuleCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingCondition" }, "maxItems": 20 }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "team": { "type": "string", "format": "uuid", "nullable": true }, "is_active": { "type": "boolean" }, "publish": { "type": "boolean", "writeOnly": true, "description": "Imposta su false per salvare una bozza mai pubblicata. Il record rimane inattivo alla versione 0 fino a quando la bozza non viene esplicitamente pubblicata. L'omissione di questo campo mantiene la creazione immediata per le integrazioni esistenti." } }, "required": [ "name", "conditions", "blueprint" ] }, "FraudCheckIdentifierRequest": { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/FraudTypeEnum" } ], "description": "Tipo di identificatore. Determina quali campi del namespace sono obbligatori.\n\n* `email` - Email\n* `phone` - Telefono\n* `national_id` - Documento d'identità nazionale\n* `tax_number` - Codice fiscale\n* `passport_number` - Numero di passaporto\n* `driving_licence_number` - Numero della patente di guida\n* `residence_permit_number` - Numero del permesso di soggiorno\n* `voter_id` - Tessera elettorale\n* `external_id` - ID esterno" }, "value": { "type": "string", "minLength": 1, "description": "Il valore dell'identificativo, in qualsiasi formato consueto.", "maxLength": 255 }, "country": { "type": "string", "description": "Paese di emissione ISO-3166 alpha-2 o alpha-3. Obbligatorio per i tipi di identificativo governativo: le stesse cifre indicano persone diverse in paesi diversi.", "maxLength": 3 }, "issuer": { "type": "string", "description": "Autorità di rilascio o ente emittente sub-nazionale opzionale, quando il solo paese non è univoco.", "maxLength": 128 } }, "required": [ "type", "value" ] }, "CaseActionActionEnum": { "enum": [ "set_status", "add_tags", "add_note", "add_to_blocklist" ], "type": "string", "description": "* `set_status` - set_status\n* `add_tags` - add_tags\n* `add_note` - add_note\n* `add_to_blocklist` - add_to_blocklist" }, "CaseActionCaseActionReceiptPage": { "type": "object", "properties": { "count": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseActionCaseActionReceipt" } } }, "required": [ "count", "next_offset", "results" ] }, "CaseActionCaseEntityActionResult": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/CaseActionCaseActionReceipt" }, "entity_type": { "$ref": "#/components/schemas/CaseActionEntityTypeEnum" }, "entity_uuid": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "previous_status": { "type": "string" }, "new_status": { "type": "string" }, "tags_added": { "type": "array", "items": { "type": "string" } }, "comment_uuid": { "type": "string", "format": "uuid" }, "blocklisted": { "type": "array", "items": { "type": "string" } } } }, "CustomerMessagingCaseRequest": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "purpose": { "type": "string", "readOnly": true }, "language": { "type": "string", "readOnly": true }, "recipient": { "type": "string", "format": "email", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time", "readOnly": true }, "actor_email": { "type": "string", "format": "email", "readOnly": true, "nullable": true }, "delivery_status": { "type": "string", "readOnly": true }, "delivered_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "responded_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "response": { "readOnly": true, "nullable": true }, "has_attachment": { "type": "boolean", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "actor_email", "cancelled_at", "created_at", "delivered_at", "delivery_status", "expires_at", "has_attachment", "language", "purpose", "recipient", "responded_at", "response", "uuid" ] }, "CustomerMessagingCaseRequestPublic": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "purpose": { "$ref": "#/components/schemas/CustomerMessagingPurposeEnum" }, "language": { "$ref": "#/components/schemas/CustomerMessagingLanguageEnum" }, "expires_at": { "type": "string", "format": "date-time" }, "responded_at": { "type": "string", "format": "date-time", "nullable": true }, "copy": { "type": "object", "additionalProperties": {} }, "organization_name": { "type": "string" }, "is_white_label": { "type": "boolean" }, "customization": { "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "copy", "customization", "expires_at", "is_white_label", "language", "organization_name", "purpose", "request_id", "responded_at" ] }, "RoutingPublicationFieldEnum": { "enum": [ "source", "priority", "tags" ], "type": "string", "description": "* `source` - source\n* `priority` - priority\n* `tags` - tags" }, "RoutingPublicationCaseRoutingRule": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingPublicationRoutingCondition" } }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "blueprint_name": { "type": "string", "readOnly": true }, "team": { "type": "string", "format": "uuid", "nullable": true }, "team_name": { "type": "string", "readOnly": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "blueprint", "blueprint_name", "conditions", "created_at", "name", "team_name", "updated_at", "uuid", "version" ] }, "CaseActionStatusEnum": { "enum": [ "APPLIED", "FAILED" ], "type": "string", "description": "* `APPLIED` - Applicato\n* `FAILED` - Non riuscito" }, "FraudCheckModuleSelectionRequest": { "type": "object", "properties": { "include": { "type": "array", "items": { "$ref": "#/components/schemas/FraudExcludeEnum" } }, "exclude": { "type": "array", "items": { "$ref": "#/components/schemas/FraudExcludeEnum" } } } }, "SignatureField": { "type": "object", "description": "Un campo da inserire su un documento di sessione: quale firmatario lo compila, come e dove. Fornisci una posizione (`page`, `x`, `y`, `width` e `height`) oppure un `anchor`. Le posizioni sono frazioni della pagina così come visualizzata, a partire dall'angolo in alto a sinistra, arrotondate a 4 decimali, e il campo deve rientrare nella pagina. Un documento supporta fino a 200 campi e un firmatario fino a 500; ogni ruolo con campi su un documento richiede un campo `signature` o `initials`. Consulta [Campi sul documento](/it/core-technology/electronic-signature/overview#campi-sul-documento).", "required": [ "key", "type" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "Definisce il nome del campo nei risultati e in `sign.field_values`. Univoco all'interno del documento." }, "type": { "type": "string", "enum": [ "signature", "initials", "full_name", "date_signed", "text", "checkbox", "email", "data" ], "description": "Cosa contiene il campo. Il firmatario applica la `signature` e le `initials` adottate, inserisce `text`, spunta una `checkbox` e digita una `email` se la sessione non dispone di un'email verificata. Didit compila `full_name` (il nome verificato), `date_signed` (la data della firma, nel fuso orario del firmatario), `data` (da `prefill`) e una `email` verificata, mostrandoli in sola lettura. Non esiste un tipo di selettore di date: usa `text`." }, "role": { "type": "string", "enum": [ "verified_person", "legal_representative", "key_people" ], "description": "Chi compila il campo, con i valori di `signature_signer`. Un passaggio compila e appone il timbro solo sui campi del proprio firmatario. Il valore predefinito è il firmatario del passaggio." }, "page": { "type": "integer", "minimum": 1, "description": "Numero di pagina, da 1 al conteggio delle pagine del documento. Per un documento Word, una pagina del PDF convertito." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "Bordo sinistro, espresso come frazione della larghezza della pagina." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "Bordo superiore, espresso come frazione dell'altezza della pagina." }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "Larghezza, come frazione della larghezza della pagina. Una firma ha una larghezza minima di `0.12`." }, "height": { "type": "number", "minimum": 0.012, "maximum": 1, "description": "Altezza, come frazione dell'altezza della pagina. Una firma è alta almeno `0.035`." }, "anchor": { "$ref": "#/components/schemas/SignatureFieldAnchor" }, "required": { "type": "boolean", "description": "`signature` and `initials` are required unless you set `false`. `full_name`, `date_signed` and `data` are always required. The signer can't finish a document until its required fields have a value, and a required checkbox must be ticked." }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Mostrato al firmatario e nei risultati. Valore predefinito desunto dal tipo." }, "placeholder": { "type": "string", "nullable": true, "maxLength": 80, "description": "Solo `text` ed `email`." }, "validation": { "$ref": "#/components/schemas/SignatureFieldValidation" }, "prefill": { "type": "string", "nullable": true, "description": "Da dove proviene il valore: `identity.full_name`, `identity.first_name`, `identity.last_name`, `identity.date_of_birth` (`DD/MM/YYYY`), `identity.nationality`, `identity.document_number`, `identity.document_type`, `identity.issuing_country`, `identity.address`, `contact.email`, `contact.phone`, `company.name`, `company.registration_number`, `company.address`, `company.country` (KYB), `session.vendor_data`, `metadata.` (una chiave dei `metadata` della sessione) o `api.` (una chiave di `sign.field_values`). Obbligatorio per `data`. `full_name` utilizza sempre `identity.full_name` ed `email` utilizza `contact.email`. I valori dei campi `data`, `full_name` ed `email` verificata vengono fissati quando il firmatario inizia ad apporre la firma." }, "editable_when_prefilled": { "type": "boolean", "default": false, "description": "Solo `text` ed `email`: il firmatario può modificare un valore precompilato." }, "checked_by_default": { "type": "boolean", "default": false, "description": "Solo `checkbox`: la casella parte già selezionata." }, "date_format": { "type": "string", "enum": [ "DD/MM/YYYY", "MM/DD/YYYY", "YYYY-MM-DD", "D MMMM YYYY" ], "default": "DD/MM/YYYY", "description": "Solo `date_signed`." } } }, "SessionSignDocument": { "type": "object", "required": [ "file_name", "content_base64" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Titolo mostrato al firmatario. Il valore predefinito è `file_name`." }, "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Nome del file, che termina con `.pdf` o `.docx`." }, "content_base64": { "type": "string", "format": "byte", "description": "Il file, codificato in base64. Un PDF può avere dimensioni fino a 20 MB e 100 pagine, senza password, script o file allegati. Un file Word (`.docx`) può avere dimensioni fino a 20 MB e viene convertito in PDF durante l'esecuzione della richiesta, in un massimo di 25 secondi; il PDF rispetta poi gli stessi limiti. Fino a 5 file Word per sessione. Un file Word con macro, revisioni con rilevamento delle modifiche, link a contenuti esterni o oggetti incorporati viene rifiutato con `signature_document_not_supported`, mentre un file che non può essere convertito restituisce `signature_document_conversion_failed`, ciascuno con una `reason`." }, "fields": { "type": "array", "description": "Campi opzionali da posizionare su questo documento, fino a 200. Le pagine e le posizioni si riferiscono al PDF o al PDF convertito per un file Word. Senza campi, il firmatario legge il documento e lo accetta.", "items": { "$ref": "#/components/schemas/SignatureField" }, "maxItems": 200 } } }, "SignatureResult": { "type": "object", "description": "Il risultato di un firmatario per un passaggio di Firma elettronica. Consulta il [report di Firma elettronica](/it/core-technology/electronic-signature/report-electronic-signature).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Passalo come `signature_id` per scaricare le prove di questo firmatario o convalidare la sua firma." }, "node_id": { "type": "string", "description": "Il passaggio del workflow che lo ha prodotto." }, "status": { "type": "string", "enum": [ "intro", "review", "code", "signing", "signed", "declined" ], "description": "A che punto si trova il firmatario nel passaggio. Solo `signed` indica che i documenti sono firmati." }, "verdict": { "type": "string", "enum": [ "Not Finished", "Approved", "In Review", "Declined" ], "description": "L'esito del passaggio. Un avviso lo imposta tramite la propria regola; le regole di stato personalizzate si applicano successivamente." }, "level": { "type": "string", "enum": [ "simple", "aes", "qes" ], "description": "`simple` (predefinito) o `aes`. `qes` (Firma elettronica qualificata, QES) è un componente aggiuntivo non ancora disponibile." }, "format": { "type": "string", "enum": [ "pdf", "pades" ], "description": "`pdf` per una firma Simple, `pades` per Advanced (AES)." }, "profile": { "type": "string", "nullable": true, "description": "`PAdES-B-LT` una volta firmata una firma avanzata (AES), altrimenti null." }, "signer": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Il nome del firmatario. Verificato (dalla verifica dell'identità approvata o dalla sessione) tranne al livello Simple senza un nome di sessione verificato, dove corrisponde al nome digitato dal firmatario e non è verificato." }, "capacity": { "type": "string", "enum": [ "self", "company" ] }, "company": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true, "description": "La designazione della persona chiave, come dichiarata." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "I ruoli strutturati della persona chiave, come dichiarati per l'azienda." }, "identity_session_id": { "type": "string", "format": "uuid", "description": "La sessione KYC che ha verificato il firmatario." } } }, "identity_used": { "type": "object", "description": "L'identità verificata su cui si basa la firma. Vuoto per una firma Simple senza identità verificata.", "properties": { "session_id": { "type": "string", "format": "uuid" }, "kyc_id": { "type": "string", "format": "uuid", "nullable": true }, "verified": { "type": "boolean" }, "expected_name": { "type": "string", "nullable": true, "description": "Il nome a cui il firmatario doveva corrispondere." } } }, "certificate": { "type": "object", "nullable": true, "description": "Il certificato con cui sono stati firmati i documenti. `null` fino alla firma, e sempre `null` per una firma Simple.", "properties": { "issuer": { "type": "string" }, "issued_to": { "type": "string" }, "serial": { "type": "string", "description": "Numero di serie, esadecimale." }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" } } }, "confirmation": { "type": "object", "properties": { "channel": { "type": "string", "nullable": true, "enum": [ "email", "sms" ], "description": "`null` per una firma Simple, che non ha codice." }, "destination": { "type": "string", "nullable": true, "description": "Il contatto oscurato a cui è stato inviato il codice." }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "attempts": { "type": "integer", "description": "Codici inseriti, incluso quello corretto." } } }, "timestamp": { "type": "object", "nullable": true, "description": "Il timestamp RFC 3161 nella firma, emesso da Didit. `null` fino alla firma, e sempre `null` per una firma Semplice.", "properties": { "time": { "type": "string", "format": "date-time" }, "qualified": { "type": "boolean", "description": "Sempre `false` per AES." }, "valid": { "type": "boolean" } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Il documento sulla copia di questo firmatario. Usalo per scaricare il file firmato." }, "uuid": { "type": "string", "format": "uuid", "description": "Corrisponde a `id`." }, "title": { "type": "string" }, "file_name": { "type": "string" }, "pages": { "type": "integer", "description": "Pagine firmate del documento. Per Word, del PDF convertito." }, "size_bytes": { "type": "integer" }, "sha256_original": { "type": "string", "description": "SHA-256 del documento così come è stato mostrato al firmatario." }, "sha256_signed": { "type": "string", "nullable": true, "description": "SHA-256 del PDF firmato, una volta completata la firma." }, "status": { "type": "string", "enum": [ "signed", "declined", "not_signed", "not_reached" ], "description": "`not_signed`: aperto ma non firmato. `not_reached`: mai aperto." }, "opened_at": { "type": "string", "format": "date-time", "nullable": true }, "read_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il firmatario ha raggiunto la fine di un documento senza campi, se il passaggio lo richiede." }, "read_to_end": { "type": "boolean" }, "consented_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il firmatario ha accettato un documento senza campi o ha completato i campi di un documento provvisto di campi." }, "consent": { "type": "boolean" }, "signed_file": { "type": "string", "nullable": true, "description": "Percorso del PDF firmato, una volta firmato. Vedi [Scarica un documento firmato](/it/sessions-api/electronic-signature/download-signed-document)." }, "mode": { "type": "string", "enum": [ "fields", "read_and_agree" ], "description": "`fields` per un documento con campi, `read_and_agree` per un documento senza." }, "source_format": { "type": "string", "enum": [ "pdf", "docx" ], "description": "`pdf`, oppure `docx` per un documento Word convertito in PDF da Didit." }, "conversion": { "type": "object", "nullable": true, "description": "`null` per un PDF. Per un documento Word, il file originale e la conversione.", "properties": { "from": { "type": "string", "enum": [ "docx" ] }, "file_name": { "type": "string", "description": "Il nome originale del tuo file Word." }, "sha256": { "type": "string", "description": "SHA-256 del tuo file Word originale." }, "size_bytes": { "type": "integer", "description": "Dimensione del tuo file Word originale." }, "converter": { "type": "string", "description": "Versione del convertitore che ha generato il PDF." } } }, "fields": { "type": "array", "description": "Campi presenti sul documento, con i relativi valori. Vuoto per un documento senza campi.", "items": { "$ref": "#/components/schemas/SignatureFieldResult" } } } } }, "adopted_signature": { "type": "object", "nullable": true, "description": "La firma e le iniziali adottate dal firmatario per i campi di firma e iniziali. `null` finché il firmatario non ne adotta una.", "properties": { "method": { "type": "string", "enum": [ "typed", "drawn" ], "description": "`typed`: il nome verificato in stile calligrafico. `drawn`: disegnato con un dito o un mouse." }, "font": { "type": "string", "nullable": true, "description": "Lo stile calligrafico di una firma digitata. `null` se tracciata a mano." }, "adopted_at": { "type": "string", "format": "date-time" } } }, "electronic_signature_consent_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il firmatario ha acconsentito, nella schermata di revisione, a firmare elettronicamente i documenti. Impostato quando qualsiasi documento contiene campi." }, "evidence_file": { "type": "string", "nullable": true, "description": "Percorso del PDF delle prove, una volta firmato. Consulta [Scaricare le prove della firma](/it/sessions-api/electronic-signature/download-evidence)." }, "warnings": { "type": "array", "description": "Avvisi generati per questo firmatario. Vedi [Avvisi di Firma elettronica](/it/core-technology/electronic-signature/warnings-electronic-signature).", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SIGNATURE_DECLINED", "SIGNATURE_OTP_FAILED", "SIGNATURE_NAME_MISMATCH", "SIGNATURE_IDENTITY_NOT_VERIFIED", "SIGNATURE_DOCUMENT_CHANGED", "SIGNATURE_FIELD_DATA_MISSING" ] }, "node_id": { "type": "string" } } } }, "validation": { "type": "object", "nullable": true, "description": "L'ultimo controllo crittografico dei documenti firmati. `null` finché i documenti non vengono firmati. Se Didit non riesce a confermare l'esito della firma, il valore è `{\"valid\": null, \"reason\": \"signature_provider_outcome_unknown\", \"checked_at\": ...}` e `status` rimane `signing`: consideralo come non firmato.", "properties": { "valid": { "type": "boolean", "nullable": true, "description": "`true` quando ogni documento è valido. `null` quando non è stato possibile confermare l'esito della firma." }, "reason": { "type": "string", "description": "Impostato quando `valid` è `null`: `signature_provider_outcome_unknown`." }, "checked_at": { "type": "string", "format": "date-time" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "checked_at": { "type": "string", "format": "date-time" }, "valid": { "type": "boolean", "description": "`true` quando la firma e il timestamp sono entrambi validi e attendibili." }, "integrity": { "type": "boolean", "description": "`true` quando il documento non è stato modificato dopo la firma." }, "trusted": { "type": "boolean", "description": "`true` quando il certificato di firma fa capo a una radice attendibile." }, "revoked": { "type": "boolean" }, "trusted_list": { "type": "object", "description": "Controllo della Trusted List dell'UE. Per AES: `{\"status\": \"not_applicable\", \"reason\": \"aes_not_qualified\"}`.", "properties": { "status": { "type": "string" }, "reason": { "type": "string" } } }, "certificate": { "type": "object", "nullable": true, "description": "Il certificato con cui sono stati firmati i documenti. `null` fino alla firma, e sempre `null` per una firma Simple.", "properties": { "issuer": { "type": "string" }, "issued_to": { "type": "string" }, "serial": { "type": "string", "description": "Numero di serie, esadecimale." }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" } } }, "timestamp": { "type": "object", "nullable": true, "description": "Il timestamp RFC 3161 nella firma, emesso da Didit. `null` fino alla firma, e sempre `null` per una firma Semplice.", "properties": { "time": { "type": "string", "format": "date-time" }, "qualified": { "type": "boolean", "description": "Sempre `false` per AES." }, "valid": { "type": "boolean" } } } } } } } }, "declined_at": { "type": "string", "format": "date-time", "nullable": true }, "declined_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ] }, "signed_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando il link di firma smette di funzionare." }, "email_sent_at": { "type": "string", "format": "date-time", "nullable": true }, "email_unavailable_reason": { "type": "string", "nullable": true }, "ip_address": { "type": "string", "nullable": true, "description": "L'indirizzo IP del firmatario al momento della richiesta del codice." }, "place": { "type": "string", "nullable": true, "description": "Non raccolto: sempre `null`." }, "place_unavailable_reason": { "type": "string", "nullable": true, "enum": [ "not_collected" ] } } }, "SignatureFieldValidation": { "type": "object", "nullable": true, "description": "Regole per il valore di un campo `text`. L'anteprima della console, il flusso di firma e l'API applicano le stesse regole.", "properties": { "kind": { "type": "string", "enum": [ "any", "letters", "number", "email", "pattern" ], "description": "`letters`: lettere in qualsiasi sistema di scrittura, spazi, trattini e apostrofi. `number`: cifre con un separatore decimale facoltativo. `pattern`: il valore deve corrispondere a `pattern`." }, "min_length": { "type": "integer", "minimum": 0, "maximum": 500, "description": "Da `0` fino a `max_length`." }, "max_length": { "type": "integer", "minimum": 1, "maximum": 500, "default": 120 }, "pattern": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 200, "description": "Obbligatorio con `kind: \"pattern\"`. Un'espressione regolare a cui deve corrispondere l'intero valore. Lookaround e backreference non sono supportati." }, "message": { "type": "string", "nullable": true, "maxLength": 120, "description": "Mostrato al firmatario invece dell'errore predefinito." } } }, "SignatureFieldAnchor": { "type": "object", "description": "Posiziona un campo tramite una porzione di testo nel documento invece di una posizione. Didit non rimuove il testo dal PDF, quindi scrivilo nello stesso colore dello sfondo della pagina. Quando il testo non viene trovato, la chiamata restituisce `400` con `field_anchor_not_found`. Vedi [Posizionare i campi tramite testo di ancoraggio](/it/sessions-api/create-session#posiziona-i-campi-tramite-testo-di-ancoraggio).", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Testo cercato nel documento. Per i file Word, nel PDF convertito." }, "occurrence": { "type": "string", "enum": [ "first", "all" ], "default": "first", "description": "`all` inserisce un campo per ogni corrispondenza; le chiavi successive alla prima ricevono `_2`, `_3` e così via." }, "offset_x": { "type": "number", "description": "Aggiunto al bordo sinistro del testo, come frazione della larghezza della pagina." }, "offset_y": { "type": "number", "description": "Aggiunto al bordo superiore del testo, come frazione dell'altezza della pagina." }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "Larghezza del campo, come frazione della larghezza della pagina." }, "height": { "type": "number", "minimum": 0.012, "maximum": 1, "description": "Altezza del campo, come frazione dell'altezza della pagina." } } }, "SignatureFieldResult": { "type": "object", "description": "Un campo di un documento firmato, con il relativo valore sulla copia di questo firmatario. Vedi [Campi](/it/core-technology/electronic-signature/report-electronic-signature#campi).", "properties": { "key": { "type": "string", "description": "La chiave del campo, come utilizzata in `sign.field_values`." }, "type": { "type": "string", "enum": [ "signature", "initials", "full_name", "date_signed", "text", "checkbox", "email", "data" ] }, "role": { "type": "string", "enum": [ "verified_person", "legal_representative", "key_people" ] }, "label": { "type": "string" }, "page": { "type": "integer", "description": "Numero di pagina, a partire da 1. Per un documento Word, una pagina del PDF convertito." }, "x": { "type": "number", "description": "Bordo sinistro, espresso come frazione della larghezza della pagina." }, "y": { "type": "number", "description": "Bordo superiore, espresso come frazione dell'altezza della pagina." }, "width": { "type": "number", "description": "Larghezza, come frazione della larghezza della pagina." }, "height": { "type": "number", "description": "Altezza, come frazione dell'altezza della pagina." }, "required": { "type": "boolean" }, "value": { "nullable": true, "description": "Una stringa per `text`, `email`, `full_name`, `date_signed` e `data`, un booleano per `checkbox` e `true` per una firma o iniziali apposte. `null` se vuoto." }, "display_value": { "type": "string", "nullable": true, "description": "Il valore così come impresso sulla pagina: date nel `date_format` del campo, `Yes` o `No` per una casella di controllo, `Signed` per una firma o iniziali." }, "value_source": { "type": "string", "nullable": true, "enum": [ "signer", "identity", "contact", "company", "session", "metadata", "api", "signing_time", null ], "description": "Da dove proviene il valore: `signer` (digitato, selezionato o applicato dal firmatario), `identity` (l'identità verificata), `contact` (l'email o il telefono verificati), `company` (l'azienda verificata), `session` (`vendor_data`), `metadata`, `api` (`sign.field_values`) o `signing_time` (la data della firma)." }, "filled_at": { "type": "string", "format": "date-time", "nullable": true }, "image_url": { "type": "string", "nullable": true, "description": "Solo firma e iniziali: il percorso dell'immagine applicata. Consulta [Scarica un'immagine di firma](/it/sessions-api/electronic-signature/download-field-image)." }, "value_unavailable_reason": { "type": "string", "nullable": true, "enum": [ "source_empty", null ], "description": "`source_empty` quando un campo precompilato non aveva alcun valore nella sessione e `signature_field_data_missing_action` ha consentito comunque al firmatario di firmare." } } }, "VaspDirectoryWidgetEntry": { "type": "object", "description": "Cosa mostra il selettore del VASP dell'utente finale: l'identità del VASP e se è raggiungibile.", "properties": { "id": { "type": "string", "format": "uuid", "description": "L'ID della voce, per GET /v3/travel-rule/vasps/{vasp_id}/." }, "kind": { "type": "string", "enum": [ "directory", "didit" ], "description": "directory per una voce della directory condivisa; didit per un membro della rete Didit." }, "name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string", "description": "Codice paese ISO 3166, così come fornito dalla fonte." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "I domini web del VASP. Sempre vuoto per i membri della rete Didit." }, "reachable": { "type": "boolean", "description": "Indica se la tua applicazione dispone di una route disponibile verso questo VASP o verso una delle sue entità per un brand. Sempre true per un membro della rete Didit." } } }, "TravelRuleDataSharingFields": { "type": "object", "description": "I campi che Didit invia al VASP della controparte sui tuoi utenti, per tipo di entità. `name` e `wallet_address` vengono sempre inviati, a prescindere da quanto indicato nell'elenco. Un tipo di entità non selezionato condivide tutti i campi. Anche un elenco vuoto è una scelta: condivide solo il nome e il wallet.", "properties": { "individual": { "type": "array", "items": { "type": "string", "enum": [ "name", "wallet_address", "address", "national_id", "customer_identification", "date_of_birth", "place_of_birth" ] }, "description": "Campi condivisi relativi a una persona fisica." }, "company": { "type": "array", "items": { "type": "string", "enum": [ "name", "wallet_address", "address", "national_id", "customer_identification" ] }, "description": "Campi condivisi relativi a una persona giuridica." } } }, "TravelRuleMatchingRules": { "type": "object", "description": "Il livello di rigore con cui ogni campo dei dati della controparte viene confrontato con quelli in tuo possesso, per tipo di entità. I campi omessi mantengono il valore predefinito. `NONE` salta il confronto, `STRICT` richiede esattamente le stesse parole, `CONTAINS` accetta un valore le cui parole compaiono tutte nell'altro, `DEFAULT` è la corrispondenza standard per sottoinsieme e `FUZZY` accetta grafie simili (e, per le date di nascita, giorno e mese invertiti).", "properties": { "individual": { "type": "object", "description": "Regole per una persona fisica.", "properties": { "name": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Valore predefinito: segue `name_matching_strictness`." }, "date_of_birth": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Valore predefinito `NONE`." }, "address": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Valore predefinito `NONE`." }, "account": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Il wallet attraverso cui è stato instradato lo scambio. Predefinito `STRICT`." } } }, "company": { "type": "object", "description": "Regole per una persona giuridica.", "properties": { "name": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Valore predefinito: segue `name_matching_strictness`." }, "address": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Valore predefinito `NONE`." }, "account": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "Il wallet attraverso cui è stato instradato lo scambio. Predefinito `STRICT`." } } } } }, "TravelRuleDataMatch": { "type": "object", "nullable": true, "description": "Confronto campo per campo tra i dati della parte del trasferimento e ciò che l'altra parte sa sul titolare del wallet. Riporta i nomi dei campi e i risultati, mai i valori, in modo che rimanga leggibile mentre i dati della controparte sono oscurati. Null finché non viene eseguito un confronto.", "properties": { "matched": { "type": "boolean", "description": "True quando nessun campo confrontato differisce." }, "mismatched_fields": { "type": "array", "items": { "type": "string", "enum": [ "name", "date_of_birth", "address", "account" ] }, "description": "I campi che differiscono." }, "fields": { "type": "object", "description": "Una voce per ciascun campo confrontato per il tipo di entità della parte (`name`, `date_of_birth`, `address`, `account`; un'azienda non ha `date_of_birth`).", "additionalProperties": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "matched", "mismatched", "not_compared" ], "description": "`not_compared` quando la regola è `NONE` o una delle due parti non ha un valore per il campo." }, "strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ] } } } } } }, "TravelRuleDataUnmasked": { "type": "object", "nullable": true, "description": "Registro di audit del momento in cui i dati della controparte sono stati smascherati. Null finché i dati sono ancora mascherati e per i trasferimenti in uscita.", "properties": { "at": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "enum": [ "ownership_confirmed", "wallet_proof", "address_book_match", "own_verified_wallet", "inquiry_approved", "known_payment_method", "travel_address" ], "description": "Cosa ha confermato l'assetto proprietario: ownership_confirmed (la tua conferma tramite la console o l'API), wallet_proof (una prova del wallet nel widget o un trasferimento in entrata INTERNAL, impostato al momento della creazione), address_book_match (un wallet verificato nella rubrica), own_verified_wallet (il wallet verificato del tuo utente), inquiry_approved (la tua approvazione di una richiesta TRP in entrata o di un messaggio GTR o Sygna), known_payment_method (un wallet con cui il tuo utente ha già pagato) o travel_address (il Travel Address associato al wallet ha denominato il wallet)." }, "actor": { "type": "string", "description": "Chi l'ha confermata: l'email dell'utente della console o l'etichetta della chiave API. Vuoto per una decisione automatica." } } }, "TravelRuleMessageAttachment": { "type": "object", "nullable": true, "description": "Il documento allegato a un messaggio, archiviato come qualsiasi altro documento di transazione.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "uploaded_by": { "type": "string", "nullable": true, "description": "Chi lo ha allegato. Nel portale di ritiro, un file inviato mostra il nome del tuo VASP, mai la persona o la chiave API sottostante." }, "created_at": { "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_url": { "type": "string", "nullable": true, "description": "URL di download a tempo." }, "original_filename": { "type": "string" }, "file_size": { "type": "integer" } } } } } }, "TravelRuleMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "MESSAGE", "DOCUMENT_REQUEST" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "`OUTBOUND` indica ciò che la tua parte ha inviato. Nel portale di ritiro la direzione è dal lato della controparte." }, "author": { "type": "string", "description": "Chi lo ha scritto dalla propria parte: l'email di un utente della console o l'etichetta di una chiave API, oppure il nome dell'altro VASP." }, "body": { "type": "string" }, "requested_documents": { "type": "array", "items": { "type": "string" }, "description": "Cosa richiede una DOCUMENT_REQUEST, secondo le parole del richiedente." }, "reply_to": { "type": "string", "format": "uuid", "nullable": true }, "fulfilled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Impostato su un DOCUMENT_REQUEST quando una risposta ad esso contiene un documento." }, "attachment": { "$ref": "#/components/schemas/TravelRuleMessageAttachment" }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleMessageCreateRequest": { "type": "object", "description": "Invia come JSON, o come multipart/form-data con gli allegati in `files`.", "properties": { "kind": { "type": "string", "enum": [ "MESSAGE", "DOCUMENT_REQUEST" ], "default": "MESSAGE" }, "body": { "type": "string", "maxLength": 5000, "description": "Obbligatorio per un MESSAGE a meno che non sia allegato un file." }, "requested_documents": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 10, "description": "Obbligatorio (almeno uno) per un DOCUMENT_REQUEST, e consentito solo in tale contesto." }, "reply_to": { "type": "string", "format": "uuid", "nullable": true, "description": "Un messaggio del medesimo trasferimento. Una risposta contenente un documento soddisfa la richiesta di documento a cui risponde." }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 5, "description": "Solo multipart. Fino a 5 file da 10 MB ciascuno." } } }, "SessionDeletionJob": { "type": "object", "description": "Un'eliminazione massiva di sessioni in esecuzione in background: avanzamento e conteggi per esito, mai quali sessioni sono state eliminate.", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "Esegui il polling di `GET /v3/sessions/delete/{job_id}/` con questo id." }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ], "description": "`PENDING`: accettato, non ancora avviato. `PROCESSING`: eliminazione in corso; `processed` e `outcomes` si stanno aggiornando. `COMPLETED`: ogni sessione selezionata è stata gestita. `FAILED`: il job si è interrotto prima del completamento; vedi `error`." }, "total": { "type": "integer", "description": "Sessioni selezionate al momento della richiesta di eliminazione." }, "processed": { "type": "integer", "description": "Sessioni completate dal processo fino a questo momento." }, "outcomes": { "type": "object", "description": "Quante sessioni si sono concluse con ciascun esito. Ogni chiave è sempre presente.", "properties": { "deleted": { "type": "integer", "description": "Sessioni eliminate insieme al rispettivo embedding facciale." }, "none": { "type": "integer", "description": "Sessioni eliminate prive di embedding facciale." }, "retained_with_user": { "type": "integer", "description": "Sessioni eliminate mantenendo un modello biometrico privo di immagini per il relativo utente, come indicato nella richiesta o previsto dalla policy dell'applicazione." }, "ineligible_no_vendor_user": { "type": "integer", "description": "Sessioni eliminate, insieme al rispettivo embedding facciale, poiché era stata richiesta la conservazione dei dati ma non avevano alcun utente collegato." }, "failed_retryable": { "type": "integer", "description": "Sessioni segnalate come non eliminate. Un processo effettua un nuovo tentativo per un gruppo che non è riuscito a eliminare autonomamente invece di conteggiarlo qui." }, "already_deleted": { "type": "integer", "description": "Sessioni selezionate che erano già state eliminate, ad esempio da un'altra richiesta, nel momento in cui il job le ha raggiunte." } } }, "deleted_child_verifications": { "type": "integer", "description": "Verifiche create dalle verifiche aziendali eliminate, eliminate insieme a esse. Sempre `0` per un processo avviato da `POST /v3/sessions/delete/`, che elimina solo sessioni KYC." }, "error": { "type": "string", "nullable": true, "description": "`null` a meno che `status` non sia `FAILED`; in tal caso, indica il motivo per cui l'eliminazione si è interrotta. Le sessioni non ancora raggiunte dal processo rimangono invariate: ripeti la richiesta per eliminarle." }, "created_at": { "type": "string", "format": "date-time", "description": "Data e ora della richiesta di eliminazione." }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il processo è terminato; `null` mentre è in esecuzione." } } }, "EntityStatusUpdateRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "Nuovo stato del ciclo di vita. `BLOCKED` aggiunge inoltre il `vendor_data` alla blocklist di sistema." } } }, "AMLMonitoringToggleResult": { "oneOf": [ { "type": "object", "required": [ "users_total", "already_enabled", "with_existing_aml", "needing_screening", "skipped_no_identity_data", "skipped_blocked", "estimated_screening_cost_usd", "estimated_annual_monitoring_cost_usd", "balance_sufficient", "unmatched" ], "description": "Anteprima dei costi. Restituita direttamente quando estimate_only è true (non viene scritto nulla).", "properties": { "users_total": { "type": "integer", "description": "Profili corrispondenti alla selezione." }, "already_enabled": { "type": "integer", "description": "Profili già monitorati (nessuna operazione da eseguire durante l'abilitazione; sono quelli che vengono disattivati quando si disabilita il monitoraggio)." }, "with_existing_aml": { "type": "integer", "description": "Profili il cui Screening AML esistente verrà impostato come monitorato (nessun nuovo screening)." }, "needing_screening": { "type": "integer", "description": "Profili senza alcuno Screening AML che verranno prima sottoposti a screening (fatturati come normale Screening AML)." }, "skipped_no_identity_data": { "type": "integer", "description": "Profili di cui non è possibile effettuare lo screening a causa della mancanza dei dati di identità." }, "skipped_blocked": { "type": "integer", "description": "Utenti bloccati che verranno saltati (sempre 0 per le aziende)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Costo una tantum dei nuovi screening." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Costo annuale di monitoraggio dei profili che passeranno a essere monitorati." }, "balance_sufficient": { "type": "boolean", "description": "Indica se il saldo dell'organizzazione copre lo screening e il primo anno di monitoraggio." }, "unmatched": { "type": "array", "items": { "type": "string" }, "description": "Identificatori della richiesta che non hanno trovato corrispondenza con alcun profilo in questa applicazione, esattamente come inviati." } } }, { "type": "object", "required": [ "job_id", "status", "is_enabled", "target_type", "total", "processed", "outcomes", "results", "error", "created_at", "completed_at", "estimate", "unmatched" ], "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean", "description": "true quando il job abilita il monitoraggio, false quando lo disabilita." }, "target_type": { "type": "string", "enum": [ "user", "business" ], "description": "Quale famiglia di profili viene attivata o disattivata dal job." }, "total": { "type": "integer", "description": "Profili elaborati dal job." }, "processed": { "type": "integer", "description": "Profili elaborati finora." }, "outcomes": { "type": "object", "description": "Contatori di esito per singolo record. Ogni profilo selezionato corrisponde esattamente a un contatore; nulla viene ignorato silenziosamente.", "properties": { "enabled": { "type": "integer", "description": "Monitoraggio abilitato su uno screening AML esistente." }, "screened_and_enabled": { "type": "integer", "description": "È stato creato un nuovo screening AML (fatturato) e il relativo monitoraggio è stato abilitato." }, "already_enabled": { "type": "integer", "description": "Il monitoraggio era già attivo; non è cambiato nulla e non è stato fatturato nulla." }, "disabled": { "type": "integer", "description": "Monitoraggio disattivato su tutti gli screening AML del profilo." }, "skipped_no_identity_data": { "type": "integer", "description": "Saltato: il profilo è privo di nome completo, data di nascita e paese (utenti) o di un nome (aziende) necessari per lo screening." }, "skipped_blocked": { "type": "integer", "description": "Saltato: l'utente è bloccato." }, "skipped_sandbox": { "type": "integer", "description": "Saltato: applicazione sandbox, non viene creato alcuno screening." }, "failed_provider": { "type": "integer", "description": "Impossibile completare lo screening; riprova più tardi." }, "failed_insufficient_balance": { "type": "integer", "description": "Il saldo si è esaurito mentre il processo era in esecuzione." } } }, "results": { "type": "array", "description": "Una voce per ogni profilo elaborato, nell'ordine di elaborazione. Aumenta durante l'esecuzione del job; completa una volta che lo stato è COMPLETED. Registrata per i job avviati tramite API.", "items": { "type": "object", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "ID interno Didit del profilo." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore per il profilo." }, "outcome": { "type": "string", "enum": [ "enabled", "screened_and_enabled", "already_enabled", "disabled", "skipped_no_identity_data", "skipped_blocked", "skipped_sandbox", "failed_provider", "failed_insufficient_balance" ] } } } }, "error": { "type": "string", "nullable": true, "description": "Messaggio di errore generico quando lo stato è FAILED; la causa dettagliata viene conservata lato piattaforma." }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "estimate": { "type": "object", "description": "Anteprima dei costi. Restituita direttamente quando estimate_only è true (non viene scritto nulla).", "properties": { "users_total": { "type": "integer", "description": "Profili corrispondenti alla selezione." }, "already_enabled": { "type": "integer", "description": "Profili già monitorati (nessuna operazione da eseguire durante l'abilitazione; sono quelli che vengono disattivati quando si disabilita il monitoraggio)." }, "with_existing_aml": { "type": "integer", "description": "Profili il cui Screening AML esistente verrà impostato come monitorato (nessun nuovo screening)." }, "needing_screening": { "type": "integer", "description": "Profili senza alcuno Screening AML che verranno prima sottoposti a screening (fatturati come normale Screening AML)." }, "skipped_no_identity_data": { "type": "integer", "description": "Profili di cui non è possibile effettuare lo screening a causa della mancanza dei dati di identità." }, "skipped_blocked": { "type": "integer", "description": "Utenti bloccati che verranno saltati (sempre 0 per le aziende)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Costo una tantum dei nuovi screening." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Costo annuale di monitoraggio dei profili che passeranno a essere monitorati." }, "balance_sufficient": { "type": "boolean", "description": "Indica se il saldo dell'organizzazione copre lo screening e il primo anno di monitoraggio." } } }, "unmatched": { "type": "array", "items": { "type": "string" }, "description": "Identificatori della richiesta che non hanno trovato corrispondenza con alcun profilo in questa applicazione, esattamente come inviati. Non fanno parte del processo." } } } ] }, "AMLMonitoringJob": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean", "description": "true quando il job abilita il monitoraggio, false quando lo disabilita." }, "target_type": { "type": "string", "enum": [ "user", "business" ], "description": "Quale famiglia di profili viene attivata o disattivata dal job." }, "total": { "type": "integer", "description": "Profili elaborati dal job." }, "processed": { "type": "integer", "description": "Profili elaborati finora." }, "outcomes": { "type": "object", "description": "Contatori di esito per singolo record. Ogni profilo selezionato corrisponde esattamente a un contatore; nulla viene ignorato silenziosamente.", "properties": { "enabled": { "type": "integer", "description": "Monitoraggio abilitato su uno screening AML esistente." }, "screened_and_enabled": { "type": "integer", "description": "È stato creato un nuovo screening AML (fatturato) e il relativo monitoraggio è stato abilitato." }, "already_enabled": { "type": "integer", "description": "Il monitoraggio era già attivo; non è cambiato nulla e non è stato fatturato nulla." }, "disabled": { "type": "integer", "description": "Monitoraggio disattivato su tutti gli screening AML del profilo." }, "skipped_no_identity_data": { "type": "integer", "description": "Saltato: il profilo è privo di nome completo, data di nascita e paese (utenti) o di un nome (aziende) necessari per lo screening." }, "skipped_blocked": { "type": "integer", "description": "Saltato: l'utente è bloccato." }, "skipped_sandbox": { "type": "integer", "description": "Saltato: applicazione sandbox, non viene creato alcuno screening." }, "failed_provider": { "type": "integer", "description": "Impossibile completare lo screening; riprova più tardi." }, "failed_insufficient_balance": { "type": "integer", "description": "Il saldo si è esaurito mentre il processo era in esecuzione." } } }, "results": { "type": "array", "description": "Una voce per ogni profilo elaborato, nell'ordine di elaborazione. Aumenta durante l'esecuzione del job; completa una volta che lo stato è COMPLETED. Registrata per i job avviati tramite API.", "items": { "type": "object", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "ID interno Didit del profilo." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore per il profilo." }, "outcome": { "type": "string", "enum": [ "enabled", "screened_and_enabled", "already_enabled", "disabled", "skipped_no_identity_data", "skipped_blocked", "skipped_sandbox", "failed_provider", "failed_insufficient_balance" ] } } } }, "error": { "type": "string", "nullable": true, "description": "Messaggio di errore generico quando lo stato è FAILED; la causa dettagliata viene conservata lato piattaforma." }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "estimate": { "type": "object", "description": "Anteprima dei costi. Restituita direttamente quando estimate_only è true (non viene scritto nulla).", "properties": { "users_total": { "type": "integer", "description": "Profili corrispondenti alla selezione." }, "already_enabled": { "type": "integer", "description": "Profili già monitorati (nessuna operazione da eseguire durante l'abilitazione; sono quelli che vengono disattivati quando si disabilita il monitoraggio)." }, "with_existing_aml": { "type": "integer", "description": "Profili il cui Screening AML esistente verrà impostato come monitorato (nessun nuovo screening)." }, "needing_screening": { "type": "integer", "description": "Profili senza alcuno Screening AML che verranno prima sottoposti a screening (fatturati come normale Screening AML)." }, "skipped_no_identity_data": { "type": "integer", "description": "Profili di cui non è possibile effettuare lo screening a causa della mancanza dei dati di identità." }, "skipped_blocked": { "type": "integer", "description": "Utenti bloccati che verranno saltati (sempre 0 per le aziende)." }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "Costo una tantum dei nuovi screening." }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "Costo annuale di monitoraggio dei profili che passeranno a essere monitorati." }, "balance_sufficient": { "type": "boolean", "description": "Indica se il saldo dell'organizzazione copre lo screening e il primo anno di monitoraggio." } } }, "unmatched": { "type": "array", "items": { "type": "string" }, "description": "Identificatori della richiesta che non hanno trovato corrispondenza con alcun profilo in questa applicazione, esattamente come inviati. Non fanno parte del processo." } } }, "OngoingMonitoringToggleRequest": { "type": "object", "required": [ "is_enabled" ], "properties": { "is_enabled": { "type": "boolean", "description": "true per abilitare il monitoraggio, false per disabilitarlo." }, "estimate_only": { "type": "boolean", "default": false, "description": "Se true, restituisce la stima dei costi e non esegue scritture." }, "update_all": { "type": "boolean", "default": false, "description": "Applica a ogni entità dell'applicazione (con ambito limitato dai parametri filter_* se presenti)." }, "filter_search": { "type": "string" }, "filter_status": { "type": "array", "items": { "type": "string" } }, "filter_country": { "type": "string" }, "filter_date_from": { "type": "string", "format": "date" }, "filter_date_to": { "type": "string", "format": "date" }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Entità da abilitare o disabilitare. Obbligatorio a meno che update_all non sia true." } } }, "OngoingMonitoringJob": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean" }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "outcomes": { "type": "object", "description": "Contatori degli esiti per entità. Nulla viene ignorato silenziosamente: ogni entità richiesta corrisponde esattamente a un contatore.", "properties": { "enabled": { "type": "integer", "description": "Monitoraggio abilitato su uno screening AML esistente." }, "screened_and_enabled": { "type": "integer", "description": "È stato creato un nuovo screening AML (fatturato) e il monitoraggio è stato abilitato." }, "already_enabled": { "type": "integer", "description": "Il monitoraggio era già attivo (le righe duplicate legacy vengono consolidate)." }, "disabled": { "type": "integer", "description": "Monitoraggio disabilitato su ogni riga AML dell'entità." }, "skipped_no_identity_data": { "type": "integer", "description": "Saltato: non sono disponibili nome completo + data di nascita + paese per lo screening." }, "skipped_blocked": { "type": "integer", "description": "Saltato: l'utente è bloccato." }, "skipped_sandbox": { "type": "integer", "description": "Saltato: applicazione sandbox." }, "failed_provider": { "type": "integer", "description": "La chiamata al provider di screening non è riuscita." }, "failed_insufficient_balance": { "type": "integer", "description": "Il saldo si è esaurito durante l'esecuzione del processo." } } }, "error": { "type": "string", "nullable": true }, "estimate": { "type": "object", "description": "Anteprima dei costi. Restituita direttamente quando estimate_only è true (non viene eseguita alcuna operazione di scrittura).", "properties": { "users_total": { "type": "integer", "description": "Entità presenti nella selezione." }, "already_enabled": { "type": "integer" }, "with_existing_aml": { "type": "integer", "description": "Entità il cui screening AML esistente verrà sottoposto al monitoraggio." }, "needing_screening": { "type": "integer", "description": "Entità prive di qualsiasi screening AML che verranno sottoposte a screening per prime (fatturate)." }, "skipped_no_identity_data": { "type": "integer" }, "skipped_blocked": { "type": "integer" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2 }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07 }, "balance_sufficient": { "type": "boolean" } } } } }, "OngoingMonitoringToggleResult": { "oneOf": [ { "type": "object", "description": "Anteprima dei costi. Restituita direttamente quando estimate_only è true (non viene eseguita alcuna operazione di scrittura).", "properties": { "users_total": { "type": "integer", "description": "Entità presenti nella selezione." }, "already_enabled": { "type": "integer" }, "with_existing_aml": { "type": "integer", "description": "Entità il cui screening AML esistente verrà sottoposto al monitoraggio." }, "needing_screening": { "type": "integer", "description": "Entità prive di qualsiasi screening AML che verranno sottoposte a screening per prime (fatturate)." }, "skipped_no_identity_data": { "type": "integer" }, "skipped_blocked": { "type": "integer" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2 }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07 }, "balance_sufficient": { "type": "boolean" } } }, { "$ref": "#/components/schemas/OngoingMonitoringJob" } ] }, "CaseBlueprintPresetInstallResult": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "string" } } } }, "CaseBulkUpdateResult": { "type": "object", "properties": { "updated": { "type": "integer" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "case_uuid": { "type": "string", "format": "uuid" }, "detail": { "type": "string" } } } } } }, "RegulatoryReportList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Numero di righe corrispondenti, con limite massimo di 100 per motivi di prestazioni." }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "EntityNetworkMembershipList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EntityNetworkMembership" } } } }, "SessionDecision": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "L'identificatore univoco della sessione." }, "session_kind": { "type": "string", "enum": [ "user", "business" ], "description": "Discriminatore che indica se si tratta di una sessione di Verifica degli utenti (KYC) o di Verifica aziendale (KYB). Quando è `user`, si applicano gli array di funzionalità KYC (`id_verifications`, `nfc_verifications`, `liveness_checks`, `face_matches`, `poa_verifications`, `document_ai_documents`, `database_validations`, ...) e gli array aziendali sono assenti. Quando è `business`, il payload contiene invece `registry_checks`, `document_verifications`, `key_people_checks` oltre agli array condivisi (`aml_screenings`, `phone_verifications`, `email_verifications`, `ip_analyses`, `questionnaire_responses`). **Omesso quando viene passato `include=events`** — il formato degli eventi esiste solo per le sessioni utente, quindi il discriminatore viene rimosso da quella variante." }, "shared_from_session": { "type": "string", "format": "uuid", "nullable": true, "description": "Per una sessione clonata con `POST /v3/session/import-shared/`: il `session_id` della sessione originale nell'applicazione di origine. `null` per qualsiasi altra sessione. Omesso quando viene passato `include=events`." }, "shared_from_session_number": { "type": "integer", "nullable": true, "description": "`session_number` della sessione di origine quando questa sessione è stata importata da un'altra applicazione della tua organizzazione. `null` altrimenti." }, "session_number": { "type": "integer", "description": "Il numero della sessione.", "nullable": true }, "session_url": { "type": "string", "format": "uri", "description": "L'URL della sessione.", "nullable": true }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Awaiting User", "In Review", "Approved", "Declined", "Resubmitted", "Expired", "Kyc Expired", "Abandoned" ], "description": "Stato complessivo del ciclo di vita della sessione — il risultato aggregato del workflow. I valori finali sono `Approved`, `Declined`, `In Review`, `Expired`, `Kyc Expired` e `Abandoned`; `Not Started`, `In Progress`, `Awaiting User` e `Resubmitted` indicano che la sessione è ancora in corso nel workflow." }, "status_override": { "type": "object", "nullable": true, "description": "Presente quando un revisore ha impostato manualmente lo `status`. `null` quando lo stato è quello automatico. Utilizzalo per distinguere un'approvazione manuale da una automatica.", "properties": { "overridden_at": { "type": "string", "format": "date-time", "nullable": true }, "automatic_status": { "type": "string", "nullable": true, "description": "Lo stato determinato dai controlli della piattaforma." } } }, "decision_trace": { "type": "object", "description": "Come è stato raggiunto lo stato: chi lo ha impostato e quali avvisi lo hanno determinato.", "properties": { "status": { "type": "string", "description": "Lo stato della sessione." }, "decided_by": { "type": "string", "nullable": true, "enum": [ "manual", "automatic", "investigator", null ], "description": "Chi ha impostato lo stato. `null` finché non viene presa una decisione sulla sessione." }, "decided_at": { "type": "string", "format": "date-time", "nullable": true }, "automatic_status": { "type": "string", "nullable": true, "description": "Cosa concludono i controlli interni della piattaforma, che differisce da `status` dopo una decisione manuale." }, "terminal_node_id": { "type": "string", "nullable": true, "description": "Il nodo di stato del workflow che ha terminato la sessione, se presente." }, "actor": { "type": "object", "nullable": true, "description": "Il revisore autore di una decisione manuale.", "properties": { "user": { "type": "string", "nullable": true }, "actor_type": { "type": "string", "nullable": true } } }, "warning_counts": { "type": "object", "description": "Avvisi per `log_type` (`error`, `warning`, `information`) e `total`.", "additionalProperties": { "type": "integer" } }, "status_warnings": { "type": "array", "description": "Gli avvisi che impostano uno stato `Declined` o `In Review`.", "items": { "type": "object", "properties": { "risk": { "type": "string" }, "feature": { "type": "string", "nullable": true }, "node_id": { "type": "string", "nullable": true }, "log_type": { "type": "string", "nullable": true }, "check_status": { "type": "string", "nullable": true }, "source": { "type": "string", "description": "L'elenco del payload da cui proviene l'avviso, ad esempio `id_verifications`." }, "short_description": { "type": "string", "nullable": true } } } } } }, "linked_records": { "type": "object", "nullable": true, "description": "Un riepilogo di altri record collegati alla sessione. `null` quando non c'è nulla da mostrare e per i workflow che dichiarano uno standard di verifica dell'età.", "properties": { "same_face": { "type": "object", "nullable": true, "description": "Altre persone il cui volto corrisponde a una delle ricerche facciali di questa sessione.", "properties": { "count": { "type": "integer" }, "best_match": { "type": "object", "nullable": true, "properties": { "session_id": { "type": "string", "format": "uuid", "nullable": true }, "session_number": { "type": "integer", "nullable": true }, "vendor_user_id": { "type": "string", "format": "uuid", "nullable": true }, "similarity_percentage": { "type": "number", "nullable": true } } } } }, "earlier_verifications": { "type": "object", "nullable": true, "properties": { "count": { "type": "integer" }, "vendor_user_id": { "type": "string", "format": "uuid", "nullable": true } } }, "networks": { "type": "object", "nullable": true, "properties": { "count": { "type": "integer" }, "open": { "type": "integer" }, "dismissed": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "network_id": { "type": "string", "format": "uuid" }, "display_number": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "status": { "type": "string" }, "risk_score": { "type": "number", "nullable": true } } } } } } } }, "workflow_id": { "type": "string", "format": "uuid", "description": "Identificatore stabile del gruppo di workflow che ha prodotto questa sessione. I workflow sono versionati: questo valore identifica il workflow stesso, non la versione specifica.", "nullable": true }, "features": { "type": "array", "items": { "type": "string", "description": "La funzionalità della sessione." }, "description": "Elenco delle funzionalità di verifica configurate per questa sessione, come nomi visualizzati: `ID_VERIFICATION`, `NFC`, `LIVENESS`, `FACE_MATCH`, `POA`, `PHONE`, `EMAIL_VERIFICATION`, `AML`, `IP_ANALYSIS`, `DATABASE_VALIDATION`, `QUESTIONNAIRE`, `AGE_ESTIMATION`, `FACE_SEARCH`, `GEOLOCATION` (Verifica della posizione) (le sessioni di Verifica aziendale utilizzano il set di funzionalità KYB: `KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`, `AML`, `PHONE`, `EMAIL_VERIFICATION`, `IP_ANALYSIS`, `QUESTIONNAIRE`). Con `include=events` ogni voce diventa un oggetto `{feature, node_id}` invece di una semplice stringa, e la funzionalità email viene rinominata: compare come `EMAIL` in modalità eventi invece dell'`EMAIL_VERIFICATION` utilizzato qui." }, "vendor_data": { "type": "string", "description": "I dati del vendor della sessione.", "nullable": true }, "metadata": { "type": "object", "description": "I metadati della sessione.", "nullable": true }, "expected_details": { "type": "object", "description": "Dettagli previsti forniti al momento della creazione della sessione — utilizzati per la convalida incrociata rispetto ai dati estratti (KYC) o per precompilare la ricerca nel registro delle imprese (KYB). Restituisce esattamente le chiavi fornite; `null` se non ne è stata fornita alcuna. Le sessioni KYC contengono i campi della persona; le sessioni aziendali (KYB) contengono `company_name`, `registry_country` e `registration_number`.", "properties": { "first_name": { "type": "string", "description": "Nome dell'utente. Ad esempio, `John`." }, "last_name": { "type": "string", "description": "Cognome dell'utente. Ad esempio, `Doe`." }, "date_of_birth": { "type": "string", "format": "date", "description": "Data di nascita dell'utente nel formato: YYYY-MM-DD. Ad esempio, `1990-05-15`." }, "gender": { "type": "string", "nullable": true, "enum": [ "M", "F" ], "default": null, "description": "Genere dell'utente. Deve essere 'M', 'F' o null." }, "nationality": { "type": "string", "description": "Codice paese ISO 3166-1 alpha-3 che rappresenta il paese di origine del richiedente. Ad esempio, `USA`." }, "country": { "type": "string", "description": "Codice paese ISO 3166-1 alpha-3 che rappresenta il paese del documento di Prova di residenza o il paese del documento d'identità del richiedente, che può differire dalla nazionalità. Ad esempio, `GBR`." }, "address": { "type": "string", "description": "L'indirizzo in un formato leggibile, includendo quante più informazioni possibili. Ad esempio, `123 Main St, San Francisco, CA 94105, USA`." }, "identification_number": { "type": "string", "description": "Il numero del documento, il codice personale o il codice fiscale dell'utente. Ad esempio, `123456789`." }, "ip_address": { "type": "string", "format": "ipv4", "description": "Indirizzo IP previsto per la sessione. Se l'indirizzo IP effettivo differisce da questo valore, verrà registrato un avviso. Ad esempio, `192.168.1.100`." }, "expected_document_types": { "type": "array", "description": "Tipi di documento a cui è stato limitato il passaggio di verifica dell'identità al momento della creazione della sessione. Vuoto/non impostato indica nessuna restrizione. Codici: `P` (passaporto), `ID` (carta d'identità), `DL` (patente di guida), `RP` (permesso di soggiorno), `HIC` (tessera sanitaria), `TC` (tessera fiscale), `SSC` (tessera di previdenza sociale).", "items": { "type": "string", "enum": [ "P", "ID", "DL", "RP", "HIC", "TC", "SSC" ] } }, "id_country": { "type": "string", "nullable": true, "description": "Paese di emissione previsto del documento d'identità (ISO 3166-1 alpha-3), se limitato al momento della creazione.", "example": "ESP" }, "poa_country": { "type": "string", "nullable": true, "description": "Paese previsto del documento di prova di residenza (ISO 3166-1 alpha-3), se limitato al momento della creazione.", "example": "ESP" }, "company_name": { "type": "string", "description": "Ragione sociale prevista dell'azienda. Solo per sessioni aziendali (KYB)." }, "registry_country": { "type": "string", "description": "Paese del registro previsto nel formato `XX` o `XX-YY` (ISO 3166-1 alpha-2, facoltativamente con una suddivisione ISO 3166-2 per i registri a livello statale, ad es. `US-CA`). Solo per sessioni aziendali (KYB)." }, "registration_number": { "type": "string", "description": "Numero di registrazione dell'azienda previsto. Solo sessioni aziendali (KYB)." } }, "nullable": true }, "contact_details": { "type": "object", "description": "Dati di contatto forniti al momento della creazione della sessione (utilizzati per le email di notifica, la verifica precompilata di telefono/email e la lingua di comunicazione). `null` quando non sono stati forniti né un'email né un numero di telefono.", "properties": { "email": { "type": "string", "description": "Indirizzo email dell'utente (ad es. \"john.doe@example.com\") che verrà utilizzato durante il passaggio di Verifica email. Se non fornito, l'utente dovrà inserirlo durante il flusso di verifica." }, "email_lang": { "type": "string", "description": "Codice lingua (ISO 639-1) per le notifiche email. Controlla la lingua di tutte le comunicazioni via email (es. \"en\", \"es\", \"fr\")." }, "send_notification_emails": { "type": "boolean", "default": false, "description": "Se true e viene fornita un'email, Didit invia l'email iniziale \"Verifica la tua identità\" in modo asincrono quando viene creata la sessione di Verifica degli utenti (KYC) o Verifica aziendale (KYB). Didit invia inoltre le notifiche sullo stato della verifica per le sessioni che richiedono la revisione manuale all'indirizzo email fornito." }, "phone": { "type": "string", "nullable": true, "description": "Numero di telefono dell'utente in formato E.164 se disponibile (ad es. +14155552671). `null` quando alla creazione della sessione è stata fornita solo un'email. Nota: questo campo restituisce il numero di telefono originale fornito durante la creazione della sessione. Se il numero non era valido, potrebbe non essere in formato E.164." } }, "nullable": true }, "callback": { "type": "string", "format": "uri", "description": "L'URL di callback della sessione.", "nullable": true }, "id_verifications": { "type": "array", "nullable": true, "description": "**Array di report di verifica dell'identità (OCR)** prodotti dai passaggi dei documenti di identità nel grafo del workflow. Sempre un array JSON — leggi `id_verifications[0]` e itera se il tuo workflow può eseguire più di un controllo dell'identità (ad esempio un controllo primario più uno step-up). `null` fino a quando almeno un passaggio di verifica dell'identità non ha prodotto dati. Ciascun elemento è il report completo, inclusi `node_id`, `status` a livello di funzionalità, campi estratti del documento, URL delle immagini, punteggi di qualità, MRZ, analisi dell'indirizzo, corrispondenze cross-sessione e `warnings[]`.", "items": { "type": "object", "description": "Un report di verifica dell'identità: il report completo per un singolo passaggio di Verifica dell'identità. `verification_method` indica quale dei tre metodi lo ha prodotto (acquisizione del documento, ricerca non documentale o accesso tramite wallet) e il blocco delle prove specifico del metodo viene popolato di conseguenza.", "properties": { "node_id": { "type": "string", "description": "ID del nodo del grafo del workflow del passaggio OCR che ha generato questo report." }, "verification_method": { "type": "string", "enum": [ "document", "id_lookup", "wallet" ], "description": "Quale metodo di Verifica dell'identità ha prodotto questo report. `document`: l'utente ha fotografato un documento d'identità fisico (impostazione predefinita e valore presente in ogni sessione creata prima dell'introduzione degli altri metodi). `id_lookup`: l'utente ha inserito il proprio numero di documento d'identità nazionale, verificato rispetto a un registro governativo o a un'altra fonte autorevole per quel paese (`id_lookup.source` ne indica il nome). `wallet`: l'utente ha effettuato l'accesso con un'identità digitale governativa o bancaria." }, "assurance": { "type": "string", "enum": [ "documentary", "data_match", "cryptographic" ], "description": "Livello di garanzia derivato da `verification_method`: `documentary` per un documento acquisito e verificato, `data_match` per dettagli che corrispondono a un record conservato dalla fonte interrogata, `cryptographic` per attributi autenticati e firmati da un provider di identità." }, "wallet_provider": { "type": "string", "nullable": true, "description": "Id del wallet di catalogo quando `verification_method` è `wallet` (`mitid`, `bankid_se`, `itsme`, ...). `null` altrimenti." }, "fallback_from": { "type": "object", "nullable": true, "description": "Il motivo per cui un metodo non basato su documenti non ha concluso il passaggio di identificazione. Impostato quando una ricerca o un accesso tramite wallet è fallito: sulla verifica del documento con cui l'utente ha proseguito quando lo switch di fallback del paese era `fallback_to_document` (`action` è `fallback_to_document`), oppure sul report rifiutato quando era `decline`. `null` altrimenti.", "properties": { "method": { "type": "string", "enum": [ "id_lookup", "wallet" ], "description": "Il metodo che ha fallito." }, "reason": { "type": "string", "description": "L'esito che ne ha determinato la conclusione, ad es. `no_match`, `provider_error`, `cancelled`, `timeout`." }, "action": { "type": "string", "enum": [ "fallback_to_document", "decline" ], "description": "L'azione configurata che è stata eseguita: `fallback_to_document` o `decline`." } } }, "id_lookup": { "type": "object", "nullable": true, "description": "Prova dal registro delle imprese. Presente solo quando `verification_method` è `id_lookup`; `null` altrimenti.", "properties": { "source": { "type": "string", "description": "Nome visibile al cliente della fonte interrogata, ad es. `Department of Home Affairs` (un registro governativo) o `UK credit bureau and financial services records` (non un registro governativo). Questa è l'unica dichiarazione di provenienza per la ricerca; non dare per scontata una fonte governativa." }, "checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il registro ha risposto." }, "attempts": { "type": "integer", "description": "Numero progressivo del tentativo, a partire da 1, da cui proviene questo report." }, "max_attempts": { "type": "integer", "description": "Budget di tentativi configurato per il paese (da 1 a 5, predefinito 1)." }, "outcome": { "type": "string", "enum": [ "match", "partial_match", "no_match", "provider_error", "format_rejected" ], "nullable": true, "description": "Cosa ha risposto il registro. Solo `match`, `partial_match` e `no_match` vengono conteggiati ai fini del budget di tentativi e della fatturazione." }, "comparison": { "type": "array", "description": "Una riga per ogni campo confrontabile per cui la fonte ha risposto, più una riga per ogni errore della fonte. Le righe di confronto utilizzano i nomi di campo normalizzati indicati di seguito anziché le chiavi dei campi di richiesta del paese, poiché diversi campi di richiesta (nome e cognome, o uno qualsiasi degli alias dell'identificatore) confluiscono in un unico confronto. Una fonte che ha fallito aggiunge una riga con `field: \"provider\"` e `result: \"error\"`, quindi verifica `result` prima di considerare una riga come esito del campo.", "items": { "type": "object", "required": [ "field", "label", "provided", "record", "result" ], "properties": { "field": { "type": "string", "enum": [ "identification_number", "full_name", "date_of_birth", "address", "provider" ], "description": "Campo di confronto normalizzato. `provider` non è un campo utente: contrassegna una riga di errore della sorgente." }, "label": { "type": "string", "description": "Etichetta visualizzata per la riga, ad es. `ID number`, `Full name`, `Provider`." }, "provided": { "type": "string", "nullable": true, "description": "Cosa ha digitato l'utente. `null` su una riga di errore `provider`." }, "record": { "type": "string", "nullable": true, "description": "Cosa conteneva la fonte. In una riga di errore `provider`, contiene invece il messaggio di errore." }, "result": { "type": "string", "enum": [ "match", "partial", "no_match", "error" ], "description": "Risultato del confronto per singolo campo. `error` compare solo su una riga `provider` e indica che tale fonte non ha risposto; consideralo come informazione sulla query, mai come una mancata corrispondenza di un campo." } } } }, "registry_portrait": { "type": "string", "format": "uri", "nullable": true, "description": "URL pre-firmato di breve durata per il ritratto restituito dalla fonte. Solo per i quattro registri governativi che ne restituiscono uno (Sudafrica, Nigeria, Argentina, Panama)." }, "face_match_score": { "type": "number", "nullable": true, "description": "Selfie rispetto alla foto del registro, 0-100. Solo se il registro restituisce una foto." } } }, "wallet_verification": { "type": "object", "nullable": true, "description": "Evidenza della credenziale. Presente solo quando `verification_method` è `wallet`; altrimenti `null`.", "properties": { "provider": { "type": "string", "description": "Id del wallet di catalogo, ad es. `mitid`." }, "provider_name": { "type": "string", "nullable": true, "description": "Nome del wallet noto all'utente finale, ad es. `MitID`." }, "issuing_authority": { "type": "string", "nullable": true, "description": "L'autorità responsabile del wallet, ad es. `Danish Agency for Digital Government`." }, "issuing_country": { "type": "string", "description": "Paese ISO 3166-1 alpha-3 in cui è stato offerto il wallet." }, "credential_type": { "type": "string", "nullable": true, "description": "Credenziale presentata dal wallet, ad es. `person_identification`." }, "level_of_assurance": { "type": "string", "enum": [ "low", "substantial", "high" ], "nullable": true, "description": "Il livello di garanzia attestato dal wallet. Un accesso che attesta un livello inferiore a quello richiesto fallisce invece di effettuare un downgrade." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "L'istante di autenticazione del wallet." }, "signature_valid": { "type": "boolean", "nullable": true, "description": "Indica se l'attestazione firmata restituita dal wallet è stata convalidata." }, "attributes": { "type": "object", "additionalProperties": true, "description": "Gli attributi condivisi dal wallet, associati alle chiavi corrispondenti a quelle indicate nella voce di catalogo del wallet." }, "portrait": { "type": "string", "format": "uri", "nullable": true, "description": "URL pre-firmato di breve durata per il ritratto condiviso dal wallet, laddove ne condivida uno." }, "face_match_score": { "type": "number", "nullable": true, "description": "Selfie rispetto alla foto del wallet, 0-100, se il wallet ne condivide una." } } }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Expired" ], "description": "Stato a livello di funzionalità di questo passaggio di verifica dell'identità. Indipendente dallo `status` della sessione di primo livello: una sessione può raggiungere la sua decisione complessiva mentre una singola funzionalità rimane in `In Review`." }, "document_type": { "type": "string", "description": "Tipo di documento d'identità" }, "document_subtype": { "type": "string", "nullable": true, "description": "Codice del sottotipo di documento accettato dalle impostazioni dei documenti del workflow, inclusa la regione del documento ove applicabile. Esempi: `ID_CARD_GENERIC`, `QUEENSLAND_DRIVER_LICENSE_GENERIC`." }, "document_number": { "type": "string", "description": "Numero identificativo del documento" }, "personal_number": { "type": "string", "description": "Numero di identificazione personale" }, "portrait_image": { "type": "string", "format": "uri", "description": "URL dell'immagine del ritratto" }, "front_image": { "type": "string", "format": "uri", "description": "URL dell'immagine del fronte del documento" }, "front_video": { "type": "string", "format": "uri", "description": "URL del video del fronte del documento" }, "back_image": { "type": "string", "format": "uri", "description": "URL dell'immagine del retro del documento" }, "back_video": { "type": "string", "format": "uri", "description": "URL del video del retro del documento" }, "full_front_image": { "type": "string", "format": "uri", "description": "URL dell'immagine completa del fronte del documento" }, "full_back_image": { "type": "string", "format": "uri", "description": "URL dell'immagine completa del retro del documento" }, "front_image_camera_front": { "type": "string", "format": "uri", "description": "URL dell'immagine del fronte del documento acquisita dalla fotocamera frontale" }, "back_image_camera_front": { "type": "string", "format": "uri", "description": "URL dell'immagine del retro del documento acquisita dalla fotocamera frontale" }, "date_of_birth": { "type": "string", "format": "date", "description": "Data di nascita dal documento" }, "age": { "type": "integer", "description": "Età calcolata dalla data di nascita" }, "expiration_date": { "type": "string", "format": "date", "description": "Data di scadenza del documento" }, "date_of_issue": { "type": "string", "format": "date", "description": "Data di emissione del documento" }, "issuing_state": { "type": "string", "description": "Codice ISO dello stato di emissione" }, "issuing_state_name": { "type": "string", "description": "Nome completo dello stato emittente" }, "first_name": { "type": "string", "description": "Nome dal documento" }, "last_name": { "type": "string", "description": "Cognome dal documento" }, "full_name": { "type": "string", "description": "Nome completo dal documento" }, "gender": { "type": "string", "description": "Genere dal documento" }, "address": { "type": "string", "description": "Indirizzo non elaborato dal documento" }, "formatted_address": { "type": "string", "description": "Indirizzo completo formattato" }, "place_of_birth": { "type": "string", "description": "Luogo di nascita dal documento" }, "marital_status": { "type": "string", "description": "Stato civile dal documento" }, "nationality": { "type": "string", "description": "Codice ISO della nazionalità" }, "extra_fields": { "type": "object", "description": "Campi aggiuntivi del documento. Include attributi specifici del documento (ad es. `dl_categories`, `blood_group`, `sponsor`, `employer`, `dl_class_code_b_from`, `dl_class_code_b_to`). Le date di validità delle categorie della patente di guida vengono restituite come `dl_class_code__from` e `dl_class_code__to`, e i codici di restrizione/informazione per categoria (ad es. colonna 12 delle patenti del Regno Unito) come `dl_class_code__notes`. Quando il documento riporta nomi, indirizzo o luogo di nascita in più sistemi di scrittura, questo oggetto include anche le versioni in sistemi di scrittura alternativi di tali campi. L'impostazione del workflow `preferred_characters` (`latin` o `non_latin`) controlla quale sistema di scrittura popola i campi di primo livello (`first_name`, `last_name`, `full_name`, `address`, `place_of_birth`); il sistema di scrittura opposto viene inserito qui come `first_name_non_latin` / `last_name_non_latin` / `full_name_non_latin` / `middle_name_non_latin` / `address_non_latin` / `place_of_birth_non_latin` (quando `preferred_characters` è `latin`) o con suffisso `_latin` (quando `preferred_characters` è `non_latin`). Le chiavi compaiono solo quando l'OCR estrae effettivamente un valore reale in un sistema di scrittura alternativo: un campo il cui valore alternativo è nello stesso sistema di scrittura del set preferito (ad esempio, un campo etichettato in cirillico il cui valore OCR è tornato in omoglifi latini) viene ignorato. Quando `preferred_characters` è `latin` ma il documento contiene solo testo non latino, Didit traslittera i valori estratti ed espone `first_name_latin` / `last_name_latin` / ecc. come fallback.", "additionalProperties": true, "properties": { "dl_categories": { "type": "array", "items": { "type": "string" } }, "blood_group": { "type": "string", "nullable": true }, "first_name_non_latin": { "type": "string", "description": "Nome nel sistema di scrittura non latino quando `preferred_characters=latin` ed è presente una versione non latina sul documento (ad es. `Айна` per un documento d'identità kirghiso)." }, "last_name_non_latin": { "type": "string", "description": "Cognome nel sistema di scrittura non latino quando `preferred_characters=latin` ed è presente una versione non latina sul documento." }, "middle_name_non_latin": { "type": "string", "description": "Secondo nome / patronimico nel sistema di scrittura non latino quando `preferred_characters=latin` e sul documento è presente una versione non latina." }, "full_name_non_latin": { "type": "string", "description": "Nome completo composto nel sistema di scrittura non latino. Ricostruito dai singoli componenti quando sia il nome che il cognome sono disponibili." }, "address_non_latin": { "type": "string", "description": "Indirizzo nel sistema di scrittura non latino quando `preferred_characters=latin` ed è presente una versione non latina sul documento." }, "place_of_birth_non_latin": { "type": "string", "description": "Luogo di nascita nel sistema di scrittura non latino quando `preferred_characters=latin` e una versione non latina è presente sul documento." }, "first_name_latin": { "type": "string", "description": "Nome in caratteri latini. Popolato quando `preferred_characters=non_latin` ed è presente una versione in caratteri latini sul documento oppure — come fallback di traslitterazione — quando `preferred_characters=latin` ma il documento contiene solo testo non latino." }, "last_name_latin": { "type": "string", "description": "Cognome in caratteri latini. Stesse regole di `first_name_latin`." }, "middle_name_latin": { "type": "string", "description": "Secondo nome / patronimico in sistema di scrittura latino. Stesse regole di `first_name_latin`." }, "full_name_latin": { "type": "string", "description": "Nome completo composto in caratteri latini. Sempre ricostruito dai singoli componenti quando sia il nome che il cognome sono disponibili." }, "address_latin": { "type": "string", "description": "Indirizzo nel sistema di scrittura latino. Stesse regole di `first_name_latin`." }, "place_of_birth_latin": { "type": "string", "description": "Luogo di nascita in caratteri latini. Stesse regole di `first_name_latin`." } } }, "mrz": { "type": "object", "nullable": true, "description": "Campi della zona a lettura ottica (MRZ) analizzati ed estratti dal documento. `null` se non è stata rilevata alcuna MRZ.", "properties": { "surname": { "type": "string", "example": "MARTINEZ_families` / `very_high_similarity_plus__families`. Presente solo quando `match_source` è `recovered_high`." } } } }, "browser_version": { "type": "string", "nullable": true }, "os_version": { "type": "string", "nullable": true }, "user_agent": { "type": "string", "nullable": true, "description": "La stringa user agent del browser." }, "accept_language": { "type": "string", "nullable": true, "description": "L'intestazione `Accept-Language` inviata dal browser." }, "session_identifier": { "type": "string", "nullable": true, "description": "Identificatore della sessione di navigazione in cui è stata eseguita la verifica." }, "session_age_ms": { "type": "integer", "nullable": true, "description": "Età di quella sessione di navigazione in millisecondi al momento dell'esecuzione del passaggio." }, "coords_accuracy": { "type": "number", "nullable": true, "description": "Raggio di accuratezza, in metri, delle coordinate segnalate dal dispositivo." }, "raw_device_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Segnali del dispositivo non elaborati raccolti per il passaggio." } } } }, "geolocation_checks": { "type": "array", "nullable": true, "description": "**Array di risultati della verifica della posizione**, uno per ciascun passaggio di verifica della posizione: il tentativo accettato di quel passaggio. `null` fino a quando un passaggio di verifica della posizione non ha prodotto dati. I tentativi precedenti dello stesso passaggio si trovano in `geolocation_attempts`.", "items": { "$ref": "#/components/schemas/GeolocationCheck" } }, "geolocation_attempts": { "type": "array", "nullable": true, "description": "Ogni tentativo di ciascun passaggio di verifica della posizione di questa sessione, dal più vecchio al più recente. I tentativi sostituiti da un nuovo invio vengono omessi. Un workflow che esclude `geolocation_checks` tramite i propri attributi di risposta esclude anche questo elenco.", "items": { "$ref": "#/components/schemas/GeolocationAttempt" } }, "database_validations": { "type": "array", "nullable": true, "description": "**Array di report di Validazione su database** — sempre un array JSON, mai un singolo oggetto `database_validation`. `null` finché almeno un passaggio di validazione su DB non ha prodotto dati. Ciascun elemento è il report completo, inclusi `node_id`, lo `status` a livello di funzionalità, `screened_data`, i `validations[]` per servizio (ciascuno con i relativi `source_data` del registro) e `warnings[]`. I campi `screened_data` e `source_data` variano in base al paese:\n\n**ARG (Argentina)**: screened_data: {document_number, selfie, gender, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, date_of_death, tax_id, tax_id_type, face_match_score, sit_1_since, banks, last_position, highest_position, rejected_checks}. Utilizza la validazione biometrica di confronto facciale RENAPER. Il genere viene dedotto automaticamente dall'analisi del volto o dal nome proprio quando non è presente nel documento (es. patenti di guida)\n\n**BOL (Bolivia)**: screened_data: {document_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender}\n\n**BRA (Brasile)**: screened_data: {tax_number, first_name, last_name, date_of_birth}. source_data include sempre {identification_number, first_name, last_name, date_of_birth, lgpd_minor, minor_under_18, minor_under_16} per corrispondenze CPF riuscite. Le ricerche riuscite per adulti impostano tali flag su false. Il servizio Consulta CPF della Receita Federal può restituire HTTP 422 (minore di 18 anni) o 451 (minore di 16 anni) con dati omessi in conformità alla LGPD; in tali casi source_data imposta i flag per minori su true come opportuno, include il codice di stato HTTP del servizio upstream e la validazione a livello di campo è no_match. Consulta la sezione Brasile del riferimento Database Validation Outcome Codes per l'elenco completo dei codici.\n\n**CHL (Cile)**: screened_data: {personal_number, first_name, last_name, date_of_birth}. source_data: {identification_number, first_name, last_name, date_of_birth, gender}\n\n**COL (Colombia)**: screened_data: {document_number, document_type, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, document_type}\n\n**CRI (Costa Rica)**: screened_data: {personal_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**DOM (Repubblica Dominicana)**: screened_data: {personal_number}. source_data: {identification_number} (restituisce solo valid/invalid)\n\n**ECU (Ecuador)**: screened_data: {personal_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, street, formatted_address, gender, nationality, education, marital_status, spouse, mother_name, father_name, profession}\n\n**ESP (Spagna)**: screened_data: {personal_number, document_type, expiration_date, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, document_type, expiration_date}\n\n**GTM (Guatemala)**: screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**HND (Honduras)**: screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**MEX (Messico)**: screened_data: {personal_number (CURP), first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender, nationality, curp_status, state_of_birth, doc_probatorio, registration_year, registration_state, registration_municipality, num_acta, crip, issuing_state_code, foreign_registry_number, folio_carta, folio_certificado}. Utilizza il registro civile RENAPO. È inoltre disponibile un servizio separato di controllo validità INE per MEX come validazione aggiuntiva una per volta.\n\n**PAN (Panama)**: screened_data: {personal_number, selfie}. source_data: {identification_number}. Utilizza la validazione biometrica SIB\n\n**PER (Perù)**: screened_data: {personal_number (DNI), first_name, last_name}. source_data: {identification_number, first_name, last_name, paternal_name, maternal_name, verification_number, verification_letter}\n\n**PRY (Paraguay)**: screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**SLV (El Salvador)**: screened_data: {document_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**URY (Uruguay)**: screened_data: {personal_number, date_of_birth, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name}\n\n**VEN (Venezuela)**: screened_data: {document_number, first_name, last_name}. source_data: {identification_number, first_name, last_name, full_name, gender, date_of_birth, document_type}", "items": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Identificativo univoco per questo passaggio di validazione su database nel grafo del workflow." }, "issuing_state": { "type": "string", "description": "Codice ISO 3166-1 alpha-3 del paese le cui fonti governative/di registro sono state interrogate (ad es. `BRA`, `MEX`, `ESP`, `NGA`, `IDN`). La Validazione su database copre 60+ paesi nelle Americhe, in Europa, in Africa, in Medio Oriente e in Asia-Pacifico, oltre a fonti multinazionali globali — la copertura si espande regolarmente, quindi considera il valore come un insieme aperto anziché come un'enumerazione fissa." }, "validation_type": { "type": "string", "enum": [ "one_by_one", "two_by_two", "not_enabled" ], "description": "In che modo è stato corroborato il risultato: `one_by_one` (esito da singolo servizio), `two_by_two` (due o più servizi distinti hanno trovato in modo indipendente una corrispondenza esatta con il numero identificativo) o `not_enabled` (salvato quando nessun servizio ha prodotto una corrispondenza utilizzabile). Il valore non è mai `null`. Le modalità di validazione biometrica 2x2 dedicate sono attualmente disponibili per `ECU` e `PER`." }, "screened_data": { "type": "object", "description": "I dati di input utilizzati per la validazione. I campi variano in base al paese: consulta la documentazione di Validazione su database (`/core-technology/database-validation/overview`) per i formati specifici per paese.", "properties": { "last_name": { "type": "string" }, "first_name": { "type": "string" }, "tax_number": { "type": "string", "description": "Brasile: CPF (11 cifre)" }, "personal_number": { "type": "string", "description": "Cile: RUT, DOM: Cédula (11 cifre), ECU: Cédula (10 cifre), ESP: DNI/NIE, MEX: CURP (18 caratteri), PER: DNI (8 cifre), URY: CI" }, "document_number": { "type": "string", "description": "ARG: DNI, BOL: CI, COL: Cédula, GTM: DPI, HND: DNI, PAN: Cédula, PRY: CI, SLV: DUI, VEN: Cédula" }, "date_of_birth": { "type": "string", "format": "date" }, "document_type": { "type": "string", "description": "COL: CC/CE/TI/NIT, ESP: ID/PASSPORT" }, "expiration_date": { "type": "string", "format": "date", "description": "Obbligatorio per ESP" } } }, "validations": { "type": "array", "description": "Una voce per ciascun servizio di registro che ha restituito un payload di validazione. Ciascuna voce identifica il servizio (`service_id`, `service_name`) e contiene il confronto di `validation` per campo, `outcome_code` / `outcome_detail` del servizio quando segnalato, e il record di registro normalizzato in `source_data`.", "items": { "type": "object", "properties": { "service_id": { "type": "string", "description": "Identificatore del servizio di registro che ha prodotto questo risultato di validazione.", "example": "bra_cpf" }, "service_name": { "type": "string", "description": "Nome di facile lettura del servizio di registro.", "example": "Brazil - CPF status check" }, "validation": { "type": "object", "description": "I risultati delle validazioni dei campi.", "properties": { "full_name": { "type": "string", "description": "Risultato del confronto per il nome completo (ad es., 'full_match', 'partial_match', 'no_match')." }, "date_of_birth": { "type": "string", "description": "Risultato del confronto per la data di nascita." }, "identification_number": { "type": "string", "description": "Risultato di corrispondenza per il numero di identificazione." } } }, "outcome_code": { "type": "string", "nullable": true, "description": "Esito leggibile dalla macchina della ricerca nel registro (ad es. `MATCH`, `NO_MATCH`, `PARTIAL_MATCH`, `INCONCLUSIVE`, codici specifici della sorgente). Presente quando il servizio ne segnala uno." }, "outcome_detail": { "type": "string", "nullable": true, "description": "Spiegazione di facile lettura di `outcome_code`, se fornita dal servizio." }, "source_data": { "type": "object", "description": "I dati restituiti dal database governativo. Campi comuni: identification_number, first_name, last_name, full_name, date_of_birth, gender. Campi aggiuntivi per paese: BRA include sempre lgpd_minor, minor_under_18 e minor_under_16 in caso di corrispondenze CPF riuscite; include anche lo stato HTTP upstream quando i dati CPF vengono trattenuti ai sensi dell'LGPD (HTTP 422/451). ECU aggiunge street, formatted_address, nationality, education, marital_status, spouse, mother_name, father_name, profession. PER aggiunge paternal_name, maternal_name, verification_number, verification_letter. ESP aggiunge document_type, expiration_date. VEN/COL aggiungono document_type.", "additionalProperties": true } } } }, "errors": { "type": "array", "description": "Errori restituiti dai servizi del registro durante la validazione, ciascuno contrassegnato con il `service_id` che lo ha generato. **Questa chiave viene omessa completamente in assenza di errori.**", "items": { "type": "object", "description": "L'oggetto di errore del servizio upstream propagato così com'è — le sue chiavi variano in base al servizio (solitamente un messaggio/codice ed eventuali dettagli specifici del provider) — oltre a `service_id` che identifica il servizio che ha generato l'errore.", "properties": { "service_id": { "type": "string", "nullable": true, "description": "Identificatore del servizio di registro che ha generato l'errore." } }, "additionalProperties": true } }, "match_type": { "type": "string", "enum": [ "no_match", "partial_match", "full_match" ], "nullable": true, "description": "L'esito aggregato della corrispondenza tra i servizi interrogati. `null` finché la validazione non è stata valutata." }, "status": { "type": "string", "description": "Stato a livello di funzionalità di questa validazione su database. Indipendente dallo `status` della sessione di primo livello: una sessione può raggiungere la sua decisione complessiva mentre una singola funzionalità rimane in `In Review`.", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACEMATCH", "PROOF_OF_ADDRESS", "PHONE", "EMAIL", "AML", "LOCATION", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "GEOLOCATION", "SIGNATURE" ], "description": "La funzionalità che ha generato questo avviso. Il valore identifica il blocco della funzionalità a cui appartiene l'avviso. L'array degli avvisi di ciascun modulo utilizza in genere il valore corrispondente al proprio modulo (es. `PHONE` all'interno di `phone_verifications[].warnings`), ma l'enum riportato sopra fa fede per tutti gli avvisi delle funzionalità presenti nel payload della decisione." }, "risk": { "type": "string" }, "additional_data": { "type": "object", "nullable": true }, "log_type": { "type": "string" }, "short_description": { "type": "string" }, "long_description": { "type": "string" }, "node_id": { "type": "string", "description": "L'ID del nodo del grafo del workflow che ha generato questo avviso" } } }, "description": "Avvisi relativi alla validazione su database." } } } }, "database_validation_not_performed_reason": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Il motivo per cui una validazione su database configurata non ha prodotto alcun risultato, sotto forma di `{code, message}` più i campi di contesto. Presente solo quando `database_validations` è `null` per un workflow che include il passaggio, consentendoti di distinguere \"il registro ha confermato\" da \"non è stato eseguito nulla\". `null` altrimenti.", "properties": { "code": { "type": "string", "description": "Motivo stabile leggibile da macchina." }, "message": { "type": "string", "description": "Spiegazione di facile lettura." } } }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string", "description": "Chi ha eseguito la revisione. Di solito l'identificativo del revisore della console (la sua email), ma il valore è `\"API Client\"` per gli aggiornamenti di stato effettuati con una chiave API e `\"Unknown\"` quando non è stato possibile risolvere alcun attore; pertanto non analizzare questo campo come un indirizzo email." }, "new_status": { "type": "string" }, "comment": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "assignee": { "type": "object", "nullable": true, "description": "Il revisore della Console a cui è assegnata la sessione, oppure `null` se non è assegnata a nessuno.", "properties": { "email": { "type": "string", "format": "email" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true } } }, "waiting_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando la sessione ha iniziato l'attesa per la revisione. `null` a meno che la sessione non sia `In Review` e la tua applicazione imposti una scadenza di revisione." }, "sla_due_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Termine entro cui la revisione deve essere completata. `null` a meno che la sessione non sia `In Review` e la tua applicazione imposti una scadenza di revisione." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp di creazione della sessione (ISO 8601, UTC)." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp in cui è prevista la scadenza di questa sessione. Impostato sulle sessioni di Verifica degli utenti (KYC) quando è stata configurata una scadenza al momento della creazione (o una volta che lo stato `Approved` attiva il calcolo della scadenza del KYC). `null` per le sessioni senza una scadenza configurata e per le tipologie che non utilizzano la scadenza (ad es. sessioni di Verifica aziendale (KYB) che non hanno mai ricevuto un `expires_at`)." }, "registry_checks": { "type": "array", "nullable": true, "description": "Controlli del registro delle imprese. Presente solo quando `session_kind = business`. Ciascun elemento include l'intero payload del registro delle imprese.", "items": { "type": "object", "description": "Un controllo del registro delle imprese — il payload completo del registro delle imprese arricchito con l'assetto proprietario e gli avvisi. Presente solo quando `session_kind = business`.", "properties": { "status": { "type": "string", "description": "Stato del ciclo di vita della funzionalità." }, "node_id": { "type": "string", "nullable": true }, "data_resolved": { "type": "boolean" }, "company": { "type": "object", "description": "Payload completo del registro delle imprese per l'azienda (record di registro unito a eventuali dati forniti dall'utente o modificati dalla console).", "properties": { "uuid": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "registry_status": { "type": "string", "nullable": true }, "data_resolved": { "type": "boolean" }, "company_name": { "type": "string" }, "registration_number": { "type": "string", "nullable": true }, "country_code": { "type": "string", "description": "Paese di costituzione (ISO 3166-1 alpha-2, ad es. `GB`, `DE`, `US`)." }, "region": { "type": "string", "nullable": true, "description": "Codice di suddivisione ISO 3166-2, se applicabile (ad es. `CA`, `NY` per gli stati degli Stati Uniti)." }, "company_type": { "type": "string", "nullable": true }, "incorporation_date": { "type": "string", "format": "date", "nullable": true }, "registered_address": { "type": "string", "nullable": true }, "tax_number": { "type": "string", "nullable": true }, "risk_level": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "nullable": true }, "verification_status": { "type": "string", "nullable": true }, "is_from_registry": { "type": "boolean" }, "fetch_status": { "type": "string", "nullable": true }, "alternative_names": { "type": "string", "nullable": true, "description": "Denominazioni aziendali alternative, commerciali, precedenti o nella lingua originale sotto forma di testo, se segnalate." }, "nature_of_business": { "type": "string", "nullable": true }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "format": "decimal", "nullable": true, "description": "Importo del capitale sociale/registrato sotto forma di stringa decimale (ad es. `\"100.00\"`), estratto dal deposito presso il registro delle imprese. `null` se non disponibile." }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "Codice valuta ISO 4217 di `registered_capital_amount` (ad es. `\"GBP\"`). `null` quando non disponibile." }, "website": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "legal_entity_identifier": { "type": "string", "nullable": true }, "location_of_registration": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true, "description": "Partita IVA UE, se raccolta durante il passaggio del registro ospitato o modificata successivamente." }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "Risultato della validazione della partita IVA o, qualora non presente, del `tax_number`, al momento dell'invio al registro. `valid` / `invalid`: stabilito dal registro ufficiale del paese (VIES UE, Norvegia, Svizzera, Brasile, Colombia, Costa Rica, Ecuador, Paraguay; per la Polonia anche dal registro IVA nazionale). `format_valid` / `invalid_format`: stabilito dalle regole di formato e cifra di controllo del paese laddove non sia possibile interrogare alcun registro. `could_not_validate`: il registro non era disponibile. `not_applicable`: nessun numero, paese privo di registro o regole, oppure sessione sandbox." }, "vat_validated_number": { "type": "string", "nullable": true, "description": "Il numero verificato, così come noto alla fonte (ad esempio la partita IVA derivata da un SIREN francese o un RSIN olandese). `null` quando non è stato eseguito alcun controllo." }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "La fonte che ha stabilito `vat_validation_status`: un registro ufficiale, oppure `format_rules`. `null` se non è stato eseguito alcun controllo." }, "vat_validated_name": { "type": "string", "nullable": true, "description": "Nome registrato presso la fonte che ha validato il numero, quando ne fornisce uno. Impostato solo quando lo stato è `valid`." }, "vat_validated_address": { "type": "string", "nullable": true, "description": "Indirizzo registrato presso la fonte che ha convalidato il numero, quando ne comunica uno. Impostato solo quando lo stato è `valid`." }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp del controllo. `null` se non è stato eseguito alcun controllo." }, "financial_summary": { "type": "object", "nullable": true }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "designation": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "enum": [ "Approved", "Declined", "Pending" ], "nullable": true }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true }, "first_name": { "type": "string", "nullable": true, "description": "Nome quando esplicitamente riportato dal registro; non dedotto dal nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Cognome quando esplicitamente riportato dal registro." }, "address": { "type": "string", "nullable": true, "description": "Indirizzo dell'amministratore riportato dal registro." }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina dell'amministratore.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data di fine dell'incarico, quando indicata.", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa comunicata dal registro delle imprese. Null se sono noti solo l'anno o il mese di nascita.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Anno di nascita riportato dal registro delle imprese, anche quando la data completa non è disponibile." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mese di nascita riportato dal registro delle imprese. Null se è noto solo l'anno." } } } }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "roles": { "type": "array", "items": { "type": "string" } }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferiore della percentuale di assetto proprietario riportata dal registro. Stringa a formato libero (ad es. `\"25.00\"`, `\"50\"`); usa `effective_ownership_percent` per un valore numerico analizzato." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superiore della percentuale di assetto proprietario indicata dal registro. Stringa a formato libero; usa `effective_ownership_percent` per un valore numerico analizzato." }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "enum": [ "Approved", "Declined", "Pending" ], "nullable": true }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa, se indicata.", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina, se comunicata.", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } } }, "addresses": { "type": "array", "nullable": true, "description": "Ogni indirizzo indicato dal registro, in un formato canonico. Null se non ne indica alcuno.", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "Le attività con cui il registro classifica l'azienda, in formato canonico. Null quando non ne viene indicata alcuna.", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Date di deposito presso il registro delle imprese, se disponibili. Le dichiarazioni annuali e le assemblee generali utilizzano last_annual_return_date e last_agm_date; sono distinte dai bilanci di esercizio." }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "description": "Dati confermati o modificati dall'utente finale." }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true }, "is_editable": { "type": "boolean" }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "Il livello del registro ordinato dal workflow: `basic`, `shareholders` o `ubo`. Anche in `ownership.tier_requested`." }, "registry_tier_delivered": { "type": "string", "nullable": true, "description": "Il livello fornito dal registro e fatturato. Presente anche in `ownership.tier_delivered`." }, "registry_ownership_status": { "type": "string", "nullable": true, "description": "`not_requested`, `pending`, `delivered`, `not_held` o `unavailable`. Anche in `ownership.status`." }, "registry_monitoring": { "type": "object", "nullable": true, "description": "Il monitoraggio del registro più recente per l'azienda, o `null` quando non ne esiste alcuno.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "I campi aziendali che il monitor monitora." } } } } }, "ownership_structure": { "$ref": "#/components/schemas/KYBOwnershipStructure" }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "key_people_checks": { "type": "array", "nullable": true, "description": "Controlli aggregati sulle persone chiave. Presente solo quando `session_kind = business`. Ciascun elemento utilizza la struttura a due contenitori (`registry`, `submitted`, `ubo_kyc_summary`).", "items": { "type": "object", "description": "Controllo aggregato sugli amministratori e sugli UBO dell'azienda. Utilizza la struttura `registry` / `submitted`. Presente solo quando session_kind = business.", "properties": { "status": { "type": "string" }, "node_id": { "type": "string", "nullable": true }, "registry": { "type": "object", "description": "Parti individuate tramite il controllo del registro.", "properties": { "officers": { "type": "array", "description": "Amministratori individuati tramite la verifica nel registro, ciascuno arricchito con lo stato di qualsiasi sessione KYC figlia e screening AML avviati per loro.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Nome completo dell'amministratore come registrato nel registro." }, "designation": { "type": "string", "nullable": true, "description": "Designazione in formato testo libero proveniente dal registro (ad es. `Director`, `Company Secretary`)." }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Ruolo normalizzato dell'esponente aziendale." }, "nationality": { "type": "string", "nullable": true }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina dell'amministratore.", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "Data di fine dell'incarico, quando indicata.", "format": "date" }, "is_active": { "type": "boolean" }, "address": { "type": "string", "nullable": true, "description": "Indirizzo dell'amministratore riportato dal registro." }, "aml_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "nullable": true, "description": "Stato dello Screening AML eseguito per questo funzionario. `null` se non è stato eseguito alcuno Screening AML." }, "kyc_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "Stato del ciclo di vita non elaborato della sessione KYC figlia generata per questo amministratore. Questo è l'enum completo degli stati della sessione (non un set ridotto Approved/Declined/Pending). `null` quando non esiste alcuna sessione KYC figlia." }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL condivisibile della sessione KYC figlia. `null` se non esiste alcuna sessione figlia." }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID sessione della sessione KYC figlia. Passalo a questo stesso endpoint di decisione per recuperare il report KYC completo della persona. `null` quando non esiste alcuna sessione figlia." }, "verification_workflow_type": { "type": "string", "nullable": true, "description": "Tipo di workflow di base del workflow della sessione figlia (ad es. `kyc`). `null` per i workflow basati su grafi o se non esiste alcuna sessione figlia." }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del workflow utilizzato dalla sessione figlia. `null` quando non esiste alcuna sessione figlia." }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "Etichetta di facile lettura del workflow della sessione figlia. `null` se non impostata." }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "Avanzamento per funzionalità della sessione di verifica figlia, ad es. `[{\"feature\": \"ID_VERIFICATION\", \"status\": \"Approved\"}]`. `null` quando la sessione figlia non ha un elenco di funzionalità determinabile.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Nome visualizzato della funzionalità (ad es. `ID_VERIFICATION`, `LIVENESS`, `AML`)." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato a livello di funzionalità all'interno della sessione figlia." } } } }, "didit_internal_id": { "type": "string", "nullable": true, "description": "Identificatore interno stabile dell'individuo verificato dietro la sessione figlia — utile per il collegamento tra sessioni. `null` quando non esiste alcuna sessione figlia o l'utente non è stato ancora risolto." }, "kyc_document_type": { "type": "string", "nullable": true, "description": "Tipo di documento presentato nella sessione KYC figlia (ad es. `P`, `ID`, `DL`). `null` finché la sessione figlia non ha un risultato di verifica dell'identità." }, "kyc_nationality": { "type": "string", "nullable": true, "description": "Nazionalità estratta dal documento nella sessione KYC figlia. `null` finché non è disponibile." }, "kyc_liveness_passed": { "type": "boolean", "nullable": true, "description": "Indica se il controllo della vitalità della sessione KYC figlia è stato superato. `null` quando non è stato eseguito alcun controllo della vitalità." }, "kyc_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora in cui la sessione KYC figlia ha raggiunto lo stato `Approved`. `null` finché la sessione figlia ha qualsiasi altro stato." }, "kyc_aml_categories": { "type": "object", "nullable": true, "description": "Riepilogo per categoria derivato dai riscontri AML della persona. `null` quando non ci sono riscontri.", "properties": { "sanctions": { "type": "string", "enum": [ "match", "clear" ] }, "pep": { "type": "string", "enum": [ "match", "clear" ] }, "adverse_media": { "type": "string", "enum": [ "match", "clear" ] }, "warnings": { "type": "string", "enum": [ "match", "clear" ] } } }, "kyc_notification_sent_at": { "type": "string", "nullable": true, "description": "Timestamp ISO 8601 dell'ultima notifica di invito alla verifica inviata per la sessione figlia di questa persona. `null` se non ne è stata inviata nessuna." }, "first_name": { "type": "string", "nullable": true, "description": "Nome quando esplicitamente riportato dal registro; non dedotto dal nome completo." }, "last_name": { "type": "string", "nullable": true, "description": "Cognome quando esplicitamente riportato dal registro." }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa comunicata dal registro delle imprese. Null se sono noti solo l'anno o il mese di nascita.", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "Anno di nascita riportato dal registro delle imprese, anche quando la data completa non è disponibile." }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "Mese di nascita riportato dal registro delle imprese. Null se è noto solo l'anno." } } } }, "beneficial_owners": { "type": "array", "description": "Titolari effettivi individuati tramite la verifica nel registro, ciascuno arricchito con lo stato di eventuali sessioni KYC figlie e screening AML generati per essi.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Nome completo del titolare effettivo (o ragione sociale per i titolari effettivi persone giuridiche)." }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "Data di nascita completa, se indicata.", "format": "date" }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "roles": { "type": "array", "description": "Nomi dei ruoli ricoperti da questo proprietario, ad es. `[\"ubo\", \"shareholder\"]`.", "items": { "type": "string" } }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "Limite inferiore della percentuale di assetto proprietario riportata dal registro. Stringa a formato libero (ad es. `\"25\"`, `\"25-50%\"`); usa `effective_ownership_percent` per un valore numerico analizzato." }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "Limite superiore della percentuale di assetto proprietario indicata dal registro. Stringa a formato libero; usa `effective_ownership_percent` per un valore numerico analizzato." }, "is_active": { "type": "boolean" }, "aml_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "nullable": true, "description": "Stato dello Screening AML eseguito per questo titolare effettivo. `null` se non è stato eseguito alcuno Screening AML." }, "kyc_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "Stato del ciclo di vita non elaborato della sessione KYC figlia generata per questo titolare effettivo. Questo è l'enum completo degli stati della sessione (non un set ridotto Approved/Declined/Pending). `null` quando non esiste alcuna sessione KYC figlia." }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL condivisibile della sessione KYC figlia. `null` se non esiste alcuna sessione figlia." }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID sessione della sessione KYC figlia. Passalo a questo stesso endpoint di decisione per recuperare il report KYC completo della persona. `null` quando non esiste alcuna sessione figlia." }, "verification_workflow_type": { "type": "string", "nullable": true, "description": "Tipo di workflow di base del workflow della sessione figlia (ad es. `kyc`). `null` per i workflow basati su grafi o se non esiste alcuna sessione figlia." }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del workflow utilizzato dalla sessione figlia. `null` quando non esiste alcuna sessione figlia." }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "Etichetta di facile lettura del workflow della sessione figlia. `null` se non impostata." }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "Avanzamento per funzionalità della sessione di verifica figlia, ad es. `[{\"feature\": \"ID_VERIFICATION\", \"status\": \"Approved\"}]`. `null` quando la sessione figlia non ha un elenco di funzionalità determinabile.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Nome visualizzato della funzionalità (ad es. `ID_VERIFICATION`, `LIVENESS`, `AML`)." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato a livello di funzionalità all'interno della sessione figlia." } } } }, "didit_internal_id": { "type": "string", "nullable": true, "description": "Identificatore interno stabile dell'individuo verificato dietro la sessione figlia — utile per il collegamento tra sessioni. `null` quando non esiste alcuna sessione figlia o l'utente non è stato ancora risolto." }, "kyc_document_type": { "type": "string", "nullable": true, "description": "Tipo di documento presentato nella sessione KYC figlia (ad es. `P`, `ID`, `DL`). `null` finché la sessione figlia non ha un risultato di verifica dell'identità." }, "kyc_nationality": { "type": "string", "nullable": true, "description": "Nazionalità estratta dal documento nella sessione KYC figlia. `null` finché non è disponibile." }, "kyc_liveness_passed": { "type": "boolean", "nullable": true, "description": "Indica se il controllo della vitalità della sessione KYC figlia è stato superato. `null` quando non è stato eseguito alcun controllo della vitalità." }, "kyc_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora in cui la sessione KYC figlia ha raggiunto lo stato `Approved`. `null` finché la sessione figlia ha qualsiasi altro stato." }, "kyc_aml_categories": { "type": "object", "nullable": true, "description": "Riepilogo per categoria derivato dai riscontri AML della persona. `null` quando non ci sono riscontri.", "properties": { "sanctions": { "type": "string", "enum": [ "match", "clear" ] }, "pep": { "type": "string", "enum": [ "match", "clear" ] }, "adverse_media": { "type": "string", "enum": [ "match", "clear" ] }, "warnings": { "type": "string", "enum": [ "match", "clear" ] } } }, "kyc_notification_sent_at": { "type": "string", "nullable": true, "description": "Timestamp ISO 8601 dell'ultima notifica di invito alla verifica inviata per la sessione figlia di questa persona. `null` se non ne è stata inviata nessuna." }, "child_beneficial_owners": { "type": "array", "description": "Per gli UBO aziendali: i titolari effettivi dell'entità proprietaria, come oggetti grezzi estratti dal registro. Array vuoto se non applicabile.", "items": { "type": "object" } }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "Percentuale di assetto proprietario numerica analizzata: il limite massimo quando disponibile, altrimenti il limite minimo. `null` quando non è stato possibile analizzare nessuno dei due limiti." }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "appointment_date": { "type": "string", "nullable": true, "description": "Data di nomina, se comunicata.", "format": "date" } } } } } }, "submitted": { "type": "object", "description": "Parti inviate dall'amministratore aziendale durante il flusso delle persone chiave (righe BusinessParty dove source=USER).", "properties": { "parties": { "type": "array", "items": { "type": "object", "description": "Parte inviata dall'amministratore aziendale tramite il flusso delle persone chiave (source=USER).", "properties": { "uuid": { "type": "string", "format": "uuid" }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "source": { "type": "string", "enum": [ "USER" ], "description": "Sempre `USER` qui: questo bucket contiene solo le parti inserite o confermate dall'utente finale nel flusso delle persone chiave (le persone rilevate dal registro compaiono sotto `registry`)." }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "nationality": { "type": "string", "nullable": true, "description": "Nazionalità per le persone fisiche; paese di costituzione per le controparti aziendali." }, "phone_number": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "position": { "type": "string", "nullable": true, "description": "Titolo professionale / posizione lavorativa in formato testo libero (solo persone)." }, "custom_fields": { "type": "object", "description": "Campi personalizzati definiti dal workflow raccolti per questa parte; le chiavi sono definite dai descrittori di campo per le persone chiave del workflow." }, "is_active": { "type": "boolean" }, "is_skipped": { "type": "boolean", "description": "True quando l'utente finale ha saltato la verifica per questo soggetto (possibile solo se il ruolo consente di saltarla)." }, "requires_verification": { "type": "boolean", "description": "True quando è richiesta una sotto-sessione figlia KYC / KYB per questo soggetto in base alle impostazioni del ruolo e alle soglie di assetto proprietario." }, "roles": { "type": "array", "description": "Tutti i ruoli ricoperti da questa parte, ciascuno con le proprie percentuali di assetto proprietario e di voto. Non esiste alcun campo scalare `role`/`ownership_percent` sulla parte stessa.", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "ownership_percent": { "type": "number", "nullable": true }, "voting_percent": { "type": "number", "nullable": true } } } }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID della sessione KYC figlia per i soggetti fisici che richiedono la verifica. `null` altrimenti." }, "kyc_session_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "Stato del ciclo di vita della sessione KYC figlia. `null` se non è presente alcuna sessione KYC figlia." }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true }, "kyb_sub_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID della sottosessione KYB figlia per i soggetti aziendali che richiedono la verifica. `null` altrimenti." }, "kyb_sub_session_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "Stato del ciclo di vita della sotto-sessione KYB figlia. `null` se non è presente alcuna sotto-sessione." }, "kyb_sub_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL condivisibile della sotto-sessione KYB figlia. `null` se non esiste alcuna sotto-sessione." }, "verification_workflow_type": { "type": "string", "nullable": true, "description": "Tipo di workflow di base del workflow della sessione figlia (viene data priorità alla sessione KYC, con fallback alla sottosessione KYB). `null` per i workflow basati su grafi o se non esiste alcuna sessione figlia." }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID del workflow utilizzato dalla sessione figlia. `null` quando non esiste alcuna sessione figlia." }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "Etichetta di facile lettura del workflow della sessione figlia. `null` se non impostata." }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "Avanzamento per funzionalità della sessione di verifica figlia, ad es. `[{\"feature\": \"ID_VERIFICATION\", \"status\": \"Approved\"}]`. `null` quando la sessione figlia non ha un elenco di funzionalità determinabile.", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "Nome visualizzato della funzionalità (ad es. `ID_VERIFICATION`, `LIVENESS`, `AML`)." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato a livello di funzionalità all'interno della sessione figlia." } } } }, "didit_internal_id": { "type": "string", "nullable": true, "description": "Identificatore interno stabile dell'individuo verificato dietro la sessione figlia. `null` quando non risolto." } } } } } }, "ubo_kyc_summary": { "type": "object", "nullable": true, "description": "Avanzamento aggregato del KYC degli UBO, oppure null quando nessun UBO ha sessioni KYC collegate.", "properties": { "total": { "type": "integer" }, "approved": { "type": "integer" }, "flagged": { "type": "integer", "description": "Gli UBO la cui verifica KYC è stata rifiutata o è in revisione." }, "pending": { "type": "integer" } } }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "document_verifications": { "type": "array", "nullable": true, "description": "Controlli di verifica del documento raggruppati per nodo del workflow. Presenti solo quando `session_kind = business`.", "items": { "type": "object", "description": "Documenti raggruppati per nodo del workflow. Presenti solo quando session_kind = business.", "properties": { "status": { "type": "string" }, "node_id": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "document_type": { "type": "string", "enum": [ "LEGAL_PRESENCE", "COMPANY_DETAILS", "OWNERSHIP_STRUCTURE", "REPRESENTATIVES_AUTHORIZATION", "OTHER" ], "nullable": true, "description": "Gruppo di documenti KYB di alto livello in cui il file è stato classificato. `null` se non è classificato." }, "document_subtype": { "type": "string", "nullable": true, "description": "Sottotipo specifico rilevato tramite OCR (ad es. `CERTIFICATE_OF_INCORPORATION`, `SHAREHOLDER_REGISTRY`); `UNKNOWN` quando l'OCR non è riuscito a classificare il documento con sufficiente affidabilità." }, "document_group": { "type": "string", "enum": [ "LEGAL_PRESENCE", "COMPANY_DETAILS", "OWNERSHIP_STRUCTURE", "REPRESENTATIVES_AUTHORIZATION", "OTHER" ], "nullable": true, "description": "Alias di `document_type` — il nome del gruppo utilizzato da `groups` e `required_groups`." }, "file_url": { "type": "string", "format": "uri", "nullable": true, "description": "Link pre-firmato di breve durata al file caricato. `null` per i segnaposto di richiesta documenti creati dall'analista (`is_requested = true`) che non sono stati ancora soddisfatti." }, "original_filename": { "type": "string", "nullable": true, "description": "Nome del file caricato dall'utente o dall'analista." }, "file_size": { "type": "integer", "nullable": true, "description": "Dimensione del file in byte." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato di verifica per singolo documento." }, "created_at": { "type": "string", "format": "date-time" }, "cross_check_result": { "type": "object", "nullable": true, "description": "Verifica incrociata dei campi del documento estratti tramite OCR rispetto al profilo aziendale del registro delle imprese. Un oggetto con sezioni `critical`, `non_critical` e `people`, ciascuna delle quali associa il nome di un campo (ad es. `company_name`, `registration_number`, `incorporation_date`, `registered_address`) a un record di confronto come `{\"document\": \"...\", \"registry\": \"...\", \"match\": true, \"score\": 0.97}`. `null` quando il documento non conteneva dati OCR o non era presente alcuna azienda nel registro con cui effettuare il confronto." }, "document_metadata": { "type": "object", "nullable": true, "description": "Metadati estratti dal documento aziendale caricato. Quando l'estrazione dei metadati è riuscita, tutte le 16 chiavi sono sempre presenti (i singoli valori sono `null` quando non applicabili al tipo di file); l'intero oggetto è `null` quando non è stato possibile estrarre nulla. Per i PDF, `overlay_manipulation` contiene l'analisi forense del testo in sovrimpressione.", "properties": { "file_size": { "type": "integer", "nullable": true, "description": "Dimensione del documento." }, "content_type": { "type": "string", "nullable": true, "description": "Tipo di contenuto del documento." }, "creation_date": { "type": "string", "nullable": true, "description": "Data in cui il documento è stato creato." }, "modified_date": { "type": "string", "nullable": true, "description": "Data in cui il documento è stato modificato." }, "creator": { "type": "string", "nullable": true, "description": "Strumento/utente di creazione registrato nei metadati del file (`Creator` del PDF)." }, "producer": { "type": "string", "nullable": true, "description": "Software che ha prodotto il file (PDF `Producer`)." }, "software": { "type": "string", "nullable": true, "description": "Software di modifica registrato nei metadati del file." }, "encryption": { "type": "string", "nullable": true, "description": "Schema di crittografia del file, se crittografato." }, "is_signed": { "type": "boolean", "nullable": true, "description": "Indica se il documento contiene una firma digitale." }, "is_tampered": { "type": "boolean", "nullable": true, "description": "Indica se la firma digitale non ha superato la convalida (modifica successiva alla firma)." }, "signature_info": { "type": "object", "nullable": true, "description": "Dettagli della firma o delle firme digitali, se presenti." }, "exif_original_date": { "type": "string", "nullable": true, "description": "Data di acquisizione originale EXIF, per i caricamenti di immagini." }, "exif_digitized_date": { "type": "string", "nullable": true, "description": "Data di digitalizzazione EXIF, per i caricamenti di immagini." }, "processed_by_known_editor": { "type": "boolean", "nullable": true, "description": "Indica se i metadati indicano che il file è stato elaborato con un editor di immagini/PDF noto." }, "has_different_creation_mod_date": { "type": "boolean", "nullable": true, "description": "Indica se le date di creazione e di modifica differiscono — un possibile (ma non conclusivo) segnale di modifica." }, "overlay_manipulation": { "type": "object", "nullable": true, "description": "Analisi forense del PDF per sospetta manipolazione del testo sovrapposto. Null se non è stata trovata alcuna prova di manipolazione del testo sovrapposto o se il documento non era un PDF.", "properties": { "detected": { "type": "boolean", "description": "Indica se sono state rilevate prove di manipolazione del testo sovrapposto." }, "analyzed": { "type": "boolean", "description": "Indica se è stato possibile analizzare il PDF." }, "analysis_incomplete": { "type": "boolean", "description": "Presente e vero solo quando il file non ha potuto essere verificato per intero. Ciò che è stato verificato mantiene i propri risultati dove possibile, e il documento genera l'avviso di sostituzione del testo non comprovata." }, "signals": { "type": "array", "items": { "type": "string" }, "description": "Segnali forensi rilevati, come duplicate_font_subset o glyph_fragmentation." }, "manipulated_regions": { "type": "array", "description": "Aree sospette di manipolazione nelle coordinate della pagina PDF.", "items": { "type": "object", "properties": { "page": { "type": "integer" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "page_width": { "type": "number" }, "page_height": { "type": "number" } } } } } } } }, "description": { "type": "string", "nullable": true, "description": "Etichetta o motivo fornito dall'analista per una richiesta di documento. `null` per i caricamenti regolari." }, "is_requested": { "type": "boolean", "description": "True per i segnaposto di richiesta documenti creati dagli analisti in attesa di caricamento." }, "ocr_data": { "type": "object", "nullable": true }, "is_console_upload": { "type": "boolean", "description": "True per i documenti caricati dalla console anziché dal flusso per l'utente finale. I caricamenti dalla console non modificano mai lo stato aggregato a livello di funzionalità." }, "is_confirmed": { "type": "boolean", "description": "I caricamenti da Console iniziano come `false` e passano a `true` non appena l'amministratore li conferma; i caricamenti dell'utente finale sono sempre `true`." } } } }, "groups": { "type": "object", "description": "Contatori di avanzamento per gruppo indicizzati per nome del gruppo (ad es. legal_presence, ownership_structure).", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "approved": { "type": "integer" }, "pending": { "type": "integer" }, "declined": { "type": "integer" }, "in_review": { "type": "integer" }, "other": { "type": "integer" }, "missing": { "type": "integer", "description": "Segnaposto richiesti per i quali non è ancora stato caricato alcun file." } } } }, "required_groups": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "Indica se la sessione è stata creata da un'applicazione di produzione (`live`) o da un'applicazione sandbox (`sandbox`). Le sessioni sandbox sono gratuite, interamente simulate e non consumano mai crediti." }, "sandbox_scenario": { "type": "string", "nullable": true, "description": "Lo scenario sandbox con cui è stata creata la sessione. `null` per le sessioni di produzione e per le sessioni sandbox create senza di esso." }, "resubmissions": { "type": "array", "description": "Restituito solo con `include=resubmissions`, per sessioni utente e aziendali. Una voce per ogni richiesta di nuovo invio, dalla meno recente alla più recente. Ogni voce include i risultati restituiti dai passaggi reinviati prima della richiesta, in modo che i precedenti invii rimangano leggibili. L'eliminazione della sessione elimina tutti gli invii.", "items": { "type": "object", "properties": { "number": { "type": "integer", "description": "1 per il primo nuovo invio della sessione, 2 per il secondo e così via." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando è stato richiesto il nuovo invio." }, "previous_status": { "type": "string", "description": "Lo stato della sessione immediatamente prima della richiesta." }, "nodes": { "type": "array", "description": "I passaggi del workflow restituiti all'utente.", "items": { "type": "object", "properties": { "node_id": { "type": "string" }, "feature": { "type": "string" } } } }, "reasons": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Il motivo fornito per ogni passaggio, indicizzato per `node_id`." }, "requested_by": { "type": "object", "nullable": true, "description": "Chi ha richiesto il nuovo invio.", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "type": { "type": "string" } } }, "results": { "type": "object", "additionalProperties": true, "description": "Cosa hanno restituito i passaggi inviati nuovamente prima della richiesta, sotto le stesse chiavi e nella stessa struttura dei risultati attuali di questa risposta (`id_verifications`, `nfc_verifications`, `liveness_checks`, `face_matches`, `poa_verifications`, `phone_verifications`, `email_verifications`, `aml_screenings`, `ip_analyses`, `database_validations`, `questionnaire_responses`, `document_ai_documents`, `geolocation_checks`; per le sessioni aziendali anche `document_verifications`). Compaiono solo le chiavi dei passaggi che sono stati reinviati." } } } }, "biometric_consent": { "type": "object", "nullable": true, "description": "Indica se la sessione ha richiesto un consenso biometrico esplicito prima dell'acquisizione del volto, per quale motivo e la prova della risposta. Solo sessioni di Verifica degli utenti (KYC); lo stesso oggetto è presente in `decision` dei webhook di sessione. `null` se la sessione non è mai stata valutata, ad esempio in un workflow senza acquisizione del volto. I campi senza alcun valore registrato sono `null`. Un SDK nativo inferiore a 4.10.0, o che non segnala la propria versione, non può mostrare il passaggio di consenso: le acquisizioni del volto proseguono come prima e una sessione che richiedeva il consenso segnala quindi `status: \"pending\"` con `reason: \"BIOMETRIC_CONSENT_UNSUPPORTED_SDK\"`. Consulta [Consenso biometrico](/it/getting-started/biometric-consent).", "properties": { "required": { "type": "boolean", "description": "Whether the session must collect explicit biometric consent. Never goes back to `false`." }, "trigger": { "type": "string", "nullable": true, "enum": [ "declared_state", "ip_state", "ip_unknown", "document_issuer", "forced", "customer_collected" ], "description": "Il motivo per cui il consenso è richiesto, o come è stato soddisfatto. `declared_state`: hai dichiarato uno stato interessato (`user_state`, o un indirizzo statunitense in `expected_details`). `ip_state`: l'IP della persona si trova in uno stato interessato (Illinois, Texas, Colorado). `ip_unknown`: gli elementi di prova collocano la persona negli Stati Uniti ma non è possibile determinare lo stato (l'IP è negli Stati Uniti senza stato associato, oppure non può essere localizzato mentre i tuoi dettagli o il documento collocano la persona negli Stati Uniti). `document_issuer`: il documento d'identità è stato rilasciato da uno stato interessato. `forced`: la modalità dell'applicazione è Always. `customer_collected`: hai inviato `biometric_consent` durante la creazione della sessione. `null` se non richiesto." }, "status": { "type": "string", "enum": [ "not_required", "pending", "given", "declined" ], "description": "`not_required`; `pending` (richiesto e non fornito: la persona non ha ancora risposto oppure `reason` indica perché non è stato raccolto); `given`; `declined` (è stato registrato un rifiuto e la sessione si è conclusa come `Declined`; attualmente nessuna schermata di Didit propone il rifiuto)." }, "given_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando è stato prestato il consenso. Per `customer_collected`, corrisponde al `given_at` inviato." }, "declined_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando è stato registrato un rifiuto." }, "text_version": { "type": "string", "nullable": true, "description": "ID versione del testo del consenso a cui la persona ha risposto, o di quello che hai inviato." }, "text_hash": { "type": "string", "nullable": true, "description": "SHA-256 (hex) del testo esatto del consenso mostrato, nella lingua in cui è stato visualizzato." }, "locale": { "type": "string", "nullable": true, "description": "Lingua in cui è stato mostrato il testo del consenso." }, "policy_url": { "type": "string", "format": "uri", "nullable": true, "description": "La policy sui dati biometrici a cui rimandava il passaggio di consenso." }, "step": { "type": "string", "nullable": true, "description": "Passaggio del workflow in cui si trovava la sessione quando la persona ha risposto, ad esempio `LIVENESS`." }, "node_id": { "type": "string", "nullable": true, "description": "Nodo del grafo del workflow in cui si trovava la sessione quando la persona ha risposto." }, "ip_address": { "type": "string", "nullable": true, "description": "IP da cui proviene la risposta." }, "ip_country_code": { "type": "string", "nullable": true, "description": "Paese ISO 3166-1 alpha-2 dell'indirizzo IP della risposta." }, "ip_state": { "type": "string", "nullable": true, "description": "Suddivisione ISO 3166-2 dell'IP della risposta, ad esempio `US-IL`." }, "ip_city": { "type": "string", "nullable": true, "description": "Città dell'IP della risposta." }, "user_agent": { "type": "string", "nullable": true, "description": "User agent della richiesta relativa alla risposta." }, "detected_ip_address": { "type": "string", "nullable": true, "description": "L'indirizzo IP della persona da cui è stato valutato l'ultimo requisito. Può differire da `ip_address` se la persona ha risposto da un altro dispositivo." }, "detected_country_code": { "type": "string", "nullable": true, "description": "Paese ISO 3166-1 alpha-2 dell'indirizzo IP rilevato." }, "detected_state": { "type": "string", "nullable": true, "description": "Suddivisione ISO 3166-2 dell'IP rilevato." }, "detected_city": { "type": "string", "nullable": true, "description": "Città dell'IP rilevato." }, "declared_state": { "type": "string", "nullable": true, "description": "Suddivisione ISO 3166-2 che hai dichiarato: `user_state` o lo stato di un indirizzo negli Stati Uniti in `expected_details`." }, "document_state": { "type": "string", "nullable": true, "description": "Suddivisione ISO 3166-2 che ha emesso il documento d'identità, letta durante l'acquisizione del documento." }, "jurisdictions": { "type": "array", "items": { "type": "string" }, "description": "Stati USA (codici USPS, ad esempio `IL`) la cui legge sulla biometria copre la persona. `US` quando le evidenze collocano la persona negli Stati Uniti ma lo stato non è noto. Vuoto se non si applica alcuno stato." }, "retention_months": { "type": "integer", "nullable": true, "description": "Il limite più breve di conservazione biometrica, in mesi, tra le `jurisdictions`. `null` se non se ne applica alcuno." }, "reason": { "type": "string", "nullable": true, "enum": [ "BIOMETRIC_CONSENT_UNSUPPORTED_SDK", "BIOMETRIC_CONSENT_DECLINED" ], "description": "`BIOMETRIC_CONSENT_UNSUPPORTED_SDK`: il consenso era obbligatorio e un SDK nativo inferiore a 4.10.0, o uno che non ha segnalato la propria versione, ha acquisito un volto senza il passaggio del consenso; `status` rimane `pending`, o `given` se la persona ha acconsentito successivamente nel flusso ospitato. `BIOMETRIC_CONSENT_DECLINED`: è stato registrato un rifiuto (sostituisce il motivo dell'SDK). `null` in caso contrario, e sempre `null` quando la sessione non richiedeva il consenso." }, "decline_reason": { "type": "string", "nullable": true, "enum": [ "BIOMETRIC_CONSENT_DECLINED" ], "description": "`BIOMETRIC_CONSENT_DECLINED` quando un rifiuto registrato ha terminato la sessione, altrimenti `null`." }, "face_data_deleted_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora in cui il rifiuto ha eliminato le immagini del volto, i video e i modelli facciali della sessione. `null` a meno che non sia stato registrato un rifiuto." } } }, "investigator": { "$ref": "#/components/schemas/InvestigatorBlock" }, "biometric_retention": { "$ref": "#/components/schemas/BiometricRetention" }, "fraud_check": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Il risultato di una chiamata alla Fraud Check API. `null` per qualsiasi altra sessione." }, "full_session_video": { "type": "string", "format": "uri", "nullable": true, "description": "URL con scadenza della registrazione completa della sessione. Restituito solo quando la tua organizzazione registra il video dell'intera sessione." }, "full_session_video_recorded_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora di registrazione dell'intera sessione. Restituito solo quando la tua organizzazione registra il video dell'intera sessione." } } }, "WorkflowDetail": { "type": "object", "description": "I campi sottostanti sono tipizzati; l'oggetto contiene inoltre ogni altra colonna della configurazione del workflow (attivazione delle funzionalità, soglie, azioni di avviso, documenti consentiti, callback) come proprietà aggiuntive. I campi non applicabili al `workflow_type` sono `null`.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificativo per versione (`settings_uuid`). Ogni versione di un workflow ha il proprio." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Identificatore stabile condiviso da tutte le versioni del workflow. Le sessioni create con esso utilizzano l'ultima versione pubblicata." }, "workflow_label": { "type": "string", "description": "Nome visualizzato del workflow." }, "workflow_type": { "type": "string", "nullable": true, "enum": [ "kyc", "kyb", "adaptive_age_verification", "biometric_authentication", "address_verification", "questionnaire_verification", "email_verification", "phone_verification", null ], "description": "Modello di workflow. `null` per i workflow a grafo creati senza un modello." }, "is_default": { "type": "boolean", "description": "Indica se questo è il workflow predefinito dell'applicazione." }, "is_archived": { "type": "boolean", "description": "I workflow archiviati non possono avviare nuove sessioni." }, "version": { "type": "integer", "description": "Numero di versione all'interno del workflow." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Le versioni in bozza sono modificabili; le versioni pubblicate sono immutabili e utilizzate per le nuove sessioni." }, "published_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando è stata pubblicata questa versione. `null` per le bozze." }, "is_simple_workflow": { "type": "boolean", "description": "`true` quando il workflow non presenta un `workflow_graph` personalizzato." }, "is_editable": { "type": "boolean", "description": "`true` solo per le versioni `draft`." }, "workflow_url": { "type": "string", "format": "uri", "description": "URL pubblico che avvia una sessione con questo workflow." }, "workflow_graph": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Struttura a grafo del workflow (nodi e archi). `null` per i workflow semplici." }, "features": { "type": "string", "description": "Funzionalità abilitate unite con `\" + \"`, ad esempio `\"OCR + LIVENESS\"`." }, "total_price": { "type": "number", "nullable": true, "description": "Prezzo per sessione; per i workflow a grafo, il percorso più costoso." }, "min_price": { "type": "number", "nullable": true, "description": "Prezzo del percorso più economico all'interno del workflow." }, "max_price": { "type": "number", "nullable": true, "description": "Prezzo del percorso più costoso all'interno del workflow." }, "special_add_on_prices": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Prezzi delle funzionalità aggiuntive specifici per l'organizzazione, oppure `null` se non ne è impostato alcuno." }, "max_retry_attempts": { "type": "integer", "description": "Nuovi tentativi consentiti dopo una verifica rifiutata." }, "retry_window_days": { "type": "integer", "nullable": true, "description": "Giorni durante i quali sono consentiti i nuovi tentativi." }, "session_expiration_time": { "type": "integer", "description": "Secondi prima della scadenza di una sessione non completata." }, "questionnaire": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Il questionario associato al workflow, o `null`." }, "kyb_role_settings": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Impostazioni di verifica per ruolo per le persone chiave KYB." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "signature_availability": { "type": "object", "description": "Quali livelli di Firma elettronica possono essere utilizzati per firmare in questo momento. Verificalo prima di impostare `signature_level`. Restituito nei workflow `kyc`, `kyb` e a grafo.", "properties": { "simple": { "type": "boolean", "description": "Simple è sempre disponibile." }, "aes": { "type": "boolean", "description": "Indica se la firma avanzata (FEA) può firmare ora. Finché è `false`, il salvataggio di un nuovo passaggio con `signature_level: \"aes\"` viene rifiutato con `aes_not_available`." }, "qes": { "type": "boolean", "description": "Indica se la firma qualificata (FEQ) può firmare ora. È `false` finché non viene collegato un fornitore qualificato." } } }, "is_bank_verification_enabled": { "type": "boolean", "description": "Indica se un workflow semplice di KYC o KYB esegue la verifica bancaria. Viene eseguita dopo i passaggi di contatto (e la verifica della posizione geografica) e prima della validazione su database, dello screening AML e dell'analisi IP. La verifica bancaria non è ancora disponibile a livello generale: l'attivazione viene rifiutata ovunque non sia abilitata." }, "bank_verification_config": { "type": "object", "additionalProperties": true, "description": "Impostazioni della verifica bancaria di un workflow semplice, con le stesse chiavi accettate da un nodo `BANK_VERIFICATION` (ad esempio `bank_countries` e `bank_method_order`). Le chiavi sconosciute vengono ignorate. Ogni chiave è facoltativa e una chiave assente mantiene il proprio valore predefinito, pertanto `{}` indica tutti i valori predefiniti. Consulta [Impostazioni della verifica bancaria](/it/management-api/workflows/feature-configs#verifica-del-conto-bancario).", "example": {} }, "is_geolocation_enabled": { "type": "boolean", "description": "Indica se un semplice workflow KYC esegue la verifica della posizione geografica. Viene eseguita dopo i passaggi di contatto e prima della verifica bancaria e della validazione su database. I workflow aziendali (KYB) non possono eseguirla." }, "geolocation_config": { "type": "object", "additionalProperties": true, "description": "Impostazioni di verifica della posizione di un workflow semplice, con le stesse chiavi accettate da un nodo `GEOLOCATION` (ad esempio `is_geolocation_geofencing_enabled` e `geolocation_max_attempts`). Le chiavi sconosciute vengono ignorate. Ogni chiave è facoltativa e una chiave assente mantiene il valore predefinito, quindi `{}` indica tutti i valori predefiniti.", "example": {} } }, "additionalProperties": true }, "UserSessionListItem": { "title": "KYC session row (session_kind: user)", "type": "object", "description": "Riga di riepilogo per una sessione di Verifica degli utenti (KYC). I campi di identità (`full_name`, `country`, `document_type`, `portrait_image`, campi di contatto) vengono popolati progressivamente man mano che l'utente completa i passaggi di verifica, e sono `null` fino al termine del passaggio pertinente. Anche i campi soggetti a restrizioni dalla configurazione degli attributi di risposta del workflow vengono restituiti come `null`.", "required": [ "session_id", "session_kind", "session_number", "session_url", "portrait_image", "document_type", "full_name", "country", "status", "vendor_data", "didit_internal_id", "created_at", "features", "phone_number", "email_address", "additional_details" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Identificativo univoco della sessione di verifica. Usalo con `GET /v3/session/{sessionId}/decision/` per recuperare il payload completo della decisione.", "example": "5b3720ed-d429-42ef-b67f-37ea805f48ee" }, "session_kind": { "type": "string", "enum": [ "user" ], "description": "Discriminatore di riga. Sempre `\"user\"` per le righe KYC; le righe di Verifica aziendale (KYB) hanno `\"business\"` e una struttura diversa.", "example": "user" }, "session_number": { "type": "integer", "description": "Numero progressivo intuitivo della sessione all'interno della tua applicazione. Utilizzato anche dal parametro `search` per trovare la sessione.", "example": 720 }, "session_url": { "type": "string", "nullable": true, "description": "URL di verifica ospitato che l'utente finale apre per completare il flusso. `null` quando la sessione non ha un URL ospitato.", "example": "https://verify.didit.me/session/CuXoBYCYVO5Y" }, "portrait_image": { "type": "string", "nullable": true, "description": "URL con scadenza (pre-firmato) del miglior ritratto disponibile: la foto del chip NFC quando disponibile, altrimenti il ritratto del documento d'identità, altrimenti l'immagine di riferimento del rilevamento della vitalità. `null` finché non ne esiste uno. Scarica tempestivamente; il link scade.", "example": "https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=..." }, "document_type": { "type": "string", "nullable": true, "enum": [ "Passport", "Identity Card", "Driver's License", "Residence Permit", "Health Insurance Card", "Tax Card" ], "description": "Tipo leggibile dall'utente del documento d'identità verificato. `null` prima del completamento della verifica del documento, e anche `null` dopo il completamento quando il codice verificato non ha una mappatura di visualizzazione (`SSC`, `WP`, `VISA`, `PSC`, `BC`, `OTHER`). Nota: il parametro di query `document_type` filtra in base ai codici brevi (`P`, `ID`, `DL`, `RP`, ...), non in base a questi valori visualizzati.", "example": "Passport" }, "full_name": { "type": "string", "nullable": true, "description": "Miglior nome completo disponibile per la sessione, risolto nell'ordine: OCR del documento d'identità, dati sottoposti a screening AML, dati sottoposti a validazione su database, documento di prova di residenza, quindi i dati previsti forniti alla creazione della sessione. `null` se nessuno è ancora disponibile.", "example": "Jane Marie Doe" }, "country": { "type": "string", "nullable": true, "description": "Paese ISO 3166-1 alpha-3 associato alla sessione, risolto nell'ordine: stato di emissione del documento d'identità, stato di emissione della validazione su database, stato di emissione della prova di residenza, dati previsti, quindi paese del telefono verificato. Può differire dalla nazionalità.", "example": "ESP" }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Stato complessivo della sessione. Consulta la pagina [Stati di verifica](/it/integration/verification-statuses) per il ciclo di vita.", "example": "Approved" }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore per l'utente finale, restituito esattamente come inviato alla creazione della sessione.", "example": "your-user-id-123" }, "didit_internal_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Identificatore interno Didit del profilo utente verificato associato a questa sessione. Stabile tra più sessioni dello stesso utente; filtrabile tramite il parametro di query `didit_internal_id`.", "example": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp UTC di creazione della sessione.", "example": "2026-06-09T12:26:54.328364Z" }, "features": { "type": "array", "description": "Stato per funzionalità di ogni passaggio di verifica configurato nel workflow della sessione, nell'ordine del workflow.", "items": { "type": "object", "required": [ "feature", "status" ], "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACE_MATCH", "POA", "QUESTIONNAIRE", "EMAIL_VERIFICATION", "PHONE", "AML", "IP_ANALYSIS", "AGE_ESTIMATION", "DATABASE_VALIDATION", "GEOLOCATION" ], "description": "Identificatore della funzionalità di verifica.", "example": "ID_VERIFICATION" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato di questa funzionalità. `Not Finished` finché il passaggio non viene completato.", "example": "Approved" } } } }, "phone_number": { "type": "object", "nullable": true, "description": "Telefono associato alla sessione: il telefono verificato se la verifica telefonica è stata eseguita, altrimenti il telefono di contatto fornito alla creazione della sessione. `null` se nessuno dei due è presente.", "required": [ "number", "is_verified" ], "properties": { "number": { "type": "string", "description": "Numero di telefono in formato E.164.", "example": "+14155552671" }, "is_verified": { "type": "boolean", "description": "`true` solo quando la funzionalità di verifica telefonica ha approvato questo numero.", "example": true } } }, "email_address": { "type": "object", "nullable": true, "description": "Email associata alla sessione: l'email verificata se la verifica email è stata eseguita, altrimenti l'email di contatto fornita al momento della creazione della sessione. `null` se nessuna delle due è presente.", "required": [ "email", "is_verified" ], "properties": { "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "is_verified": { "type": "boolean", "description": "`true` solo quando la funzionalità di verifica email ha approvato questo indirizzo.", "example": true } } }, "additional_details": { "type": "object", "nullable": true, "description": "Dati extra compatti per funzionalità. Solo le funzionalità che hanno generato dati compaiono come chiavi; `null` se nessuna funzionalità ha generato dati extra. I campi esclusi dalla configurazione degli attributi della risposta del workflow vengono omessi.", "properties": { "aml": { "type": "object", "description": "Presente quando è stato eseguito lo screening AML.", "properties": { "total_hits": { "type": "integer", "description": "Numero di corrispondenze dello screening AML.", "example": 0 }, "entity_type": { "type": "string", "description": "Tipo di entità sottoposta a screening.", "example": "person" }, "is_adverse_media_fetched": { "type": "boolean", "example": false }, "screened_data": { "type": "object", "description": "Sottoinsieme dei dati sottoposti a screening. Vengono incluse solo le chiavi non vuote.", "properties": { "nationality": { "type": "string", "example": "ESP" }, "document_number": { "type": "string", "example": "XX1234567" }, "date_of_birth": { "type": "string", "example": "1990-05-21" } } } } }, "database_validation": { "type": "object", "description": "Presente quando è stata eseguita la validazione su database.", "properties": { "validation_type": { "type": "string", "example": "DOCUMENT_VALIDATION" }, "match_type": { "type": "string", "example": "FULL_MATCH" }, "identification_number": { "type": "string", "description": "Numero fiscale, personale o del documento che è stato convalidato (il primo disponibile).", "example": "12345678Z" } } }, "poa": { "type": "object", "description": "Presente quando è stata eseguita la prova di residenza.", "properties": { "document_type": { "type": "string", "example": "UTILITY_BILL" }, "issuer": { "type": "string", "example": "Energy Co" }, "address": { "type": "string", "example": "Calle Mayor 1, 28013 Madrid" }, "name_on_document": { "type": "string", "example": "Jane Marie Doe" } } }, "liveness": { "type": "object", "description": "Presente quando è stato eseguito il rilevamento della vitalità.", "properties": { "method": { "type": "string", "example": "PASSIVE" }, "score": { "type": "number", "description": "Punteggio di affidabilità del rilevamento della vitalità, arrotondato a 2 decimali.", "example": 0.98 } } }, "face_match": { "type": "object", "description": "Presente quando è stato eseguito il confronto facciale.", "properties": { "score": { "type": "number", "description": "Punteggio di somiglianza del confronto facciale, arrotondato a 2 decimali.", "example": 0.95 }, "source_image": { "type": "string", "description": "URL con scadenza (pre-firmato) dell'immagine del volto sorgente.", "example": "https:///faces/source.jpg?X-Amz-Expires=3600&..." }, "target_image": { "type": "string", "description": "URL con scadenza (pre-firmato) dell'immagine del volto target.", "example": "https:///faces/target.jpg?X-Amz-Expires=3600&..." } } }, "phone_verification": { "type": "object", "description": "Presente quando è stata eseguita la verifica telefonica.", "properties": { "country_code": { "type": "string", "description": "Paese ISO 3166-1 alpha-2 del numero di telefono.", "example": "US" }, "is_temporary": { "type": "boolean", "example": false }, "is_ported": { "type": "boolean", "example": false }, "is_blocked": { "type": "boolean", "example": false } } }, "email_verification": { "type": "object", "description": "Presente quando è stata eseguita la verifica email.", "properties": { "is_breached": { "type": "boolean", "example": false }, "is_disposable": { "type": "boolean", "example": false }, "is_undeliverable": { "type": "boolean", "example": false }, "is_blocklisted": { "type": "boolean", "example": false } } } } }, "assignee": { "type": "object", "nullable": true, "description": "Il revisore della Console a cui è assegnata la sessione, oppure `null` se non è assegnata a nessuno.", "properties": { "email": { "type": "string", "format": "email" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true } } }, "waiting_since": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando la sessione ha iniziato l'attesa per la revisione. `null` a meno che la sessione non sia `In Review`." }, "sla_due_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Termine entro cui la revisione deve essere completata, in base alla scadenza di revisione impostata per la tua applicazione nella Console. `null` a meno che la sessione non sia `In Review` e sia impostata una scadenza." }, "top_warnings": { "type": "array", "description": "Al massimo alcuni degli avvisi più importanti della sessione, per una rapida valutazione iniziale. L'elenco completo si trova nella decisione.", "items": { "type": "object", "properties": { "risk": { "type": "string", "description": "Codice dell'avviso, ad esempio `FACE_MATCH_LOW_SIMILARITY`." }, "feature": { "type": "string", "description": "La funzionalità che lo ha generato." }, "log_type": { "type": "string", "nullable": true, "description": "`error` o `warning`; `null` per una voce legacy." }, "short_description": { "type": "string" } } } }, "warnings_count": { "type": "integer", "description": "Numero di avvisi presenti nella sessione." } } }, "BusinessSessionListItem": { "title": "KYB session row (session_kind: business)", "type": "object", "description": "Riga di riepilogo per una sessione di Verifica aziendale (KYB). Restituita solo quando `session_kind` è `business` o `all`.", "required": [ "session_id", "session_kind", "session_number", "status", "vendor_data", "created_at", "workflow_id", "workflow_type", "workflow_label", "company_name", "registration_number", "country" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "Identificativo univoco della sessione di verifica aziendale.", "example": "8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52" }, "session_kind": { "type": "string", "enum": [ "business" ], "description": "Discriminatore di riga. Sempre `\"business\"` per le righe KYB.", "example": "business" }, "session_number": { "type": "integer", "description": "Numero progressivo di facile lettura della sessione aziendale all'interno della tua applicazione. Numerato indipendentemente dalle sessioni KYC.", "example": 42 }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Stato complessivo della sessione. Consulta la pagina [Stati di verifica](/it/integration/verification-statuses).", "example": "Approved" }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo identificatore per l'azienda, restituito esattamente come inviato alla creazione della sessione.", "example": "your-company-id-77" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp UTC di creazione della sessione.", "example": "2026-06-08T09:14:02.118450Z" }, "workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Identificatore del workflow con cui è stata creata questa sessione.", "example": "9f9b1234-aaaa-bbbb-cccc-1234567890ab" }, "workflow_type": { "type": "string", "nullable": true, "description": "Tipo di workflow. `kyb` per i workflow aziendali.", "example": "kyb" }, "workflow_label": { "type": "string", "nullable": true, "description": "Nome visualizzato del workflow.", "example": "Standard KYB" }, "company_name": { "type": "string", "nullable": true, "description": "Nome dell'azienda sottoposta a verifica, ricavato dall'azienda del registro delle imprese collegata alla sessione. `null` finché non viene selezionata un'azienda.", "example": "Acme Holdings S.L." }, "registration_number": { "type": "string", "nullable": true, "description": "Numero di registrazione aziendale proveniente dall'azienda del registro collegata alla sessione.", "example": "B12345678" }, "country": { "type": "string", "nullable": true, "description": "Codice del paese dell'azienda nel registro collegata alla sessione.", "example": "ES" } } }, "TransactionVerificationSessionAction": { "title": "Verification session", "type": "object", "properties": { "type": { "type": "string", "enum": [ "verification_session" ] }, "url": { "type": "string", "format": "uri", "description": "URL di verifica ospitato da aprire per l'utente finale." }, "session_id": { "type": "string", "format": "uuid", "description": "ID della sessione di verifica." }, "session_token": { "type": "string", "description": "Token di sessione, utilizzato dagli SDK per dispositivi mobili per avviare il flusso in modo nativo." }, "status": { "type": "string", "description": "Stato della sessione di verifica." } }, "required": [ "type", "url" ] }, "TransactionWalletOwnershipAction": { "title": "Wallet ownership", "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet_ownership" ] }, "url": { "type": "string", "format": "uri", "description": "URL del widget ospitato per la titolarità del wallet. Aprilo in una vera interfaccia browser: su mobile usa SFSafariViewController o un Chrome Custom Tab, mai una webview integrata." }, "widget_session_id": { "type": "string", "format": "uuid", "description": "ID di sessione del widget di titolarità del wallet." }, "expires_at": { "type": "string", "format": "date-time", "description": "Quando scade la sessione del widget." } }, "required": [ "type", "url" ] }, "TransactionRuleActionAddScore": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "add_score" ] }, "value": { "type": "integer", "description": "Punti aggiunti al punteggio di rischio della transazione. Possono essere negativi." } }, "description": "Aggiungi punti al punteggio di rischio cumulativo della transazione; il totale determina lo stato tramite le soglie di revisione/rifiuto dell'applicazione." }, "TransactionRuleActionChangeStatus": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "change_status" ] }, "value": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Stato da impostare immediatamente, a prescindere dal punteggio. Chiave alias: status." }, "workflow_id": { "type": "string", "format": "uuid", "description": "OBBLIGATORIO quando il valore è AWAITING_USER: il workflow di verifica che il soggetto è invitato a completare. Chiave alias: remediation_workflow_id. Didit crea una sessione di correzione ospitata per il soggetto quando la regola si attiva." } }, "description": "Imposta direttamente lo stato della transazione. DECLINED prevale sempre tra le regole corrispondenti." }, "TransactionRuleActionAddTags": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "add_tags" ] }, "tag_uuid": { "type": "string", "format": "uuid", "description": "Tag dell'applicazione esistente da associare." }, "tag_name": { "type": "string", "description": "Nome del tag da associare; creato al primo utilizzo (salvato in maiuscolo). Fornisci tag_uuid o tag_name." }, "tag_color": { "type": "string", "description": "Colore esadecimale utilizzato quando tag_name crea un nuovo tag, ad es. #007AFE." } }, "description": "Collega un tag dell'applicazione alla transazione corrispondente." }, "TransactionRuleActionAddNote": { "type": "object", "required": [ "type", "note" ], "properties": { "type": { "type": "string", "enum": [ "add_note" ] }, "note": { "type": "string", "description": "Testo della nota allegato alla transazione (autore: Rule Engine). Alias chiave: valore." } }, "description": "Collega una nota automatica dell'analista alla transazione corrispondente." }, "TransactionRuleActionAddToList": { "type": "object", "required": [ "type", "list_id" ], "properties": { "type": { "type": "string", "enum": [ "add_to_list" ] }, "list_id": { "type": "string", "format": "uuid", "description": "Elenco a cui aggiungere il vendor_data del soggetto." } }, "description": "Aggiungi il vendor_data del soggetto a una blocklist, lista consentita o lista personalizzata." }, "TransactionRuleActionOpenCase": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "open_case" ] }, "blueprint": { "type": "string", "format": "uuid", "description": "UUID del blueprint del caso; il valore predefinito è il blueprint predefinito dell'applicazione." }, "grouping": { "type": "string", "enum": [ "by_applicant", "by_rule_and_applicant" ], "description": "Indica se le corrispondenze ripetute vengono aggregate in un unico caso per richiedente o uno per regola+richiedente." }, "attach_matched_transaction": { "type": "boolean", "description": "Collega la transazione corrispondente al caso." } }, "description": "Apri (o aggiungi a) un caso di indagine. Viene applicata solo la prima azione open_case su una regola." }, "KYBRegistrySearchResults": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "kyb_response_id": { "type": "string", "nullable": true, "description": "Identificatore per questo candidato — passalo a `POST /v3/kyb/select/` per recuperare il profilo completo. Effimero e limitato all'ambito di questa ricerca: non memorizzarlo a lungo termine; effettua nuovamente la ricerca per ottenerne uno nuovo.", "example": "69aeeb95febb0f1704042259" }, "name": { "type": "string", "nullable": true, "description": "Ragione sociale registrata.", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "description": "Numero di registrazione nel registro delle imprese.", "example": "00445790" }, "status": { "type": "string", "nullable": true, "description": "Stato normalizzato dell'azienda nel registro delle imprese (ad es. `active`, `dissolved`, `inactive`, `struck off`).", "example": "active" }, "type": { "type": "string", "nullable": true, "description": "Forma giuridica indicata dal registro.", "example": "Public Limited Company" }, "registered_address": { "type": "string", "nullable": true, "description": "Sede legale del candidato, quando il registro ne restituisce una. Utilizzala, insieme al numero di registrazione, per distinguere aziende con lo stesso nome: negli Stati Uniti un candidato può essere registrato nello stato in cui l'azienda opera anziché in quello che hai cercato.", "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA" }, "risk_level": { "type": "string", "nullable": true, "description": "Livello di rischio riportato dal registro delle imprese, se disponibile. Di solito `null` al momento della ricerca." }, "fetch_status": { "type": "string", "nullable": true, "description": "Sempre `pending` per i candidati di ricerca: il profilo aziendale completo viene recuperato (e fatturato) solo quando selezioni il candidato.", "example": "pending" } } }, "description": "Elenco deduplicato dei candidati. Vuoto quando `search_resolved=false` (modalità webhook) o quando non ci sono corrispondenze." }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Numero di candidati restituiti." }, "page": { "type": "integer" }, "per_page": { "type": "integer", "example": 25 } } }, "search_status": { "type": "string", "nullable": true, "enum": [ "pending", "resolved" ], "description": "Stato del ciclo di vita della ricerca nel registro delle imprese." }, "search_resolved": { "type": "boolean", "description": "`true` quando la lista dei candidati è definitiva." } } }, "KYBRegistryCandidateRequest": { "type": "object", "required": [ "kyb_response_id" ], "properties": { "kyb_response_id": { "type": "string", "maxLength": 1024, "description": "Handle del candidato da `POST /v3/kyb/search/` (`kyb_registry.companies[].kyb_response_id`). Effimero: usalo poco dopo la ricerca che lo ha generato. Gli handle possono essere lunghi, quindi memorizza e invia il valore esattamente come restituito, senza troncarlo o presumere una lunghezza.", "example": "69aeeb95febb0f1704042259" }, "vendor_data": { "type": "string", "description": "Il tuo identificatore per questa azienda; restituito nella risposta e memorizzato con la sessione aziendale." }, "metadata": { "type": "object", "nullable": true, "description": "JSON a struttura libera memorizzato con la sessione aziendale e restituito nella risposta." }, "save_api_request": { "type": "boolean", "default": true, "description": "Deve essere `true` (valore predefinito). Le selezioni dal registro KYB vengono sempre salvate per consentire il tracciamento della fatturazione e del recupero; `false` restituisce `400`." } } }, "WebhookEventEnvelope": { "type": "object", "description": "Campi che Didit aggiunge a ogni consegna di webhook firmata, indipendentemente dal tipo di evento. Leggi `webhook_type` per sapere quale payload hai ricevuto.", "required": [ "event_id", "webhook_type", "timestamp", "created_at", "application_id", "environment" ], "properties": { "event_id": { "type": "string", "format": "uuid", "description": "Identificatore dell'evento. Ogni destinazione riceve lo stesso valore e una riconsegna lo mantiene, quindi usalo per la deduplicazione." }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "timestamp": { "type": "integer", "description": "Ora Unix in secondi in cui questa consegna è stata firmata. Uguale all'intestazione `X-Timestamp`; una nuova consegna riporta un nuovo valore." }, "created_at": { "type": "integer", "description": "Ora Unix in secondi della modifica che ha generato l'evento." }, "application_id": { "type": "string", "format": "uuid", "description": "L'applicazione a cui appartiene l'evento." }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "`sandbox` per sessioni e applicazioni sandbox, altrimenti `live`." } } }, "SessionWebhookEventData": { "type": "object", "description": "Campi `status.updated` e `data.updated` della sessione. I campi opzionali vengono omessi, mai inviati come `null`, quando non sono applicabili. Le sessioni aziendali (KYB) aggiungono `business_session_id`, `session_kind` e `vendor_business_id`.", "required": [ "session_id", "status", "sandbox_scenario" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "La sessione di verifica." }, "business_session_id": { "type": "string", "format": "uuid", "description": "Solo sessioni aziendali (KYB): lo stesso valore di `session_id`." }, "session_kind": { "type": "string", "enum": [ "business" ], "description": "Solo sessioni aziendali (KYB). Gli eventi delle sessioni utente (KYC) non contengono un `session_kind` di primo livello; leggi invece `decision.session_kind`." }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Stato della sessione dopo la modifica." }, "trigger": { "type": "string", "description": "Presente quando l'evento non è stato generato dal flusso di verifica stesso, ad esempio `manual_review`, `manual_step_update`, `ongoing_monitoring`, `webhook_reconciliation` (un `status.updated` reinviato perché il primo webhook finale non è mai stato creato, quindi potresti ricevere un secondo evento per una decisione già ottenuta: deduplica in base a `session_id` e `status`), `manual_webhook_recovery`, `kyb_registry_change`, `biometric_retention` (un `data.updated` inviato quando i dati biometrici acquisiti dal vivo durante la sessione vengono cancellati come programmato) o una modifica `console_*` come `console_registry_edit`, `console_key_people_skip` o `console_key_people_regenerate`." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Il workflow della sessione. Omesso quando la sessione non ne ha alcuno." }, "workflow_version": { "type": "integer", "description": "Versione del workflow eseguita dalla sessione. Inviata insieme a `workflow_id`." }, "vendor_data": { "type": "string", "description": "Il tuo `vendor_data` per la sessione. Omesso se vuoto." }, "vendor_business_id": { "type": "string", "description": "Solo sessioni aziendali (KYB): l'azienda a cui appartiene la sessione. È omessa quando assente." }, "metadata": { "type": "object", "additionalProperties": true, "description": "I `metadata` della tua sessione. Omessi se vuoti." }, "decision": { "$ref": "#/components/schemas/SessionDecision" }, "resubmit_info": { "type": "object", "description": "Solo quando `status` è `Resubmitted`: i passaggi che l'utente deve ripetere e il relativo motivo.", "required": [ "nodes_to_resubmit", "reasons" ], "properties": { "nodes_to_resubmit": { "type": "array", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "Identificativo del nodo così come appare nella definizione del workflow della sessione (ad esempio `feature_ocr`, `feature_liveness`).", "example": "feature_poa" }, "feature": { "type": "string", "description": "Tipo di funzionalità del nodo, ad esempio `OCR`, `LIVENESS` o `PROOF_OF_ADDRESS`.", "example": "PROOF_OF_ADDRESS" } } }, "description": "Passaggi del workflow che l'utente deve ripetere. Le stesse voci `{node_id, feature}` di `nodes_to_resubmit` in [Aggiorna stato](#patch-/v3/session/-sessionId-/update-status/)." }, "reasons": { "type": "object", "additionalProperties": true, "description": "Motivo per `node_id` in `nodes_to_resubmit`." } } }, "sandbox_scenario": { "type": "string", "nullable": true, "description": "L'esito simulato configurato in una sessione sandbox, oppure `null`. Sempre `null` per le sessioni di produzione." } } }, "SessionStatusUpdatedEvent": { "description": "Una sessione di verifica ha modificato lo stato. `decision` viene inviata solo per `Approved`, `Declined`, `In Review` e `Abandoned`; ha la forma di `GET /v3/session/{sessionId}/decision/` per le destinazioni sulla versione 3 del webhook (quella predefinita), e la forma ridotta precedente per le destinazioni di versione 1 o 2. Le sessioni aziendali ricevono sempre la decisione aziendale di versione 3.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "$ref": "#/components/schemas/SessionWebhookEventData" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "status.updated" ], "description": "Sempre `status.updated`." } }, "required": [ "webhook_type" ] } ] }, "SessionDataUpdatedEvent": { "description": "I dati di una sessione di verifica sono cambiati senza una modifica di stato, ad esempio dopo una modifica durante la revisione manuale, l'override di un passaggio o un nuovo screening del monitoraggio continuo. `decision` viene inviato solo per `Approved`, `Declined`, `In Review` e `Abandoned`; ha la forma di `GET /v3/session/{sessionId}/decision/` per le destinazioni con webhook versione 3 (predefinita), e la forma ridotta precedente per le destinazioni con versione 1 o 2. Le sessioni aziendali ricevono sempre la decisione aziendale della versione 3.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "$ref": "#/components/schemas/SessionWebhookEventData" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "data.updated" ], "description": "Sempre `data.updated`." } }, "required": [ "webhook_type" ] } ] }, "UserStatusUpdatedEvent": { "description": "Un utente ha modificato lo stato. Non viene inviato quando l'utente viene creato.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "user.status.updated" ], "description": "Sempre `user.status.updated`." }, "vendor_user_id": { "type": "string", "format": "uuid", "description": "L'utente a cui si riferisce l'evento." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo `vendor_data` per l'utente, oppure `null`." }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Stato dell'utente dopo la modifica." }, "previous_status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Stato prima della modifica." } }, "required": [ "webhook_type", "vendor_user_id", "vendor_data", "status", "previous_status" ] } ] }, "UserDataUpdatedEvent": { "description": "I campi di un utente sono cambiati. Non viene inviato quando l'utente viene creato. Un singolo salvataggio può produrre sia un evento di stato sia un evento di dati.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "user.data.updated" ], "description": "Sempre `user.data.updated`." }, "vendor_user_id": { "type": "string", "format": "uuid", "description": "L'utente a cui si riferisce l'evento." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo `vendor_data` per l'utente, oppure `null`." }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Stato dell'utente dopo la modifica." }, "changed_fields": { "type": "array", "items": { "type": "string", "enum": [ "vendor_data", "display_name", "full_name", "date_of_birth", "metadata", "portrait_image", "issuing_states", "approved_emails", "approved_phones", "features", "session_count", "approved_count", "declined_count", "in_review_count", "first_session_at", "last_session_at" ] }, "description": "Nomi dei campi modificati." }, "changes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "previous": { "nullable": true, "description": "Valore prima della modifica. Le date sono stringhe ISO 8601." }, "current": { "nullable": true, "description": "Valore dopo la modifica. Le date sono stringhe ISO 8601." } } }, "description": "Valore precedente e attuale di ogni campo modificato, indicizzati per nome del campo. I valori possono essere dati personali (nomi, date di nascita, link al ritratto, email, numeri di telefono); gestiscili di conseguenza." } }, "required": [ "webhook_type", "vendor_user_id", "vendor_data", "status", "changed_fields", "changes" ] } ] }, "BusinessStatusUpdatedEvent": { "description": "Un'azienda ha cambiato stato. Non viene inviato al momento della creazione dell'azienda.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "business.status.updated" ], "description": "Sempre `business.status.updated`." }, "vendor_business_id": { "type": "string", "format": "uuid", "description": "L'azienda a cui si riferisce l'evento." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo `vendor_data` per l'azienda, oppure `null`." }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Stato dell'azienda dopo la modifica." }, "previous_status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Stato prima della modifica." } }, "required": [ "webhook_type", "vendor_business_id", "vendor_data", "status", "previous_status" ] } ] }, "BusinessDataUpdatedEvent": { "description": "I campi di un'azienda sono cambiati. Non viene inviato quando l'azienda viene creata. Un singolo salvataggio può produrre sia un evento di stato sia un evento di dati.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "business.data.updated" ], "description": "Sempre `business.data.updated`." }, "vendor_business_id": { "type": "string", "format": "uuid", "description": "L'azienda a cui si riferisce l'evento." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo `vendor_data` per l'azienda, oppure `null`." }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "Stato dell'azienda dopo la modifica." }, "changed_fields": { "type": "array", "items": { "type": "string", "enum": [ "vendor_data", "display_name", "metadata", "legal_name", "registration_number", "country_code", "session_count", "approved_count", "declined_count", "in_review_count", "features", "first_session_at", "last_session_at" ] }, "description": "Nomi dei campi modificati." }, "changes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "previous": { "nullable": true, "description": "Valore prima della modifica. Le date sono stringhe ISO 8601." }, "current": { "nullable": true, "description": "Valore dopo la modifica. Le date sono stringhe ISO 8601." } } }, "description": "Valore precedente e attuale di ogni campo modificato, indicizzati per nome del campo." } }, "required": [ "webhook_type", "vendor_business_id", "vendor_data", "status", "changed_fields", "changes" ] } ] }, "TransactionCreatedEvent": { "description": "Una transazione è stata creata e sottoposta a screening. Inviato solo per le applicazioni in produzione.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "transaction.created" ], "description": "Sempre `transaction.created`." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Identificatore Didit della transazione." }, "txn_id": { "type": "string", "nullable": true, "description": "Il `transaction_id` fornito al momento della creazione, oppure `null`." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Stato del monitoraggio dopo la modifica." }, "score": { "type": "integer", "description": "Punteggio di rischio accumulato dalle regole." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "Gravità del rischio, oppure `null` finché una regola o un provider non ne imposta una." }, "amount": { "type": "string", "description": "Importo della transazione come stringa decimale. A differenza dell'API non è normalizzato, quindi può contenere zeri finali (fino a 18 cifre decimali)." }, "currency": { "type": "string", "description": "Codice valuta o simbolo dell'asset crypto di `amount`." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direzione rispetto al soggetto." }, "action_required": { "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/TransactionVerificationSessionAction" }, { "$ref": "#/components/schemas/TransactionWalletOwnershipAction" } ], "discriminator": { "propertyName": "type", "mapping": { "verification_session": "#/components/schemas/TransactionVerificationSessionAction", "wallet_ownership": "#/components/schemas/TransactionWalletOwnershipAction" } }, "description": "Azione dell'utente finale in sospeso, oppure `null`. Stesso oggetto di `action_required` nella transazione; `session_token` è una credenziale, quindi non registrarlo mai nei log." } }, "required": [ "webhook_type", "transaction_id", "txn_id", "status", "score", "severity", "amount", "currency", "direction", "action_required" ] } ] }, "TransactionStatusUpdatedEvent": { "description": "Una transazione ha cambiato stato, in seguito a una regola, a una revisione o a un'azione dell'utente finale. Inviato solo per le applicazioni in produzione.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "transaction.status.updated" ], "description": "Sempre `transaction.status.updated`." }, "transaction_id": { "type": "string", "format": "uuid", "description": "Identificatore Didit della transazione." }, "txn_id": { "type": "string", "nullable": true, "description": "Il `transaction_id` fornito al momento della creazione, oppure `null`." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Stato del monitoraggio dopo la modifica." }, "score": { "type": "integer", "description": "Punteggio di rischio accumulato dalle regole." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "Gravità del rischio, oppure `null` finché una regola o un provider non ne imposta una." }, "amount": { "type": "string", "description": "Importo della transazione come stringa decimale. A differenza dell'API non è normalizzato, quindi può contenere zeri finali (fino a 18 cifre decimali)." }, "currency": { "type": "string", "description": "Codice valuta o simbolo dell'asset crypto di `amount`." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direzione rispetto al soggetto." }, "action_required": { "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/TransactionVerificationSessionAction" }, { "$ref": "#/components/schemas/TransactionWalletOwnershipAction" } ], "discriminator": { "propertyName": "type", "mapping": { "verification_session": "#/components/schemas/TransactionVerificationSessionAction", "wallet_ownership": "#/components/schemas/TransactionWalletOwnershipAction" } }, "description": "Azione dell'utente finale in sospeso, oppure `null`. Stesso oggetto di `action_required` nella transazione; `session_token` è una credenziale, quindi non registrarlo mai nei log." } }, "required": [ "webhook_type", "transaction_id", "txn_id", "status", "score", "severity", "amount", "currency", "direction", "action_required" ] } ] }, "TravelRuleStatusUpdatedEvent": { "description": "Uno scambio Travel Rule ha cambiato stato. Inviato per ogni transizione fino a `FINISHED`, `CANCELLED` o `EXPIRED` inclusi, mai dopo. Inviato per le applicazioni di produzione e, per gli scambi Travel Rule, anche per le applicazioni sandbox (`environment: sandbox`). Non è presente alcuno `status` di primo livello.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "travel_rule.status.updated" ], "description": "Sempre `travel_rule.status.updated`." }, "transaction_id": { "type": "string", "format": "uuid", "description": "La transazione a cui appartiene lo scambio." }, "txn_id": { "type": "string", "nullable": true, "description": "Il `transaction_id` fornito al momento della creazione, oppure `null`." }, "travel_rule_status": { "type": "string", "enum": [ "AWAITING_COUNTERPARTY", "ON_HOLD", "COMPLETED", "FINISHED", "CANCELLED", "EXPIRED", "COUNTERPARTY_MISMATCHED_DATA", "COUNTERPARTY_VASP_NOT_FOUND", "COUNTERPARTY_VASP_NOT_REACHABLE", "UNCONFIRMED_OWNERSHIP", "COUNTERPARTY_VASP_GENERAL_DECLINE", "NOT_ENOUGH_COUNTERPARTY_DATA", "NOT_APPLICABLE" ], "description": "Stato dello scambio dopo la modifica." }, "rail": { "type": "string", "enum": [ "", "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "TEST_VASP" ], "description": "Rete su cui opera l'exchange, oppure una stringa vuota se non è stato possibile determinarne alcuna. `TEST_VASP` è un trasferimento in sandbox a cui ha risposto il Didit Test VASP." }, "test_vasp": { "type": "boolean", "description": "Presente e `true` solo su un trasferimento in sandbox a cui ha risposto il Didit Test VASP." }, "test_vasp_scenario": { "type": "string", "description": "Presente solo con `test_vasp`: lo scenario sandbox che ha determinato l'esito, o una stringa vuota." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direzione del trasferimento." } }, "required": [ "webhook_type", "transaction_id", "txn_id", "travel_rule_status", "rail", "direction" ] } ] }, "WorkflowComplianceChangedEvent": { "description": "Lo stato di compliance di un workflow pubblicato è cambiato dopo una rivalutazione. Un evento per workflow. Non è presente alcuno `status` di primo livello.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "workflow.compliance_changed" ], "description": "Sempre `workflow.compliance_changed`." }, "workflow_id": { "type": "string", "format": "uuid", "description": "Il workflow modificato." }, "workflow_version": { "type": "integer", "description": "Versione valutata." }, "workflow_label": { "type": "string", "nullable": true, "description": "Nome visualizzato del workflow." }, "transition": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "enum": [ "compliant", "gaps_detected", "pending_change", "unknown_coverage", "not_evaluated" ], "description": "Stato prima della rivalutazione." }, "to": { "type": "string", "enum": [ "compliant", "gaps_detected", "pending_change", "unknown_coverage", "not_evaluated" ], "description": "Stato dopo la rivalutazione." } } }, "severity": { "type": "string", "enum": [ "actionable", "indicative", "informative" ], "description": "`actionable` quando sono state rilevate lacune, `indicative` per una modifica in sospeso, `informative` quando le lacune sono state risolte." }, "kb_version": { "type": "string", "description": "Versione della base di conoscenze normativa utilizzata." } }, "required": [ "webhook_type", "workflow_id", "workflow_version", "workflow_label", "transition", "severity", "kb_version" ] } ] }, "WebhookEventPayload": { "description": "Corpo di una consegna webhook firmata, discriminato da `webhook_type`. È possibile iscriversi ad `activity.created`, ma attualmente non viene inviato. Tratta qualsiasi altro `webhook_type` come un nuovo tipo di evento e conserva il corpo non elaborato.", "oneOf": [ { "$ref": "#/components/schemas/SessionStatusUpdatedEvent" }, { "$ref": "#/components/schemas/SessionDataUpdatedEvent" }, { "$ref": "#/components/schemas/UserStatusUpdatedEvent" }, { "$ref": "#/components/schemas/UserDataUpdatedEvent" }, { "$ref": "#/components/schemas/BusinessStatusUpdatedEvent" }, { "$ref": "#/components/schemas/BusinessDataUpdatedEvent" }, { "$ref": "#/components/schemas/TransactionCreatedEvent" }, { "$ref": "#/components/schemas/TransactionStatusUpdatedEvent" }, { "$ref": "#/components/schemas/TravelRuleStatusUpdatedEvent" }, { "$ref": "#/components/schemas/WorkflowComplianceChangedEvent" }, { "$ref": "#/components/schemas/TransactionRuleSuggestionsCreatedEvent" } ], "discriminator": { "propertyName": "webhook_type", "mapping": { "status.updated": "#/components/schemas/SessionStatusUpdatedEvent", "data.updated": "#/components/schemas/SessionDataUpdatedEvent", "user.status.updated": "#/components/schemas/UserStatusUpdatedEvent", "user.data.updated": "#/components/schemas/UserDataUpdatedEvent", "business.status.updated": "#/components/schemas/BusinessStatusUpdatedEvent", "business.data.updated": "#/components/schemas/BusinessDataUpdatedEvent", "transaction.created": "#/components/schemas/TransactionCreatedEvent", "transaction.status.updated": "#/components/schemas/TransactionStatusUpdatedEvent", "travel_rule.status.updated": "#/components/schemas/TravelRuleStatusUpdatedEvent", "workflow.compliance_changed": "#/components/schemas/WorkflowComplianceChangedEvent", "transaction_rule_suggestions.created": "#/components/schemas/TransactionRuleSuggestionsCreatedEvent" } } }, "KYBRegistrySearchResolvedCallback": { "type": "object", "description": "Corpo del callback inviato all'URL specificato in `webhook_url` di `POST /v3/kyb/search/` una volta risolta la ricerca nel registro. Non è firmato: la richiesta contiene `X-Didit-Unsigned-Callback: true` e nessuna delle intestazioni di firma, pertanto confermalo verificando che `request_id` corrisponda a una ricerca avviata da te. Utilizza `event_type`, non `webhook_type`.", "required": [ "event_id", "event_type", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at" ], "properties": { "event_id": { "type": "string", "format": "uuid", "description": "Identificatore del callback." }, "event_type": { "type": "string", "enum": [ "kyb.registry_search.resolved" ], "description": "Sempre `kyb.registry_search.resolved`." }, "request_id": { "type": "string", "format": "uuid", "description": "Il `request_id` restituito da `POST /v3/kyb/search/`." }, "vendor_data": { "type": "string", "nullable": true, "description": "Eco del `vendor_data` inviato." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Eco del `metadata` inviato." }, "search_status": { "type": "string", "description": "Sempre `resolved` al momento." }, "search_resolved": { "type": "boolean", "description": "`true` quando `search_status` è `resolved`." }, "kyb_registry": { "$ref": "#/components/schemas/KYBRegistrySearchResults" }, "timestamp": { "type": "integer", "description": "Ora Unix in secondi in cui il callback è stato inserito in coda." }, "created_at": { "type": "integer", "description": "Ora Unix in secondi in cui il callback è stato inserito in coda." } } }, "AMLScreening": { "type": "object", "properties": { "node_id": { "type": "string", "description": "Identificatore univoco per questo passaggio AML nel grafo del workflow." }, "status": { "type": "string", "description": "Stato a livello di funzionalità di questo Screening AML. Indipendente dallo `status` della sessione di primo livello: una sessione può raggiungere la sua decisione complessiva mentre una singola funzionalità rimane in `In Review`.", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ] }, "total_hits": { "type": "integer", "description": "Numero totale di corrispondenze trovate" }, "entity_type": { "type": "string", "description": "Tipo di entità sottoposta a screening: persona o azienda" }, "hits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificativo stabile di Didit per l'hit: `hit_` seguito da 24 caratteri esadecimali. La stessa entità corrispondente mantiene lo stesso `id` quando il soggetto viene sottoposto nuovamente a screening. Passalo come `hit_id` agli endpoint di revisione degli hit AML." }, "url": { "type": "string", "format": "uri", "description": "URL di origine per la corrispondenza" }, "match": { "type": "boolean", "description": "Indica se si tratta di una corrispondenza confermata" }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 1, "description": "Punteggio di corrispondenza ponderato deprecato nell'intervallo 0-1 (ad es. `0.73`). Usa invece `match_score` (0-100).", "deprecated": true }, "target": { "type": "boolean", "nullable": true, "description": "Indica se l'entità corrispondente è il bersaglio diretto dell'inserimento nella lista (anziché una parte correlata). `null` quando la fonte non lo specifica." }, "caption": { "type": "string", "description": "Didascalia o titolo della corrispondenza" }, "datasets": { "type": "array", "items": { "type": "string", "enum": [ "PEP", "PEP Level 1", "PEP Level 2", "PEP Level 3", "PEP Level 4", "Sanctions", "Adverse Media", "Warnings and Regulatory Enforcement", "Fitness and Probity", "SIP", "SIE", "Insolvency", "Other Lists" ] }, "description": "Elenco delle categorie di dataset in cui è stata trovata la corrispondenza. Indica se l'entità compare in liste PEP (con livello), database di sanzioni, notizie negative, avvisi/provvedimenti normativi o altri dataset di conformità. `Other Lists` quando la fonte dell'entità non specifica nessuna di queste categorie." }, "features": { "type": "object", "nullable": true, "description": "Caratteristiche aggiuntive della corrispondenza" }, "rca_name": { "type": "string", "description": "Nome RCA, se applicabile" }, "last_seen": { "type": "string", "format": "date-time", "description": "Data in cui la corrispondenza è stata rilevata per l'ultima volta" }, "risk_view": { "type": "object", "properties": { "crimes": { "type": "object", "properties": { "score": { "type": "integer" }, "weightage": { "type": "integer" }, "risk_level": { "type": "string" }, "risk_scores": { "type": "object" } } }, "countries": { "type": "object", "properties": { "score": { "type": "integer" }, "weightage": { "type": "integer" }, "risk_level": { "type": "string" }, "risk_scores": { "type": "object" } } }, "categories": { "type": "object", "properties": { "score": { "type": "integer" }, "weightage": { "type": "integer" }, "risk_level": { "type": "string" }, "risk_scores": { "type": "object" } } }, "custom_list": { "type": "object" } } }, "first_seen": { "type": "string", "format": "date-time", "description": "Data in cui la corrispondenza è stata rilevata per la prima volta" }, "properties": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string" } }, "alias": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string", "nullable": true }, "gender": { "type": "array", "items": { "type": "string" } }, "height": { "type": "string", "nullable": true }, "topics": { "type": "string", "nullable": true }, "weight": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "eyeColor": { "type": "string", "nullable": true }, "keywords": { "type": "string", "nullable": true }, "lastName": { "type": "array", "items": { "type": "string" } }, "position": { "type": "string", "nullable": true }, "religion": { "type": "string", "nullable": true }, "birthDate": { "type": "array", "items": { "type": "string" } }, "education": { "type": "array", "items": { "type": "string" } }, "ethnicity": { "type": "string", "nullable": true }, "firstName": { "type": "array", "items": { "type": "string" } }, "hairColor": { "type": "string", "nullable": true }, "weakAlias": { "type": "string", "nullable": true }, "birthPlace": { "type": "array", "items": { "type": "string" } }, "modifiedAt": { "type": "string", "nullable": true }, "wikidataId": { "type": "string", "nullable": true }, "citizenship": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true } } }, "match_score": { "type": "number", "description": "Punteggio di affidabilità dell'identità ponderato (0-100) calcolato a partire dalla somiglianza del nome, dalla data di nascita e dalla corrispondenza del paese. Utilizzato per determinare se un'occorrenza è un falso positivo o una possibile corrispondenza.", "format": "float", "nullable": true }, "risk_score": { "type": "number", "description": "Punteggio di rischio dell'entità (0-100). Utilizzato per determinare lo stato AML finale (Approvata/In revisione/Rifiutata) in base al risk_score più alto tra le corrispondenze non considerate falsi positivi." }, "review_status": { "type": "string", "description": "Stato di revisione per questa corrispondenza. Può essere 'Unreviewed', 'Confirmed Match', 'False Positive' o 'Inconclusive'.", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ] }, "score_breakdown": { "type": "object", "description": "Dettaglio approfondito di come è stato calcolato match_score.", "properties": { "name_score": { "type": "integer", "description": "Percentuale di somiglianza dei nomi non elaborata (0-100)." }, "name_weight": { "type": "integer", "description": "Peso originale per il nome dalla configurazione (0-100)." }, "name_weight_normalized": { "type": "number", "description": "Peso normalizzato per il nome dopo la ricalibrazione per dati mancanti (0-100)." }, "name_contribution": { "type": "number", "description": "Punti con cui il nome ha contribuito al punteggio totale." }, "dob_score": { "type": "integer", "description": "Punteggio di corrispondenza della data di nascita (-100 a 100)." }, "dob_weight": { "type": "integer", "description": "Peso originale per la data di nascita (DOB) dalla configurazione (0-100)." }, "dob_weight_normalized": { "type": "number", "description": "Peso normalizzato per la data di nascita dopo la ricalibrazione per dati mancanti (0-100)." }, "dob_contribution": { "type": "number", "description": "Punti con cui la data di nascita ha contribuito al punteggio totale." }, "country_score": { "type": "integer", "description": "Punteggio di corrispondenza del paese (da -100 a 100)." }, "country_weight": { "type": "integer", "description": "Peso originale per il paese dalla configurazione (0-100)." }, "country_weight_normalized": { "type": "number", "description": "Peso normalizzato per il paese dopo la ricalibrazione per dati mancanti (0-100)." }, "country_contribution": { "type": "number", "description": "Punti con cui il paese ha contribuito al punteggio totale." }, "document_number_match_type": { "type": "string", "description": "Risultato della valutazione 'Golden Key' del numero di documento.", "enum": [ "MATCH", "NEUTRAL", "HARD_MISMATCH" ] }, "document_number_effect": { "type": "string", "description": "Descrizione di facile lettura dell'effetto del numero del documento sul punteggio." }, "total_score": { "type": "integer", "description": "Punteggio di corrispondenza ponderato finale (0-100)." } } }, "pep_matches": { "type": "array", "items": { "type": "object", "properties": { "aliases": { "type": "array", "items": { "type": "string" } }, "education": { "type": "array", "items": { "type": "string" } }, "list_name": { "type": "string" }, "publisher": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "matched_name": { "type": "string" }, "pep_position": { "type": "string" }, "date_of_birth": { "type": "string" }, "other_sources": { "type": "array", "items": { "type": "string" } }, "place_of_birth": { "type": "string" } } } }, "linked_entities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string" } }, "active": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "details": { "type": "array", "items": { "type": "string" } }, "relation": { "type": "array", "items": { "type": "string" } } } } }, "warning_matches": { "type": "array", "description": "Elenco delle corrispondenze con avvisi e provvedimenti normativi. Include voci delle categorie: Warning, SIP, Warnings and Regulatory Enforcement, Fitness and Probity, SIE e Insolvency.", "items": { "type": "object", "properties": { "list_name": { "type": "string", "description": "Nome dell'editore della lista di avvisi" }, "matched_name": { "type": "string", "description": "Nome corrispondente nella lista degli avvisi" }, "description": { "type": "string", "description": "Descrizione della voce di avviso" }, "publisher": { "type": "string", "description": "Editore o fonte dell'avviso" }, "source_url": { "type": "string", "format": "uri", "description": "URL della fonte dell'avviso" }, "other_sources": { "type": "array", "items": { "type": "string" }, "description": "URL sorgente aggiuntivi" }, "countries": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Paesi associati all'avviso" }, "created_at": { "type": "string", "nullable": true, "description": "Data di creazione della voce di avviso" }, "updated_at": { "type": "string", "nullable": true, "description": "Data dell'ultimo aggiornamento della voce di avviso" }, "additional_data": { "type": "object", "description": "Dati aggiuntivi provenienti dalla fonte dell'avviso. Può contenere un oggetto `data` con un array `case_details`.", "properties": { "data": { "type": "object", "properties": { "case_details": { "type": "array", "description": "Dettagli dei casi di avviso associati a questa corrispondenza", "items": { "type": "object", "properties": { "case_type": { "type": "string", "description": "Tipo del caso di avviso", "enum": [ "Accusation", "Arrest", "Bribery", "Criminal", "Fraud", "Illegal Fundraising", "Non-conviction Terror", "Proclaimed Offender", "Regulatory Enforcement", "Terrorism", "Terrorism-related", "Terrorism-related listing" ] } } } } } } } } } } }, "sanction_matches": { "type": "array", "description": "Elenco delle corrispondenze nelle liste delle sanzioni trovate per questa entità.", "items": { "type": "object", "properties": { "list_name": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Nome/i della/e lista/e delle sanzioni" }, "matched_name": { "type": "string", "description": "Nome corrispondente nella lista delle sanzioni" }, "description": { "type": "string", "description": "Descrizione della voce di sanzione" }, "reason": { "type": "string", "nullable": true, "description": "Motivo in formato testo libero per cui l'entità è stata sanzionata. Aggregato dalle voci relative al motivo della lista delle sanzioni. Esempi: 'Executive Order 13224 (Terrorism)', 'Support for actions undermining Ukraine's sovereignty', 'Listed due to national security concerns.'" }, "source_url": { "type": "string", "format": "uri", "description": "URL della fonte della sanzione" }, "other_sources": { "type": "array", "items": { "type": "string" }, "description": "URL sorgente aggiuntivi" }, "details": { "type": "array", "items": { "type": "string" }, "description": "Ulteriori dettagli sulla sanzione" }, "legal_basis": { "type": "array", "items": { "type": "string" }, "description": "Base giuridica della sanzione" }, "listed_on": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Data/e in cui l'entità è stata inserita nell'elenco" }, "sanction_list": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Identificatore/i della lista delle sanzioni" }, "sanction_program": { "type": "array", "items": { "type": "string" }, "description": "Programma/i di sanzioni in cui l'entità è inclusa" }, "sanctioning_authority": { "type": "array", "items": { "type": "string" }, "description": "Autorità che ha imposto la sanzione" }, "updated_on": { "type": "array", "items": { "type": "string" }, "description": "Data o date dell'ultimo aggiornamento della voce di sanzione" }, "additional_data": { "type": "object", "description": "Dati aggiuntivi provenienti dalla fonte delle sanzioni non acquisiti nei campi principali" } } } }, "adverse_media_details": { "type": "object", "properties": { "sentiment": { "type": "string" }, "entity_type": { "type": "string" }, "sentiment_score": { "type": "integer" }, "adverse_keywords": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "adverse_media_matches": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "summary": { "type": "string" }, "headline": { "type": "string" }, "sentiment": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" }, "source_url": { "type": "string", "format": "uri" }, "author_name": { "type": "string", "nullable": true }, "other_sources": { "type": "array", "items": { "type": "string" } }, "adverse_keywords": { "type": "array", "items": { "type": "string" } }, "sentiment_score": { "type": "integer" }, "publication_date": { "type": "string", "format": "date-time" } } } }, "additional_information": { "type": "object" } } } }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Punteggio complessivo dello screening AML — il punteggio di rischio più alto tra tutti i riscontri (float, 0-100). `null` finché non viene calcolato." }, "screened_data": { "type": "object", "properties": { "full_name": { "type": "string" }, "nationality": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "document_number": { "type": "string", "nullable": true } } }, "is_ongoing_monitoring_enabled": { "type": "boolean", "description": "Indica se il monitoraggio AML continuo è abilitato per questo screening. Quando è `true`, l'entità viene sottoposta nuovamente a screening periodicamente e ogni nuova corrispondenza aggiorna il report." }, "next_ongoing_monitoring_bill_date": { "type": "string", "format": "date", "nullable": true, "description": "Data (YYYY-MM-DD) in cui verrà fatturato successivamente questo abbonamento al monitoraggio continuo. Calcolata come la data dell'ultima fatturazione del monitoraggio continuo più 365 giorni quando `is_ongoing_monitoring_enabled = true`; altrimenti `null`. Questa è una data di fatturazione, non una data di screening: usa `last_ongoing_screening_at` a questo scopo." }, "last_ongoing_screening_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultimo completamento del nuovo screening di questo record da parte del monitoraggio continuo, indipendentemente dal fatto che il risultato sia cambiato o meno. `null` se il record non è mai stato sottoposto a un nuovo screening; non viene mai retrodatato alla data di abilitazione o di fatturazione." }, "last_ongoing_screening_datasets_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "La data più recente di aggiornamento del set di dati AML segnalata dal provider al momento di tale screening. `null` se il provider non ha segnalato date del set di dati; mai stimata." }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACEMATCH", "PROOF_OF_ADDRESS", "PHONE", "EMAIL", "AML", "LOCATION", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "GEOLOCATION", "SIGNATURE" ], "description": "La funzionalità che ha generato questo avviso. Il valore identifica il blocco della funzionalità a cui appartiene l'avviso. All'interno di uno screening AML questo è solitamente `AML`, ma l'enum riportato sopra fa fede per tutti gli avvisi delle funzionalità presenti nel payload della decisione." }, "risk": { "type": "string" }, "additional_data": { "type": "object", "nullable": true }, "log_type": { "type": "string" }, "short_description": { "type": "string" }, "long_description": { "type": "string" }, "node_id": { "type": "string", "description": "L'ID del nodo del grafo del workflow che ha generato questo avviso" } } } } } }, "MonitoringEvent": { "type": "object", "description": "Un evento di monitoraggio memorizzato come restituito dagli endpoint dell'elenco e della cronologia del soggetto. Le evidenze con accesso limitato (payload, contesto del dispositivo, evidenze della regola) vengono restituite solo da `GET /v3/events/{event_uuid}/`.", "required": [ "event_uuid", "event_id", "event_category", "action_type", "occurred_at", "received_at", "status", "score", "subject_vendor_data", "subject_entity_type", "subject_uuid", "counterparty_vendor_data", "session_id", "device_fingerprint", "ip_address", "ip_country", "amount", "currency", "game_id", "round_id", "bonus_id", "affiliate_code", "payment_reference_id", "retention_class", "rules_matched_count", "correlation_pending", "is_droppable" ], "properties": { "event_uuid": { "type": "string", "format": "uuid", "description": "Identificatore Didit dell'evento. Utilizzalo come `{event_uuid}` nelle chiamate di recupero e cancellazione." }, "event_id": { "type": "string", "maxLength": 128, "description": "Il tuo identificatore, la chiave di idempotenza che hai inviato." }, "event_category": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ], "description": "Categoria dell'evento." }, "action_type": { "type": "string", "maxLength": 128, "description": "Cosa è successo all'interno della categoria, così come l'hai inviato." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Data e ora in cui l'evento si è verificato nel tuo sistema." }, "received_at": { "type": "string", "format": "date-time", "description": "Quando Didit ha accettato l'evento." }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "`ACCEPTED`: memorizzato, nessuna regola corrispondente ha modificato il suo stato (la risposta normale per la maggior parte degli eventi, e sempre la risposta in un'applicazione sandbox, dove non viene eseguita alcuna regola). `APPROVED`: una regola ha trovato corrispondenza e il punteggio è rimasto al di sotto della soglia di revisione. `IN_REVIEW`: una regola ha fatto superare al punteggio la soglia di revisione o ha impostato lo stato. `DECLINED`: una regola lo ha rifiutato o il punteggio ha superato la soglia di rifiuto." }, "score": { "type": "integer", "description": "Punteggio cumulativo delle regole. Inizia da 0; le azioni `add_score` delle regole lo modificano (sono consentiti delta negativi)." }, "subject_vendor_data": { "type": "string", "maxLength": 255, "description": "`subject.vendor_data` dell'evento: il tuo identificativo per l'utente o l'azienda." }, "subject_entity_type": { "type": "string", "description": "`individual` o `company`: indica il tipo di soggetto a cui fa riferimento `subject_vendor_data`.", "example": "individual" }, "subject_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID dell'utente (persona fisica) o dell'azienda a cui l'evento è stato ricondotto, oppure null se tale record non esiste più." }, "counterparty_vendor_data": { "type": "string", "nullable": true, "description": "L'altro partecipante di un evento P2P (promosso da `payload.counterparty_vendor_data`).", "maxLength": 255 }, "session_id": { "type": "string", "nullable": true, "description": "`session.session_id` inviato con l'evento.", "maxLength": 255 }, "device_fingerprint": { "type": "string", "nullable": true, "description": "`device_context.fingerprint` inviato con l'evento.", "maxLength": 255 }, "ip_address": { "type": "string", "nullable": true, "description": "Indirizzo IP dell'evento. Sul lato server è `device_context.network_context.ip_address` come lo hai inviato; sul lato dispositivo è l'IP della richiesta.", "maxLength": 64 }, "ip_country": { "type": "string", "nullable": true, "description": "Codice del paese di `ip_address` ottenuto dall'arricchimento IP, oppure null quando l'indirizzo non è stato arricchito (telemetria mancante, privata o a basso valore il cui indirizzo non era già noto).", "example": "ES" }, "amount": { "type": "string", "nullable": true, "description": "Importo come stringa decimale con 18 cifre decimali, da `transaction_context.amount`, `payload.amount` o `payload.stake_amount`, in quest'ordine.", "example": "250.000000000000000000" }, "currency": { "type": "string", "nullable": true, "description": "Valuta da `transaction_context.currency` o `payload.currency`.", "maxLength": 10 }, "game_id": { "type": "string", "nullable": true, "description": "Promosso da `payload.game_id`.", "maxLength": 128 }, "round_id": { "type": "string", "nullable": true, "description": "Promosso da `payload.round_id`.", "maxLength": 128 }, "bonus_id": { "type": "string", "nullable": true, "description": "Promosso da `payload.bonus_id`.", "maxLength": 128 }, "affiliate_code": { "type": "string", "nullable": true, "description": "Promosso da `payload.affiliate_code`.", "maxLength": 128 }, "payment_reference_id": { "type": "string", "nullable": true, "description": "Riferimento di pagamento da `transaction_context.payment_reference_id` o `payload.payment_reference_id`.", "maxLength": 255 }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "Classe di conservazione. Gli eventi di pagamento e contestazione sono `monetary_or_compliance`; gli eventi di sicurezza e gioco responsabile sono `risk_relevant`; `session.page_view`, `session.sdk_heartbeat`, `session.sdk_loaded`, `session.device_seen`, `session.bot_signal_observed`, `bonus.promotion_viewed` e `affiliate.referral_clicked` sono `low_value`; tutto il resto è `standard`. Un evento corrispondente a una regola attiva viene promosso a `risk_relevant` (senza mai essere retrocesso)." }, "rules_matched_count": { "type": "integer", "minimum": 0, "description": "Numero di regole che hanno corrisposto all'evento, incluse le regole in modalità `TEST` (che registrano le prove ma non applicano azioni)." }, "correlation_pending": { "type": "boolean", "description": "`true` mentre una regola asincrona (correlazione tra soggetti o una sequenza superiore a 24 ore) deve ancora essere eseguita per questo evento. Si risolve entro pochi minuti e `status`, `score` e `rules_matched_count` vengono aggiornati sul posto." }, "is_droppable": { "type": "boolean", "description": "Indica se un SDK sotto contropressione (backpressure) può ignorare eventi di questo tipo. `false` per ogni evento di `security`, `payment`, `dispute` e `responsible_gambling` e per `gameplay.bet_placed`, `gameplay.bet_settled` e `gameplay.p2p_settlement`." } } }, "MonitoringEventDetail": { "description": "Un evento di monitoraggio con la sua busta completa, l'arricchimento e le evidenze delle regole. Tutti i campi di `MonitoringEvent` più i campi seguenti.", "allOf": [ { "$ref": "#/components/schemas/MonitoringEvent" }, { "type": "object", "required": [ "payload", "custom_values", "device_context", "field_sources", "session_sequence", "table_id", "hand_id", "match_id", "market_id", "side", "role", "net_result_amount", "payment_fingerprint", "instrument_reference_hash", "withdrawal_address_hash", "dispute_id", "chargeback_id", "changed_field", "identity_match_ref", "schema_version", "expires_at", "rules_evaluated_count", "rule_runs", "ip_enrichment", "subject_profile", "tags" ], "properties": { "payload": { "type": "object", "additionalProperties": true, "description": "I campi della categoria inviati in `payload`." }, "custom_values": { "type": "object", "additionalProperties": true, "description": "I valori scalari di `custom_values` che hai inviato. Didit aggiunge `vpn_or_proxy_detected: true` o `is_data_center: true` quando l'arricchimento IP contrassegna l'indirizzo e non li hai impostati." }, "device_context": { "type": "object", "additionalProperties": true, "description": "Il contesto del dispositivo archiviato: il tuo `device_context` (inclusi `fingerprint`, `persistent_device_id` e `bot_score` se inviati) con `network_context` completato tramite arricchimento IP (`ip_country`, `ip_country_code`, `ip_city`, `asn_number`, `asn_organization`, `is_vpn_or_tor`, `is_data_center`, `proxy_type`, `connection_type`) per le chiavi lasciate vuote." }, "field_sources": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "customer", "sdk", "server" ] }, "description": "Percorso del campo della provenienza: `customer` (inviato dal tuo backend), `sdk` (inviato tramite il canale del dispositivo) o `server` (derivato da Didit, come `received_at` e i campi di rete arricchiti). Verificalo prima di intervenire su una corrispondenza." }, "session_sequence": { "type": "integer", "format": "int64", "nullable": true, "description": "`session.sequence` inviato con l'evento." }, "table_id": { "type": "string", "nullable": true, "description": "Promosso da `payload.table_id`.", "maxLength": 128 }, "hand_id": { "type": "string", "nullable": true, "description": "Promosso da `payload.hand_id`.", "maxLength": 128 }, "match_id": { "type": "string", "nullable": true, "description": "Promosso da `payload.match_id`.", "maxLength": 128 }, "market_id": { "type": "string", "nullable": true, "description": "Promosso da `payload.market_id`.", "maxLength": 128 }, "side": { "type": "string", "nullable": true, "description": "Promosso da `payload.side`.", "maxLength": 64 }, "role": { "type": "string", "nullable": true, "description": "Promosso da `payload.role`.", "maxLength": 64 }, "net_result_amount": { "type": "string", "nullable": true, "description": "Promosso da `payload.net_result_amount`, come stringa decimale con 18 cifre decimali.", "example": "-120.000000000000000000" }, "payment_fingerprint": { "type": "string", "nullable": true, "description": "Promosso da `payload.payment_fingerprint`.", "maxLength": 255 }, "instrument_reference_hash": { "type": "string", "nullable": true, "description": "Promosso da `payload.instrument_reference_hash`.", "maxLength": 255 }, "withdrawal_address_hash": { "type": "string", "nullable": true, "description": "Promosso da `payload.withdrawal_address_hash` (o `payload.destination_reference_hash`).", "maxLength": 255 }, "dispute_id": { "type": "string", "nullable": true, "description": "Promosso da `payload.dispute_id`.", "maxLength": 255 }, "chargeback_id": { "type": "string", "nullable": true, "description": "Promosso da `payload.chargeback_id`.", "maxLength": 255 }, "changed_field": { "type": "string", "nullable": true, "description": "Promosso da `payload.changed_field` (eventi di modifica della sicurezza).", "maxLength": 128 }, "identity_match_ref": { "type": "string", "nullable": true, "description": "Promosso da `payload.identity_match_ref` (corrispondenze nel registro del gioco responsabile).", "maxLength": 255 }, "schema_version": { "type": "integer", "description": "Versione dello schema dell'involucro dell'evento. Attualmente `1`.", "example": 1 }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora di scadenza ed eliminazione dell'evento in base alla relativa classe di conservazione: `occurred_at` più il periodo della classe (14, 30 o 90 giorni per impostazione predefinita, modificabile per applicazione). Null per gli eventi `monetary_or_compliance`, che seguono la conservazione delle transazioni." }, "rules_evaluated_count": { "type": "integer", "minimum": 0, "description": "Numero di regole di evento valutate per questo evento." }, "rule_runs": { "type": "array", "description": "Ogni regola che ha trovato corrispondenza con l'evento, dalla più recente alla più vecchia.", "items": { "$ref": "#/components/schemas/MonitoringEventRuleRun" } }, "ip_enrichment": { "type": "object", "nullable": true, "description": "Arricchimento dell'indirizzo IP dell'evento, oppure null se l'indirizzo non è stato arricchito. Consulta [arricchimento IP](https://docs.didit.me/it/transaction-monitoring/ip-enrichment).", "properties": { "ip_country_code": { "type": "string", "nullable": true, "description": "Codice del paese dell'indirizzo." }, "ip_city": { "type": "string", "nullable": true, "description": "Città dell'indirizzo." }, "asn_number": { "type": "integer", "nullable": true, "description": "Numero di sistema autonomo." }, "asn_organization": { "type": "string", "nullable": true, "description": "Organizzazione che gestisce il sistema autonomo." }, "is_vpn_or_tor": { "type": "boolean", "description": "Indica se l'indirizzo è un'uscita nota di una VPN o di Tor." }, "is_data_center": { "type": "boolean", "description": "Indica se l'indirizzo appartiene a una rete di hosting o data center." }, "proxy_type": { "type": "string", "nullable": true, "description": "Classificazione proxy dell'indirizzo come stringa opaca, oppure null." }, "last_enriched_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultimo arricchimento dell'indirizzo." } }, "required": [ "ip_country_code", "ip_city", "asn_number", "asn_organization", "is_vpn_or_tor", "is_data_center", "proxy_type", "last_enriched_at" ] }, "subject_profile": { "type": "object", "nullable": true, "description": "Segnali di rischio memorizzati nella cache per email e telefono del soggetto, oppure null se non esiste alcun profilo per il soggetto.", "properties": { "email_risk_score": { "type": "integer", "nullable": true, "description": "Punteggio di rischio dell'email." }, "email_deliverability": { "type": "string", "nullable": true, "description": "Verdetto sulla recapitabilità dell'email." }, "email_is_disposable": { "type": "boolean", "nullable": true, "description": "Indica se l'indirizzo email è usa e getta." }, "email_is_breached": { "type": "boolean", "nullable": true, "description": "Indica se l'indirizzo email compare in violazioni di dati note." }, "email_social_count": { "type": "integer", "nullable": true, "description": "Numero di account online collegati all'indirizzo email." }, "email_social_providers": { "type": "array", "items": { "type": "string" }, "description": "Nomi dei servizi online in cui è stato trovato un account collegato all'indirizzo email." }, "phone_risk_score": { "type": "integer", "nullable": true, "description": "Punteggio di rischio del telefono." }, "phone_line_type": { "type": "string", "nullable": true, "description": "Tipo di linea telefonica." }, "phone_carrier": { "type": "string", "nullable": true, "description": "Nome dell'operatore telefonico." }, "phone_social_count": { "type": "integer", "nullable": true, "description": "Numero di account online collegati al numero di telefono." }, "phone_social_providers": { "type": "array", "items": { "type": "string" }, "description": "Nomi dei servizi online in cui è stato trovato un account collegato al numero di telefono." }, "source_provider": { "type": "string", "nullable": true, "description": "Identificatore opaco della fonte del profilo." }, "last_enriched_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il profilo è stato aggiornato l'ultima volta." } }, "required": [ "email_risk_score", "email_deliverability", "email_is_disposable", "email_is_breached", "email_social_count", "email_social_providers", "phone_risk_score", "phone_line_type", "phone_carrier", "phone_social_count", "phone_social_providers", "source_provider", "last_enriched_at" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Nomi dei tag associati all'evento (azioni `add_tags` della regola)." } } } ] }, "MonitoringEventRuleRun": { "type": "object", "properties": { "rule_uuid": { "type": "string", "format": "uuid", "description": "UUID della regola di monitoraggio delle transazioni." }, "rule_title": { "type": "string", "description": "Titolo della regola." }, "library_key": { "type": "string", "nullable": true, "description": "Chiave della libreria se la regola è stata installata dalla libreria di regole, altrimenti null." }, "matched": { "type": "boolean", "description": "Sempre `true`: vengono registrate solo le esecuzioni corrispondenti." }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "Modalità della regola al momento dell'esecuzione. Un'esecuzione in modalità `TEST` registra le prove ma non applica alcuna azione." }, "is_async": { "type": "boolean", "description": "`true` quando l'esecuzione proviene dal passaggio di correlazione asincrono anziché dalla richiesta di acquisizione." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "Gravità della regola. Null per le esecuzioni `TEST` e per le regole prive di gravità." }, "score_delta": { "type": "integer", "description": "Di quanto questa esecuzione ha modificato il punteggio dell'evento (0 per le esecuzioni `TEST`)." }, "action_summary": { "type": "string", "nullable": true, "description": "Breve riepilogo delle azioni applicate, ad esempio `score +40; add_tag:VPN_LOGIN`. Null quando non è stato applicato nulla." }, "matched_payload": { "type": "array", "description": "Le condizioni e le aggregazioni corrispondenti. Le voci di condizione contengono `field`, `operator`, `expected_value`, `current_value`, `matched`, `group_index`, `group_logic` e `field_source` (`server`, `sdk` o `customer`); le voci di aggregazione contengono `metric`, `field`, `operator`, `expected_value`, `computed_value`, `window`, `filters`, `matched` e `sample_references`.", "items": { "type": "object", "additionalProperties": true } }, "created_at": { "type": "string", "format": "date-time", "description": "Quando è stata registrata l'esecuzione della regola." } }, "required": [ "rule_uuid", "rule_title", "library_key", "matched", "mode", "is_async", "severity", "score_delta", "action_summary", "matched_payload", "created_at" ] }, "MonitoringEventPage": { "type": "object", "description": "Una pagina di eventi di monitoraggio, con il valore di `occurred_at` più recente per primo.", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "Numero di eventi corrispondenti, esatto fino a 100 e con limite massimo di 100 oltre tale soglia. Non calcolare il conteggio delle pagine da questo valore; segui `next` finché non è null." }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina successiva, o null nell'ultima pagina." }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "URL della pagina precedente, o null nella prima pagina." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringEvent" } } } }, "MonitoringEventCreateRequest": { "type": "object", "description": "L'envelope dell'evento, lo stesso per ogni categoria. Sono accettati gli alias in camelCase: `eventId`, `eventCategory` (o `category`), `actionType`, `occurredAt`, `timeZone` (o `zoneId`), `deviceContext` (o `device`), `transactionContext`, `customValues` (o `props`); all'interno di `subject`: `vendorData`, `entityType`, `fullName`; all'interno di `session`: `sessionId`, `pageUrl`; all'interno di `transaction_context`: `paymentReferenceId`.", "required": [ "event_id", "event_category", "action_type", "occurred_at", "subject" ], "properties": { "event_id": { "type": "string", "maxLength": 128, "description": "Il tuo identificatore per l'evento, univoco per applicazione. È la chiave di idempotenza: il reinvio, con questo identificatore, degli stessi valori di `event_category`, `action_type`, `occurred_at`, `subject.vendor_data` e `payload` costituisce un replay, qualsiasi elemento differente genera un conflitto.", "example": "login-2026-10-17-000001" }, "event_category": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ], "description": "Categoria dell'evento.", "example": "auth" }, "action_type": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Cosa è successo all'interno della categoria. Vocabolario aperto; le azioni gestite elencate in [Event ingestion](https://docs.didit.me/it/transaction-monitoring/events) (ad esempio `login`, `deposit_completed`, `chargeback_opened`) sbloccano la convalida tipizzata e i campi delle regole gestite. Gli spazi vuoti iniziali e finali vengono rimossi.", "example": "login" }, "occurred_at": { "type": "string", "format": "date-time", "description": "Data e ora in cui l'evento si è verificato nel tuo sistema, ISO 8601 (un valore senza offset viene interpretato come UTC). Non deve essere antecedente a più di 7 giorni nel passato né può essere più di 5 minuti nel futuro.", "example": "2026-10-17T09:15:02.481Z" }, "time_zone": { "type": "string", "nullable": true, "maxLength": 64, "description": "Fuso orario dell'evento dal tuo lato, ad esempio `Europe/Madrid`. Memorizzato con l'evento; non restituito dagli endpoint di lettura." }, "subject": { "type": "object", "description": "L'utente o l'azienda a cui appartiene l'evento. Si risolve nell'utente (o azienda) con questo `vendor_data` nella tua applicazione; ne viene creato uno se non ne esiste alcuno.", "required": [ "vendor_data" ], "properties": { "vendor_data": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Il tuo ID per il soggetto.", "example": "user-42" }, "entity_type": { "type": "string", "maxLength": 32, "default": "individual", "description": "`company` risolve il soggetto in un'azienda; qualsiasi altro valore (predefinito `individual`) lo risolve in una persona fisica. Lo stesso `vendor_data` può indicare uno per ciascun tipo.", "example": "individual" }, "full_name": { "type": "string", "nullable": true, "maxLength": 512, "description": "Nome visualizzato, utilizzato solo quando questo evento crea l'utente o l'azienda." }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Validato come indirizzo email; non memorizzato sull'evento." }, "phone": { "type": "string", "nullable": true, "maxLength": 32, "description": "Validato; non memorizzato sull'evento." }, "country": { "type": "string", "nullable": true, "maxLength": 3, "description": "Validato; non memorizzato sull'evento." } } }, "business": { "type": "object", "description": "L'azienda a cui appartiene l'evento, quando differisce dal soggetto. Viene letto solo `vendor_data`.", "additionalProperties": true, "properties": { "vendor_data": { "type": "string", "maxLength": 255, "description": "Il tuo ID per l'azienda. Filtrabile come `business_vendor_data`.", "example": "merchant-7" } } }, "session": { "type": "object", "description": "Il contesto della tua sessione per l'evento.", "properties": { "session_id": { "type": "string", "nullable": true, "maxLength": 255, "description": "Il tuo identificatore di sessione. Filtrabile e restituito come `session_id`." }, "sequence": { "type": "integer", "nullable": true, "description": "Posizione dell'evento all'interno della sessione. Restituita come `session_sequence`." }, "page_url": { "type": "string", "nullable": true, "maxLength": 2048, "description": "Validato; non memorizzato sull'evento." }, "referrer": { "type": "string", "nullable": true, "maxLength": 2048, "description": "Validato; non memorizzato sull'evento." } } }, "device_context": { "type": "object", "additionalProperties": true, "description": "Contesto del dispositivo e di rete, memorizzato così come inviato e restituito da `GET /v3/events/{event_uuid}/`. In questo canale server Didit non vede la connessione dell'utente finale, quindi l'IP arricchito e utilizzato dalle regole è `network_context.ip_address` esattamente come inviato.", "properties": { "fingerprint": { "type": "string", "maxLength": 255, "description": "Fingerprint del dispositivo. Filtrabile come `device_fingerprint`." }, "persistent_device_id": { "type": "string", "maxLength": 255, "description": "Il tuo identificatore persistente del dispositivo." }, "bot_score": { "type": "integer", "description": "Punteggio bot dal tuo sistema di rilevamento, come numero intero." }, "network_context": { "type": "object", "additionalProperties": true, "properties": { "ip_address": { "type": "string", "maxLength": 64, "description": "Indirizzo IP dell'utente finale. Gli indirizzi pubblici vengono arricchiti una sola volta per ciascun indirizzo univoco.", "example": "203.0.113.42" } } } } }, "transaction_context": { "type": "object", "description": "Contesto monetario. I valori non vuoti qui presenti soddisfano anche le chiavi obbligatorie del payload dell'azione.", "properties": { "amount": { "type": "string", "nullable": true, "description": "Importo come stringa decimale (è accettato anche un numero).", "example": "1000.00" }, "currency": { "type": "string", "nullable": true, "maxLength": 10, "description": "Codice valuta." }, "direction": { "type": "string", "nullable": true, "maxLength": 16, "description": "Direzione del movimento di denaro, ad esempio `inbound` o `outbound`." }, "payment_reference_id": { "type": "string", "nullable": true, "maxLength": 255, "description": "Il tuo riferimento di pagamento. Filtrabile come `payment_reference_id`." } } }, "payload": { "type": "object", "additionalProperties": true, "description": "I campi di dominio della categoria, massimo 16384 byte una volta codificati in JSON. Alcune azioni richiedono chiavi (in `payload` o in `transaction_context`): `gameplay.p2p_settlement` richiede `game_id`, `counterparty_vendor_data`, `stake_amount`, `net_result_amount`, `role` e uno tra `hand_id`, `round_id`, `match_id`; `gameplay.bet_placed` e `gameplay.bet_settled` richiedono `game_id`; `payment.deposit_initiated`, `payment.deposit_completed`, `payment.withdrawal_requested` e `payment.withdrawal_completed` richiedono `payment_reference_id`, `amount`, `currency`, `payment_method`, `status`; `payment.withdrawal_address_changed` richiede `withdrawal_address_hash`; `dispute.chargeback_opened`, `dispute.chargeback_won` e `dispute.chargeback_lost` richiedono `payment_reference_id` e uno tra `dispute_id`, `chargeback_id`; `session.bot_signal_observed` richiede `telemetry_schema_version` e uno tra `bot_score`, `actions_per_minute`, `timing_variance_ms`, `pointer_entropy`, `keystroke_entropy`, `reaction_time_ms_p50`; `responsible_gambling.self_exclusion_match` richiede `registry_source`, `exclusion_status`, `identity_match_ref`. Ogni azione `security` che termina con `_changed` richiede `changed_field`, oltre a `previous_reference_hash` o `new_reference_hash` quando il campo è `password`, `mfa_method`, `mfa`, `email`, `phone`, `withdrawal_address`, `payout_method` o `api_key`. Invia hash e riferimenti, mai un numero di carta, un indirizzo di prelievo completo, un hash della password o un segreto MFA." }, "custom_values": { "type": "object", "description": "Fino a 100 chiavi personalizzate, indirizzabili dalle regole come `custom_values.`. I valori devono essere scalari (stringa, numero, booleano o null); oggetti e array annidati vengono rifiutati.", "additionalProperties": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "example": { "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481Z", "time_zone": "Europe/Madrid", "subject": { "vendor_data": "user-42", "entity_type": "individual" }, "session": { "session_id": "web-session-abc", "sequence": 142 }, "device_context": { "fingerprint": "fp-a8c1", "network_context": { "ip_address": "203.0.113.42" } }, "payload": { "method": "password" }, "custom_values": { "vip_tier": "gold" } } }, "MonitoringEventIngestResult": { "type": "object", "description": "Esito dell'acquisizione di un evento. Viene restituita la stessa struttura sia per un nuovo evento sia per una ripetizione idempotente.", "required": [ "event_uuid", "event_id", "status", "score", "rules_evaluated_count", "rules_matched_count", "correlation_pending", "retention_class", "expires_at", "idempotent_replay", "rule_matches" ], "properties": { "event_uuid": { "type": "string", "format": "uuid", "description": "Identificatore Didit dell'evento memorizzato." }, "event_id": { "type": "string", "description": "Il tuo `event_id`." }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "Stato dopo l'esecuzione delle regole in tempo reale. Vedi `MonitoringEvent.status`." }, "score": { "type": "integer", "description": "Punteggio ottenuto dopo l'esecuzione delle regole in tempo reale." }, "rules_evaluated_count": { "type": "integer", "minimum": 0, "description": "Numero di regole di evento valutate nella richiesta. 0 in un'applicazione sandbox, in cui non viene eseguita alcuna regola." }, "rules_matched_count": { "type": "integer", "minimum": 0, "description": "Numero di regole che hanno trovato corrispondenza, incluse le regole in modalità `TEST`." }, "correlation_pending": { "type": "boolean", "description": "`true` quando una regola asincrona deve ancora essere eseguita. Leggi `GET /v3/events/{event_uuid}/` qualche minuto dopo per ottenere `status` e `score` definitivi." }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "Classe di conservazione, dopo l'eventuale promozione applicata da una regola corrispondente." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora di scadenza ed eliminazione dell'evento in base alla relativa classe di conservazione. Null per gli eventi `monetary_or_compliance` (pagamento e contestazione)." }, "idempotent_replay": { "type": "boolean", "description": "`true` quando un evento con questo `event_id` e lo stesso contenuto era già memorizzato; i valori sono quelli dell'evento memorizzato e nessuna regola è stata rieseguita." }, "rule_matches": { "type": "array", "description": "Regole che hanno prodotto una corrispondenza con l'evento.", "items": { "type": "object", "required": [ "rule_id", "library_key", "mode", "is_async" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "description": "UUID della regola." }, "library_key": { "type": "string", "nullable": true, "description": "Chiave della libreria se la regola è stata installata dalla libreria di regole, altrimenti null." }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "Le regole `TEST` registrano la corrispondenza ma non applicano alcuna azione." }, "is_async": { "type": "boolean", "description": "`true` quando la corrispondenza proviene dal passaggio asincrono." } } } } } }, "ComplianceList": { "type": "object", "description": "Una blocklist, allowlist o lista personalizzata di un'applicazione.", "required": [ "uuid", "name", "description", "list_type", "entry_type", "is_system", "entry_count", "last_entry_added_at", "created_at", "updated_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificatore della lista. Utilizzalo come `list_uuid` negli endpoint di lista e voci, e come valore di una condizione di regola di workflow o transazione con `value_type: \"list\"`." }, "name": { "type": "string", "maxLength": 255, "description": "Nome della lista, univoco tra le liste dell'applicazione." }, "description": { "type": "string", "description": "Descrizione in formato testo libero. Stringa vuota se non impostata." }, "list_type": { "type": "string", "enum": [ "blocklist", "allowlist", "custom" ], "description": "`blocklist`: una corrispondenza rifiuta la sessione o la transazione (solo liste di sistema, una per tipo di voce). `allowlist`: gli elementi corrispondenti sono attendibili, ad esempio un'allowlist dei volti salta l'azione per volto duplicato; non sovrascrive mai una corrispondenza con la blocklist. `custom`: utilizzato nelle condizioni delle regole del workflow e delle transazioni (`value_type: \"list\"`)." }, "entry_type": { "type": "string", "enum": [ "face", "document", "phone", "email", "ip_address", "device_fingerprint", "wallet_address", "bank_account", "country", "user", "business", "key" ], "description": "Cosa contiene la lista: `face`, `document` (numero del documento), `phone`, `email`, `ip_address` (indirizzo o intervallo CIDR), `device_fingerprint`, `wallet_address`, `bank_account`, `country` (ISO 3166-1 alpha-3), `user` o `business` (il tuo `vendor_data`), oppure `key` (qualsiasi stringa). Determina come vengono convalidati e confrontati i valori delle voci." }, "is_system": { "type": "boolean", "description": "`true` per le liste predisposte da Didit: una blocklist per tipo di voce (`face`, `document`, `phone`, `email`, `ip_address`, `device_fingerprint`, `wallet_address`, `bank_account`, `user`, `business`), la lista personalizzata **High Risk Countries** e le allowlist di sistema. Le liste di sistema non possono essere rinominate, modificate o eliminate; puoi aggiungerne ed eliminarne le voci." }, "entry_count": { "type": "integer", "minimum": 0, "description": "Numero di voci attualmente presenti nella lista." }, "last_entry_added_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando è stata aggiunta la voce corrente più recente. `null` per una lista vuota." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando la lista è stata creata." }, "updated_at": { "type": "string", "format": "date-time", "description": "Quando la lista è stata aggiornata l'ultima volta." } } }, "ComplianceListEntry": { "type": "object", "description": "Un singolo valore in una lista.", "required": [ "uuid", "value", "display_label", "comment", "added_by", "reference_session_id", "reference_session_number", "reference_session_type", "reference_object_uuid", "metadata", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificatore della voce. Utilizzalo come `entry_uuid` in Elimina una voce dell'elenco." }, "value": { "type": "string", "description": "Il valore inserito in lista: un numero di telefono in formato E.164, un indirizzo email, un numero di documento, un indirizzo IP o un intervallo CIDR, un'impronta digitale del dispositivo, un indirizzo del wallet, un conto bancario, un codice paese ISO 3166-1 alpha-3, un `vendor_data`, qualsiasi stringa su una lista `key`, oppure l'UUID del volto memorizzato su una lista di volti. I valori inviati vengono memorizzati in minuscolo, ad eccezione dei numeri di telefono e dei codici paese. La corrispondenza non fa distinzione tra maiuscole e minuscole." }, "display_label": { "type": "string", "nullable": true, "maxLength": 512, "description": "Etichetta di facile lettura. Didit la compila per le voci estratte da una sessione (ad esempio il nome del titolare e il numero del documento) quando non ne invii nessuna." }, "comment": { "type": "string", "description": "Nota in formato testo libero. Stringa vuota se non impostata." }, "added_by": { "type": "string", "nullable": true, "description": "Chi ha aggiunto la voce: `api` (una chiave API), l'indirizzo email di un utente della console o `console`, `system` o `migration` (voci create da Didit), oppure `rule` (un'azione di una regola di transazione o monitoraggio)." }, "reference_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessione di verifica da cui è stata estratta la voce. `null` quando la voce è stata aggiunta per valore." }, "reference_session_number": { "type": "integer", "nullable": true, "description": "Numero della sessione con ambito limitato all'applicazione, come mostrato nella console." }, "reference_session_type": { "type": "string", "nullable": true, "enum": [ "kyc", "kyb", null ], "description": "`kyc` per una sessione di verifica di una persona fisica, `kyb` per una sessione di verifica aziendale, `null` quando non è presente alcuna sessione." }, "reference_object_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "Il record rappresentato dalla voce: il record del volto, del documento, del telefono o dell'email letto da una sessione, il volto creato tramite Upload a face to a list, o l'UUID inviato (ad esempio l'UUID di una transazione o il `didit_internal_id` di un utente)." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Contesto aggiuntivo. Contiene le chiavi impostate da Didit (elencate qui) unite a qualsiasi `metadata` inviato durante la creazione della voce, restituite così come memorizzate. `null` se non è presente alcuno.", "properties": { "reference_image_url": { "type": "string", "description": "Voci del volto: URL firmato di breve durata, emesso nuovamente a ogni chiamata; `null` per una chiave API con ambito senza `media: read`. Assente quando nessuna immagine appartiene alla voce." }, "front_image_url": { "type": "string", "description": "Voci del documento contenenti l'immagine frontale del documento: URL firmato di breve durata, riemesso a ogni chiamata; `null` per una chiave API con ambito priva di `media: read`." }, "full_name": { "type": "string", "description": "Voci del documento estratte da una sessione: nome completo del titolare." }, "issuing_state": { "type": "string", "description": "Voci del documento estratte da una sessione: paese di emissione ISO 3166-1 alpha-3." }, "document_type": { "type": "string", "description": "Voci del documento estratte da una sessione: codice del tipo di documento, ad esempio `P`, `ID` o `DL`." }, "region": { "type": "string", "description": "Voci del documento estratte da una sessione: stato o provincia di emissione per un documento emesso a livello regionale, vuoto se non applicabile. Non impostato da Aggiungi elementi della sessione alla blocklist." }, "document_number": { "type": "string", "description": "Voci del documento estratte da una sessione: il numero del documento." }, "face_image_source": { "type": "string", "enum": [ "front_image_camera_front", "back_image_camera_front" ], "description": "Voci facciali tratte da un selfie acquisito durante l'acquisizione del documento: quale selfie. Assente per i volti del rilevamento della vitalità." }, "reference_node_id": { "type": "string", "nullable": true, "description": "Voci facciali tratte da un selfie acquisito durante l'acquisizione del documento: il nodo di verifica dell'identità da cui proviene il selfie." }, "fingerprint_tier": { "type": "string", "nullable": true, "enum": [ "persistent_id", "composite_hash", "legacy_fp", "unknown", null ], "description": "Voci del fingerprint del dispositivo acquisite da una sessione: come è stato ricavato il fingerprint. `persistent_id` identifica un singolo dispositivo; `composite_hash` e `legacy_fp` possono essere condivisi da dispositivi dello stesso modello." }, "sandbox": { "type": "boolean", "description": "`true` su una voce del volto caricata in un'applicazione sandbox; tale voce non produce alcuna corrispondenza." }, "reference_type": { "type": "string", "enum": [ "transaction", "vendor_user", "vendor_business" ], "description": "Impostato da te: cosa indica `reference_object_uuid`, in modo che la console crei un collegamento di ritorno verso di esso." }, "reference_id": { "type": "string", "description": "Impostato da te: identificativo del record di origine." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Data e ora di aggiunta della voce." } } }, "BlocklistedItem": { "type": "object", "description": "Un volto, documento d'identità, numero di telefono o indirizzo email presente nella blocklist di una sessione di verifica. I campi non applicabili al `type` dell'elemento sono `null`.", "required": [ "type", "session_id", "session_number", "blocklisted_at", "face_image", "document_type", "document_number", "front_image", "phone_number", "country_code", "email" ], "properties": { "type": { "type": "string", "enum": [ "face", "document", "phone", "email" ], "description": "Cosa è stato inserito nella blocklist." }, "session_id": { "type": "string", "format": "uuid", "description": "Sessione di verifica a cui appartiene l'elemento." }, "session_number": { "type": "integer", "nullable": true, "description": "Numero della sessione con ambito limitato all'applicazione, come mostrato nella console." }, "blocklisted_at": { "type": "string", "format": "date-time", "description": "Quando l'elemento è stato inserito l'ultima volta nella blocklist." }, "face_image": { "type": "string", "nullable": true, "description": "Elementi del volto: URL firmato di breve durata, emesso nuovamente a ogni chiamata; `null` per una chiave API con ambito senza `media: read`. Anche `null` quando non è memorizzata alcuna immagine di riferimento." }, "document_type": { "type": "string", "nullable": true, "description": "Elementi del documento: codice del tipo di documento, ad esempio `P` (passaporto), `ID` (carta d'identità), `DL` (patente di guida) o `RP` (permesso di soggiorno)." }, "document_number": { "type": "string", "nullable": true, "description": "Elementi del documento: il numero del documento o il numero personale quando il documento non ne ha uno." }, "front_image": { "type": "string", "nullable": true, "description": "Elementi del documento: immagine frontale del documento, URL firmato di breve durata, riemesso a ogni chiamata; `null` per una chiave API con ambito priva di `media: read`." }, "phone_number": { "type": "string", "nullable": true, "description": "Elementi telefonici: il numero di telefono in formato E.164." }, "country_code": { "type": "string", "nullable": true, "description": "Elementi telefonici: paese ISO 3166-1 alpha-2 del numero." }, "email": { "type": "string", "nullable": true, "description": "Elementi email: l'indirizzo email." } } }, "TransactionNote": { "type": "object", "description": "Una nota sulla cronologia di revisione di una transazione monitorata.", "required": [ "uuid", "note", "actor_email", "actor_name", "metadata", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificatore della nota." }, "note": { "type": "string", "description": "Corpo della nota in testo normale." }, "actor_email": { "type": "string", "format": "email", "nullable": true, "description": "Email dell'utente della Console che ha scritto la nota o modificato lo stato. `null` per le note create con una chiave API e per le note aggiunte automaticamente da Didit." }, "actor_name": { "type": "string", "nullable": true, "description": "Nome visualizzato dell'utente della Console (la sua email se non ha un nome). `Rule Engine` per le note aggiunte automaticamente da Didit. `null` per le note create con una chiave API." }, "metadata": { "type": "object", "description": "Distingue le tipologie di note. Le note inserite tramite l'API o la Console includono `mentioned_emails`. Una modifica di stato effettuata nella Console include `type: status_change` con `previous_status`, `new_status`, `reason_code` e `reason_label`. Le note aggiunte da Didit contengono `source`: `rule_action` (con `rule_uuid`) per l'azione `add_note` di una regola, oppure `remediation_session` in caso di errore nella creazione della sessione di verifica dell'azione utente.", "properties": { "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Membri dell'organizzazione menzionati, in lettere minuscole e deduplicati. Vuoto se nessuno è stato menzionato." }, "type": { "type": "string", "enum": [ "status_change" ], "description": "Presente sulle note che registrano una modifica di stato effettuata nella Console." }, "previous_status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Stato prima della modifica." }, "new_status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Stato dopo la modifica." }, "reason_code": { "type": "string", "nullable": true, "description": "Codice del motivo specificato con la modifica." }, "reason_label": { "type": "string", "nullable": true, "description": "Etichetta del motivo specificata con la modifica." }, "source": { "type": "string", "enum": [ "rule_action", "remediation_session" ], "description": "Presente sulle note aggiunte automaticamente da Didit." }, "rule_uuid": { "type": "string", "format": "uuid", "description": "Regola la cui azione `add_note` ha scritto la nota (con `source: rule_action`)." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Quando la nota è stata salvata." } } }, "TransactionSummary": { "type": "object", "description": "Riepilogo di una transazione monitorata, nella struttura elencata da `GET /v3/transactions/`. Chiama `GET /v3/transactions/{transaction_id}/` con `uuid` per le parti, gli alert e le esecuzioni delle regole.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID della transazione Didit. Utilizzalo come `{transaction_id}` negli endpoint delle transazioni." }, "transaction_number": { "type": "integer", "nullable": true, "description": "Numero sequenziale con ambito limitato all'applicazione mostrato nella Console." }, "txn_id": { "type": "string", "nullable": true, "description": "Il tuo identificatore dalla chiamata di creazione. Univoco per applicazione." }, "transaction_type": { "type": "string", "description": "Categoria come memorizzata: `finance`, `kyc`, `travelRule`, `userPlatformEvent`, `gamblingBet`, `gamblingLimitChange`, `gamblingBonusChange` o `auditTrailEvent`." }, "action_type": { "type": "string", "description": "Sottotipo all'interno della categoria, ad esempio `withdrawal`." }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "Verdetto di monitoraggio attuale." }, "source": { "type": "string", "enum": [ "LIVE", "IMPORTED" ], "description": "`LIVE` per le transazioni inviate per il monitoraggio, `IMPORTED` per le importazioni storiche." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Direzione rispetto al soggetto." }, "amount": { "type": "string", "description": "Importo come stringa decimale senza zeri finali (fino a 18 cifre decimali)." }, "currency": { "type": "string", "description": "Codice valuta o simbolo dell'asset crypto di `amount`." }, "currency_type": { "type": "string", "nullable": true, "description": "`fiat` o `crypto` se noto." }, "preferred_currency_amount": { "type": "string", "nullable": true, "description": "`amount` convertito nella valuta preferita dell'applicazione, quando era disponibile un tasso di cambio." }, "preferred_currency_code": { "type": "string", "nullable": true, "description": "Valuta di `preferred_currency_amount`." }, "payment_details": { "type": "string", "nullable": true, "description": "Riferimento di pagamento in formato testo libero." }, "txn_date": { "type": "string", "format": "date-time", "description": "Quando è avvenuta la transazione." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando Didit lo ha registrato." }, "score": { "type": "integer", "description": "Punteggio di rischio. Più alto indica un rischio maggiore." }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "Gravità del rischio, `null` finché non viene impostata." }, "decision_reason_code": { "type": "string", "nullable": true, "description": "Motivo leggibile dalla macchina per il `status` attuale." }, "decision_reason_label": { "type": "string", "nullable": true, "description": "Etichetta di facile lettura per `decision_reason_code`." }, "tags": { "type": "array", "description": "Tag sulla transazione.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "description": "Colore esadecimale, ad esempio `#F59E0B`." }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "Tag predefinito Didit o personalizzato." } } } }, "subject_name": { "type": "string", "nullable": true, "description": "Nome completo della parte `APPLICANT`." }, "subject_vendor_data": { "type": "string", "nullable": true, "description": "Il tuo `vendor_data` per il richiedente." }, "subject_type": { "type": "string", "nullable": true, "enum": [ "user", "business", null ], "description": "Indica se il richiedente è collegato a un utente o a un'azienda di Didit; `null` quando non è collegato a nessuno dei due." }, "subject_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "UUID dell'utente o dell'azienda Didit a cui è collegato il richiedente." }, "subject_country": { "type": "string", "nullable": true, "description": "Codice del paese del richiedente." }, "counterparty_name": { "type": "string", "nullable": true, "description": "Nome completo della parte `COUNTERPARTY`, se presente." }, "counterparty_vendor_data": { "type": "string", "nullable": true, "description": "Il tuo `vendor_data` per la controparte." }, "counterparty_country": { "type": "string", "nullable": true, "description": "Codice del paese della controparte." }, "assigned_to_name": { "type": "string", "nullable": true, "description": "Nome del revisore della Console assegnato alla transazione." }, "travel_rule_status": { "type": "string", "nullable": true, "description": "Stato del trasferimento Travel Rule della transazione, o `null` se non ne ha nessuno." }, "application_id": { "type": "string", "format": "uuid", "description": "Applicazione a cui appartiene la transazione." }, "application_name": { "type": "string", "nullable": true, "description": "Nome di tale applicazione." }, "organization_id": { "type": "string", "format": "uuid", "description": "Organizzazione proprietaria dell'applicazione." }, "organization_name": { "type": "string", "nullable": true, "description": "Nome di tale organizzazione." } } }, "ApplicationAnalyticsDataPoint": { "type": "object", "description": "Conteggi delle sessioni per un giorno, per data di creazione (UTC). Ciascun conteggio riflette lo stato corrente della sessione. I punti del periodo precedente contengono almeno i campi obbligatori.", "required": [ "rounded_date", "total", "approved", "declined", "canceled", "pending" ], "properties": { "rounded_date": { "type": "string", "format": "date", "description": "Il giorno, `YYYY-MM-DD`." }, "total": { "type": "integer", "description": "Sessioni create in quel giorno." }, "approved": { "type": "integer", "description": "Di queste, sessioni `Approved` o `Kyc Expired`." }, "declined": { "type": "integer", "description": "Sessioni `Declined`." }, "canceled": { "type": "integer", "description": "Sessioni `Expired` o `Abandoned`." }, "pending": { "type": "integer", "description": "Sessioni `Not Started`, `In Progress` o `In Review`." }, "in_review": { "type": "integer", "description": "Sessioni `In Review`." }, "expired": { "type": "integer", "description": "Sessioni `Expired`." }, "abandoned": { "type": "integer", "description": "Sessioni `Abandoned`." }, "in_progress": { "type": "integer", "description": "Sessioni `In Progress`." }, "not_started": { "type": "integer", "description": "Sessioni `Not Started`." }, "manually_approved": { "type": "integer", "description": "Sessioni approvate da un revisore dopo che il workflow ha emesso un altro verdetto." }, "manually_declined": { "type": "integer", "description": "Sessioni rifiutate da un revisore dopo che il workflow ha emesso un altro verdetto." } } }, "ApplicationAnalyticsRequestBreakdown": { "type": "object", "description": "Totali degli stati per l'intervallo. La suddivisione del periodo precedente contiene almeno i campi obbligatori.", "required": [ "total_approved", "total_in_review", "total_declined", "total_canceled", "total_pending" ], "properties": { "total_approved": { "type": "integer", "description": "Sessioni `Approved` o `Kyc Expired`." }, "total_in_review": { "type": "integer", "description": "Sessioni `In Review`." }, "total_declined": { "type": "integer", "description": "Sessioni `Declined`." }, "total_canceled": { "type": "integer", "description": "Sessioni `Expired` o `Abandoned`." }, "total_pending": { "type": "integer", "description": "Sessioni `Not Started`, `In Progress` o `In Review` (include `total_in_review`)." }, "total_expired": { "type": "integer", "description": "Sessioni `Expired`." }, "total_abandoned": { "type": "integer", "description": "Sessioni `Abandoned`." }, "total_in_progress": { "type": "integer", "description": "Sessioni `In Progress`." }, "total_not_started": { "type": "integer", "description": "Sessioni `Not Started`." }, "total_manually_approved": { "type": "integer", "description": "Approvata da un revisore." }, "total_manually_declined": { "type": "integer", "description": "Rifiutata da un revisore." } } }, "ApplicationAnalyticsCountryCount": { "type": "object", "properties": { "country": { "type": "string", "description": "Nome del paese." }, "country_code": { "type": "string", "description": "Codice paese a due lettere." }, "session_count": { "type": "integer", "description": "Sessioni provenienti da quel paese." } } }, "ApplicationAnalyticsLocationStats": { "type": "object", "properties": { "ip_countries": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsCountryCount" }, "description": "Paesi degli indirizzi degli utenti, ordinati per numero decrescente di sessioni." }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsCountryCount" }, "description": "Stesso elenco di `ip_countries`." }, "id_countries": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsCountryCount" }, "description": "Paesi di emissione dei documenti d'identità verificati, con il maggior numero di sessioni per primi." }, "conversion_by_country": { "type": "array", "description": "Per paese di emissione del documento: sessioni concluse (approvata, rifiutata o in revisione) e quante sono state approvate. Ordinate per numero di completate decrescente.", "items": { "type": "object", "properties": { "country": { "type": "string" }, "country_code": { "type": "string" }, "finished": { "type": "integer" }, "approved": { "type": "integer" } } } }, "cities": { "type": "array", "description": "Fino a 100 città IP, ordinate a partire da quelle con più sessioni.", "items": { "type": "object", "properties": { "location": { "type": "string", "description": "`City, Country`." }, "session_count": { "type": "integer" }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true } } } } } }, "ApplicationAnalyticsDemographicStats": { "type": "object", "properties": { "age_distribution": { "type": "object", "description": "Sessioni per fascia d'età rilevata dal documento d'identità. Vuoto in assenza di dati.", "properties": { "under_18": { "type": "integer" }, "18_24": { "type": "integer" }, "25_34": { "type": "integer" }, "35_44": { "type": "integer" }, "45_64": { "type": "integer" }, "65_plus": { "type": "integer" } }, "additionalProperties": { "type": "integer" } }, "gender_distribution": { "type": "object", "description": "Sessioni per codice di genere del documento: `M`, `F` o `U` (sconosciuto).", "additionalProperties": { "type": "integer" } } } }, "ApplicationAnalyticsDeviceDetails": { "type": "object", "description": "I primi cinque per ciascuno, ordinati per numero decrescente di sessioni.", "properties": { "device_models": { "type": "array", "description": "Brand dei dispositivi: `Apple`, `Android`, `LG`, tutti gli altri raggruppati come `Other`.", "items": { "type": "object", "properties": { "device": { "type": "string" }, "count": { "type": "integer" } } } }, "browsers": { "type": "array", "description": "Browser: `Chrome`, `Safari`, `Didit App`, `Firefox`, tutto il resto raggruppato come `Other`.", "items": { "type": "object", "properties": { "browser": { "type": "string" }, "count": { "type": "integer" } } } }, "operating_systems": { "type": "array", "description": "Sistemi operativi.", "items": { "type": "object", "properties": { "os": { "type": "string" }, "count": { "type": "integer" } } } } } }, "ApplicationAnalyticsWorkflowFunnel": { "type": "object", "description": "Indicizzato per ID del workflow. `total` indica le sessioni avviate su quel workflow; `steps` conta le sessioni che hanno raggiunto ciascun passaggio (`OCR`, `LIVENESS`, `FACE_MATCH`, `AML`, `POA`, `PHONE`, `EMAIL`, `NFC`, `DATABASE_VALIDATION`, `QUESTIONNAIRE`, `IP_ANALYSIS`, `AGE_ESTIMATION`, `KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`). Il raggiungimento di un passaggio non equivale al suo superamento.", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "steps": { "type": "object", "additionalProperties": { "type": "object", "properties": { "reached": { "type": "integer" } } } } } } }, "ApplicationAnalyticsVerificationTimeStats": { "type": "object", "description": "Tempo attivo trascorso dagli utenti durante la verifica, ignorando i periodi di inattività. Un oggetto vuoto in assenza di dati.", "properties": { "overall_avg_seconds": { "type": "number", "description": "Media per sessione, un decimale." }, "overall_count": { "type": "integer", "description": "Sessioni misurate." }, "per_feature": { "type": "object", "description": "Indicizzato per funzionalità, ad esempio `OCR` o `LIVENESS`.", "additionalProperties": { "type": "object", "properties": { "avg_seconds": { "type": "number" }, "total_seconds": { "type": "number" }, "count": { "type": "integer" } } } }, "per_sub_step": { "type": "object", "description": "Indicizzato per funzionalità, quindi per sotto-passaggio, ad esempio `front_id_photo`.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "avg_seconds": { "type": "number" }, "total_seconds": { "type": "number" }, "count": { "type": "integer" } } } } } } }, "ApplicationAnalyticsResubmissionStats": { "type": "object", "properties": { "first_pass": { "type": "integer", "description": "Sessioni completate senza nuovo invio." }, "second": { "type": "integer", "description": "Sessioni completate inviate nuovamente una volta." }, "third_plus": { "type": "integer", "description": "Sessioni completate inviate nuovamente due o più volte." }, "abandoned": { "type": "integer", "description": "Sessioni abbandonate." } } }, "ApplicationAnalyticsOriginalStatusStats": { "type": "object", "description": "Il verdetto automatico del workflow, prima che qualsiasi revisore lo modificasse.", "properties": { "approved": { "type": "integer" }, "in_review": { "type": "integer" }, "declined": { "type": "integer" } } }, "ApplicationAnalyticsWarningStats": { "type": "object", "description": "Indicizzato per funzionalità (`ID_VERIFICATION`, `LIVENESS`, `FACEMATCH`, `AML`, `PROOF_OF_ADDRESS`, `PHONE`, `EMAIL`, `NFC`, `LOCATION`, `DATABASE_VALIDATION`, `QUESTIONNAIRE` e le funzionalità KYB). `total` indica le sessioni che hanno raggiunto la funzionalità; `risks` conta le sessioni per codice e livello di avviso.", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "risks": { "type": "object", "additionalProperties": { "type": "object", "properties": { "error": { "type": "integer" }, "warning": { "type": "integer" }, "information": { "type": "integer" } } } } } } }, "ApplicationAnalyticsDemographicPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chiave del periodo: `YYYY-MM-DD` per un giorno, il lunedì di una settimana, o `YYYY-MM` per un mese, in base a `grouping_mode`." }, "age_distribution": { "type": "object", "additionalProperties": { "type": "integer" } }, "gender_distribution": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "ApplicationAnalyticsDevicePoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chiave del periodo: `YYYY-MM-DD` per un giorno, il lunedì di una settimana, o `YYYY-MM` per un mese, in base a `grouping_mode`." }, "devices": { "type": "object", "additionalProperties": { "type": "integer" } }, "browsers": { "type": "object", "additionalProperties": { "type": "integer" } }, "operating_systems": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "ApplicationAnalyticsVerificationTimePoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chiave del periodo: `YYYY-MM-DD` per un giorno, il lunedì di una settimana, o `YYYY-MM` per un mese, in base a `grouping_mode`." }, "overall_avg": { "type": "number", "description": "Secondi attivi medi per sessione." }, "per_feature": { "type": "object", "description": "Secondi attivi medi per funzionalità.", "additionalProperties": { "type": "number" } } } }, "ApplicationAnalyticsResubmissionPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chiave del periodo: `YYYY-MM-DD` per un giorno, il lunedì di una settimana, o `YYYY-MM` per un mese, in base a `grouping_mode`." }, "first_pass": { "type": "integer" }, "second": { "type": "integer" }, "third_plus": { "type": "integer" }, "abandoned": { "type": "integer" } } }, "ApplicationAnalyticsOriginalStatusPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Chiave del periodo: `YYYY-MM-DD` per un giorno, il lunedì di una settimana, o `YYYY-MM` per un mese, in base a `grouping_mode`." }, "approved": { "type": "integer" }, "in_review": { "type": "integer" }, "declined": { "type": "integer" } } }, "ApplicationAnalyticsSummary": { "type": "object", "description": "Riepilogo della verifica degli utenti (KYC), restituito quando non vengono inviati né `scope` né `widget_keys`.", "required": [ "data_points", "request_breakdown", "previous_data_points", "previous_request_breakdown", "conversion_rate", "location_stats", "demographic_stats", "device_details", "workflow_funnel_stats", "verification_time_stats", "resubmission_stats", "warning_stats", "original_status_stats", "grouping_mode", "demographic_time_series", "device_time_series", "verification_time_time_series", "resubmission_time_series", "original_status_time_series" ], "properties": { "data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" }, "description": "Un punto al giorno, dal primo giorno con sessioni nell'intervallo fino a `end_date`. Sempre giornaliero, indipendentemente dal valore di `grouping_mode`." }, "request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "previous_data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" }, "description": "Punti giornalieri per il periodo della stessa durata immediatamente precedente a `start_date`." }, "previous_request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "conversion_rate": { "type": "number", "nullable": true, "description": "`total_approved / (total_approved + total_declined + total_in_review) x 100`, con un decimale. `null` se nessuna operazione è terminata." }, "location_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsLocationStats" }, "demographic_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicStats" }, "device_details": { "$ref": "#/components/schemas/ApplicationAnalyticsDeviceDetails" }, "workflow_funnel_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWorkflowFunnel" }, "verification_time_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimeStats" }, "resubmission_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionStats" }, "warning_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWarningStats" }, "original_status_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusStats" }, "grouping_mode": { "type": "string", "enum": [ "day", "week", "month" ], "description": "In che modo sono raggruppati gli elenchi `*_time_series`: `day` fino a 14 giorni, `week` fino a 90, `month` oltre. Misurato a partire dal primo giorno con sessioni nell'intervallo." }, "demographic_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicPoint" } }, "device_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDevicePoint" } }, "verification_time_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimePoint" } }, "resubmission_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionPoint" } }, "original_status_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusPoint" } } } }, "ApplicationAnalyticsWidget": { "type": "object", "description": "Un widget della dashboard. Ogni widget ha `kind` e `title`; gli altri campi dipendono da `kind`. I widget della sessione riutilizzano gli oggetti di riepilogo (`data_points`, `request_breakdown`, `workflow_funnel_stats` e così via); i widget di tipo elenco inseriscono le voci in `items`; le metriche delle transazioni usano `value`.", "required": [ "kind", "title" ], "properties": { "kind": { "type": "string", "enum": [ "sessions_volume", "workflow_funnel", "average_verification_time", "country_distribution", "warning_insights", "conversion_rate", "conversion_by_country", "resubmission_insights", "original_status_distribution", "database_validation_coverage", "database_validation_latency", "demographics", "device_details", "horizontal_bar", "kyb_registry_coverage", "kyb_registry_data_completeness", "metric", "time_series", "breakdown", "status_time_series", "leaderboard", "histogram" ], "description": "Tipo di widget." }, "title": { "type": "string", "description": "Titolo visualizzato, ad esempio `Verification volume`." }, "grouping_mode": { "type": "string", "enum": [ "day", "week", "month" ], "description": "In che modo sono raggruppati gli elenchi `*_time_series`: `day` fino a 14 giorni, `week` fino a 90, `month` oltre. Misurato a partire dal primo giorno con sessioni nell'intervallo." }, "data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" } }, "request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "previous_data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" } }, "previous_request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "conversion_rate": { "type": "number", "nullable": true }, "workflow_funnel_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWorkflowFunnel" }, "verification_time_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimeStats" }, "verification_time_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimePoint" } }, "warning_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWarningStats" }, "resubmission_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionStats" }, "resubmission_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionPoint" } }, "original_status_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusStats" }, "original_status_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusPoint" } }, "demographic_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicStats" }, "demographic_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicPoint" } }, "device_details": { "$ref": "#/components/schemas/ApplicationAnalyticsDeviceDetails" }, "device_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDevicePoint" } }, "items": { "type": "array", "description": "Voci di un widget a elenco. `country_distribution` (KYC): `country`, `country_code`, `session_count`. `conversion_by_country`: `country`, `country_code`, `finished`, `approved`. `time_series`: `date`, `value`. `status_time_series`: `date`, `approved`, `declined`, `flagged`. `breakdown`: `transaction_type` o `action_type` con `count` e `volume`, oppure `tag_id`, `tag_name`, `count`. `leaderboard`: `rule_title`, `trigger_count` o `assignee`, `handled_count`, `average_processing_seconds`, ciascuno con `approved_percentage`, `declined_percentage`, `flagged_percentage`. `histogram`: `score`, `count`.", "items": { "type": "object", "additionalProperties": {} } }, "previous_items": { "type": "array", "description": "Serie temporale delle transazioni per il periodo della stessa durata immediatamente precedente a `start_date`.", "items": { "type": "object", "additionalProperties": {} } }, "value": { "type": "number", "description": "Widget `metric`: il valore relativo all'intervallo." }, "currency": { "type": "string", "nullable": true, "description": "Widget per volume e importo delle transazioni: valuta predefinita delle transazioni dell'applicazione." }, "thresholds": { "type": "object", "description": "Widget `histogram`: le soglie di punteggio per la revisione e il rifiuto dell'applicazione.", "properties": { "review": { "type": "integer" }, "decline": { "type": "integer" } } }, "search": { "type": "object", "description": "Widget `kyb_registry_coverage`: totali delle ricerche nel registro.", "properties": { "searches_total": { "type": "integer" }, "searches_with_no_candidates": { "type": "integer" } } } } }, "ApplicationAnalyticsWidgetResponse": { "type": "object", "description": "Widget della dashboard, restituiti quando viene inviato `scope` o `widget_keys`.", "required": [ "scope", "available_widget_keys", "requested_widget_keys", "widgets" ], "properties": { "scope": { "type": "string", "enum": [ "home", "kyc", "kyb", "transactions" ], "description": "Scheda della dashboard." }, "available_widget_keys": { "type": "array", "items": { "type": "string" }, "description": "Ogni chiave widget accettata da questo ambito." }, "requested_widget_keys": { "type": "array", "items": { "type": "string" }, "description": "Le chiavi del widget a cui è stata data risposta, in ordine: le tue `widget_keys` valide o i valori predefiniti dell'ambito." }, "widgets": { "type": "object", "description": "Indicizzato per chiave del widget, nell'ordine di `requested_widget_keys`.", "additionalProperties": { "$ref": "#/components/schemas/ApplicationAnalyticsWidget" } } } }, "ApplicationAnalyticsToday": { "type": "object", "description": "Verifiche di oggi per ora locale rispetto allo stesso giorno della settimana scorsa.", "required": [ "time_zone", "date", "current_hour", "previous_date", "hours", "previous_hours", "total", "previous_total_so_far", "outcomes" ], "properties": { "time_zone": { "type": "string", "description": "Il fuso orario IANA a cui si riferiscono il giorno e i relativi orari.", "example": "Europe/Madrid" }, "date": { "type": "string", "format": "date", "description": "Oggi in quel fuso orario.", "example": "2026-10-30" }, "current_hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "L'ora locale attuale.", "example": 14 }, "previous_date": { "type": "string", "format": "date", "description": "Il giorno di confronto: lo stesso giorno della settimana una settimana prima.", "example": "2026-10-23" }, "hours": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 24, "maxItems": 24, "description": "Verifiche create oggi, per ora locale a partire dalle 00:00. Le ore non ancora trascorse sono pari a 0." }, "previous_hours": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 24, "maxItems": 24, "description": "Verifiche create nel giorno di confronto, per ora locale a partire dalle 00:00." }, "total": { "type": "integer", "minimum": 0, "description": "Verifiche create oggi fino a questo momento.", "example": 165 }, "previous_total_so_far": { "type": "integer", "minimum": 0, "description": "Verifiche create nel giorno di confronto fino alla stessa ora locale.", "example": 151 }, "outcomes": { "type": "object", "description": "Delle verifiche di oggi, quante sono approvate, in attesa di revisione e rifiutate al momento. Il resto non è ancora completato.", "required": [ "approved", "in_review", "declined" ], "properties": { "approved": { "type": "integer", "minimum": 0 }, "in_review": { "type": "integer", "minimum": 0 }, "declined": { "type": "integer", "minimum": 0 } } } } }, "WebhookConfigDestination": { "type": "object", "description": "Una destinazione webhook così come elencata nella configurazione dei webhook, senza metriche di consegna. `GET /v3/webhook/destinations/{destination_uuid}/` aggiunge il relativo riepilogo di consegna.", "required": [ "uuid", "label", "url", "enabled", "webhook_version", "secret_shared_key", "subscribed_events", "created_at", "updated_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID della destinazione." }, "label": { "type": "string", "maxLength": 255, "description": "Nome leggibile dall'utente." }, "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Endpoint HTTPS a cui Didit invia gli eventi." }, "enabled": { "type": "boolean", "description": "`false` sospende le consegne verso questa destinazione." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versione del payload inviata a questa destinazione." }, "secret_shared_key": { "type": "string", "description": "Il segreto di firma di questa destinazione (token URL-safe di 43 caratteri). Verifica ogni webhook con il segreto della destinazione a cui è stato inviato. I chiamanti con chiave API lo ricevono sempre per intero; gli utenti della Console privi di `read:webhooks` ricevono una stringa vuota." }, "subscribed_events": { "type": "array", "uniqueItems": true, "description": "Tipi di evento consegnati a questa destinazione. Vuoto se la destinazione è stata creata senza eventi, nel qual caso non riceve nulla.", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookConfig": { "type": "object", "description": "Configurazione dei webhook a livello di applicazione, policy di conservazione e host di ritorno del wallet Digital ID, con ogni destinazione webhook.", "required": [ "webhook_url", "webhook_version", "secret_shared_key", "capture_method", "data_retention_months", "face_retention_policy", "face_retention_days", "available_events", "allowed_return_hosts", "endpoints" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL del webhook a livello di applicazione (legacy). Didit invia le notifiche a questo URL solo se l'applicazione non ha destinazioni abilitate, e in tal caso invia solo `status.updated` e `data.updated`. Ogni operazione di creazione, aggiornamento o eliminazione di una destinazione lo imposta sull'URL della destinazione abilitata più vecchia, oppure su `null` se nessuna è abilitata." }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Versione del payload del `webhook_url` legacy. Ciascuna destinazione ha il proprio `webhook_version`." }, "secret_shared_key": { "type": "string", "description": "Segreto di firma a livello di applicazione (token URL-safe di 43 caratteri). Firma solo le consegne al `webhook_url` legacy; ciascuna destinazione firma con la propria `secret_shared_key`. I chiamanti autenticati tramite chiave API lo ricevono sempre per intero; gli utenti della Console privi dell'autorizzazione `read:webhooks` ricevono una stringa vuota." }, "capture_method": { "type": "string", "enum": [ "MOBILE", "MOBILE_AND_DESKTOP" ], "description": "Impostazione legacy dell'applicazione. Il flusso di verifica non la legge: le opzioni di acquisizione sono configurate per workflow." }, "data_retention_months": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 120, "description": "Finestra di eliminazione automatica. Le sessioni di verifica degli utenti create più di questo numero di mesi fa (un mese corrisponde a 30 giorni) vengono eliminate automaticamente e tale eliminazione è irreversibile. `null` indica che le sessioni non vengono mai eliminate automaticamente. Consulta [Conservazione dei dati](https://docs.didit.me/it/console/data-retention)." }, "face_retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "Cosa succede all'embedding facciale di una sessione quando la sessione viene eliminata. `delete_with_session` (predefinito) lo elimina con la sessione. `retain_until_user_deleted` è l'opzione facoltativa per la [conservazione del modello biometrico](https://docs.didit.me/it/console/data-retention#conservazione-del-modello-biometrico): un modello biometrico privo di immagini collegato all'Utente viene gestito separatamente fino al termine del periodo di conservazione, all'eliminazione dell'Utente o alla sua eliminazione definitiva." }, "face_retention_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 3650, "description": "Periodo di conservazione, in giorni, dei modelli biometrici secondo `retain_until_user_deleted`. Obbligatorio quando tale criterio è impostato." }, "biometric_consent_mode": { "type": "string", "enum": [ "auto", "always", "never" ], "description": "Quando il flusso ospitato e gli SDK nativi richiedono alla persona il consenso biometrico esplicito prima dell'acquisizione del volto. `auto` (predefinito) lo richiede solo quando si applica un trigger: uno stato dichiarato, l'IP della persona o l'emittente del documento d'identità si trova in Illinois, Texas o Colorado, oppure la persona sembra trovarsi negli Stati Uniti senza uno stato noto. `always` lo richiede a ogni persona il cui workflow acquisisce un volto. `never` non mostra mai il passaggio, e raccogli tu stesso il consenso prima del selfie. Ogni modifica viene registrata nel registro di audit. Consulta [Consenso biometrico](https://docs.didit.me/it/getting-started/biometric-consent)." }, "available_events": { "type": "array", "description": "Ogni tipo di evento a cui una destinazione può iscriversi, con un'etichetta visibile.", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "$ref": "#/components/schemas/WebhookEvent" }, "label": { "type": "string", "description": "Etichetta visualizzata, ad esempio `Session status updated`." } } } }, "allowed_return_hosts": { "type": "array", "maxItems": 20, "description": "Hostname (corrispondenza esatta, solo HTTPS) a cui una verifica del wallet Digital ID autonoma può rimandare l'utente con il suo `return_url`. Anche il tuo dominio white label è sempre consentito. Consulta [Registra la tua destinazione di ritorno](https://docs.didit.me/it/standalone-apis/digital-id-wallets#registra-la-tua-destinazione-di-ritorno).", "items": { "type": "string", "maxLength": 253 } }, "endpoints": { "type": "array", "description": "Ogni destinazione webhook dell'applicazione, dalla più vecchia alla più recente, ciascuna con il rispettivo segreto di firma. Qui in sola lettura: gestisci le destinazioni con gli endpoint `/v3/webhook/destinations/`.", "items": { "$ref": "#/components/schemas/WebhookConfigDestination" } }, "allowed_domains": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 }, "description": "Origini (ad esempio `https://app.example.com`; `http` consentito solo per `localhost`) in cui il flusso di verifica ospitato può essere incorporato e a cui può reindirizzare l'utente con un callback di sessione. Le chiamate server-to-server non sono interessate. Un elenco vuoto indica che non vi sono restrizioni. Didit memorizza ciascuna origine in lettere minuscole e senza porta predefinita. Una voce non valida genera un errore `400` su `allowed_domains`.", "example": [ "https://app.example.com" ] } } }, "WebhookDestinationDelivery": { "type": "object", "description": "Un tentativo di consegna a una destinazione webhook. Il primo invio di un evento, ogni nuovo tentativo automatico e ogni reinvio costituiscono consegne separate.", "required": [ "uuid", "session_id", "request_url", "response_status", "response_time_ms", "status", "webhook_type", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID consegna, per le chiamate per i dettagli e per il nuovo invio." }, "session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessione di verifica dell'utente a cui si riferisce l'evento. `null` per eventi relativi a sessioni aziendali, utenti, aziende, transazioni, Travel Rule e workflow." }, "request_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL a cui è stata inviata la consegna: l'URL della destinazione al momento della generazione dell'evento." }, "response_status": { "type": "integer", "nullable": true, "description": "Stato HTTP restituito dal tuo endpoint. `null` finché la consegna è in coda e non è ancora stata tentata. Quando non è stata ricevuta alcuna risposta HTTP, Didit registra un proprio stato: `504` se il tuo endpoint non risponde entro 5 secondi, `503` in caso di errore di connessione, `400` se l'URL viene rifiutato perché non sicuro (ad esempio un indirizzo privato o interno) e `404` per qualsiasi altro errore della richiesta. Un codice `400` o superiore è considerato una consegna non riuscita." }, "response_time_ms": { "type": "integer", "nullable": true, "minimum": 0, "description": "Tempo impiegato dal tentativo, in millisecondi. `null` mentre la consegna è in coda." }, "status": { "type": "string", "nullable": true, "description": "Stato segnalato dall'evento al momento della generazione: lo stato della sessione per gli eventi di sessione (ad esempio `Approved` o `In Review`), lo stato della persona o dell'azienda per gli eventi utente e aziendali, e lo stato della transazione per gli eventi di transazione. `null` per gli eventi che non contengono alcuno stato." }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "created_at": { "type": "string", "format": "date-time", "description": "Data e ora di creazione della consegna." } } }, "WebhookDestinationDeliveryDetail": { "type": "object", "description": "Un tentativo di consegna a una destinazione webhook, con le intestazioni e il corpo esatti della richiesta inviati da Didit.", "required": [ "uuid", "session_id", "request_url", "response_status", "response_time_ms", "status", "webhook_type", "created_at", "request_header", "request_body" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID consegna, per le chiamate per i dettagli e per il nuovo invio." }, "session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessione di verifica dell'utente a cui si riferisce l'evento. `null` per eventi relativi a sessioni aziendali, utenti, aziende, transazioni, Travel Rule e workflow." }, "request_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL a cui è stata inviata la consegna: l'URL della destinazione al momento della generazione dell'evento." }, "response_status": { "type": "integer", "nullable": true, "description": "Stato HTTP restituito dal tuo endpoint. `null` finché la consegna è in coda e non è ancora stata tentata. Quando non è stata ricevuta alcuna risposta HTTP, Didit registra un proprio stato: `504` se il tuo endpoint non risponde entro 5 secondi, `503` in caso di errore di connessione, `400` se l'URL viene rifiutato perché non sicuro (ad esempio un indirizzo privato o interno) e `404` per qualsiasi altro errore della richiesta. Un codice `400` o superiore è considerato una consegna non riuscita." }, "response_time_ms": { "type": "integer", "nullable": true, "minimum": 0, "description": "Tempo impiegato dal tentativo, in millisecondi. `null` mentre la consegna è in coda." }, "status": { "type": "string", "nullable": true, "description": "Stato segnalato dall'evento al momento della generazione: lo stato della sessione per gli eventi di sessione (ad esempio `Approved` o `In Review`), lo stato della persona o dell'azienda per gli eventi utente e aziendali, e lo stato della transazione per gli eventi di transazione. `null` per gli eventi che non contengono alcuno stato." }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "created_at": { "type": "string", "format": "date-time", "description": "Data e ora di creazione della consegna." }, "request_header": { "type": "string", "description": "Testo JSON (una stringa) delle intestazioni della richiesta inviate da Didit: `Content-Type`, `X-Signature`, `X-Signature-V2`, `X-Signature-Simple`, `X-Timestamp` e `User-Agent`. Analizzalo con un parser JSON. Contiene le firme, mai il segreto di firma." }, "request_body": { "type": "string", "description": "Testo JSON (una stringa) del payload esatto inviato da Didit, con chiavi ordinate, inclusi `event_id` e `timestamp`. Analizzalo con un parser JSON; vedi [Payload shape](https://docs.didit.me/it/integration/webhooks#struttura-del-payload). Per una chiave con ambito limitato senza `media: read`, gli URL dei file multimediali al suo interno sono `null`; senza `sessions: write`, i token di sessione e i link di verifica ospitati sono `null`. Un corpo modificato in questo modo non corrisponde più alle sue firme. Didit non registra il corpo della risposta restituito dal tuo endpoint." } } }, "SessionWebhookDelivery": { "type": "object", "description": "Un singolo tentativo di consegna webhook registrato per una sessione di verifica, con le intestazioni e il corpo esatti della richiesta inviati da Didit.", "required": [ "uuid", "session_id", "request_url", "response_status", "status", "webhook_type", "request_header", "request_body", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "ID consegna. Utilizzalo come `{webhook_uuid}` per recuperare o inviare nuovamente questa consegna." }, "session_id": { "type": "string", "format": "uuid", "description": "La sessione a cui appartiene la consegna (la sessione nel percorso)." }, "request_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL a cui è stata inviata la consegna." }, "response_status": { "type": "integer", "nullable": true, "description": "Stato HTTP restituito dal tuo endpoint. `null` finché la consegna è in coda e non è ancora stata tentata. Quando non è stata ricevuta alcuna risposta HTTP, Didit registra un proprio stato: `504` se il tuo endpoint non risponde entro 5 secondi, `503` in caso di errore di connessione, `400` se l'URL viene rifiutato perché non sicuro (ad esempio un indirizzo privato o interno) e `404` per qualsiasi altro errore della richiesta. Un codice `400` o superiore è considerato una consegna non riuscita." }, "status": { "type": "string", "nullable": true, "description": "Stato della sessione al momento della generazione dell'evento, ad esempio `In Progress`, `Approved` o `Declined`." }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "request_header": { "type": "string", "description": "Testo JSON (una stringa) delle intestazioni della richiesta inviate da Didit: `Content-Type`, `X-Signature`, `X-Signature-V2`, `X-Signature-Simple`, `X-Timestamp` e `User-Agent`. Analizzalo con un parser JSON. Contiene le firme, mai il segreto di firma." }, "request_body": { "type": "string", "description": "Testo JSON (una stringa) del payload esatto inviato da Didit, con chiavi ordinate, inclusi `event_id` e `timestamp`. Analizzalo con un parser JSON; vedi [Payload shape](https://docs.didit.me/it/integration/webhooks#struttura-del-payload). Per una chiave con ambito limitato senza `media: read`, gli URL dei file multimediali al suo interno sono `null`; senza `sessions: write`, i token di sessione e i link di verifica ospitati sono `null`. Un corpo modificato in questo modo non corrisponde più alle sue firme. Didit non registra il corpo della risposta restituito dal tuo endpoint." }, "created_at": { "type": "string", "format": "date-time", "description": "Data e ora di creazione della consegna." } } }, "SessionEvent": { "type": "object", "description": "Una voce della cronologia degli eventi di una sessione di verifica.", "required": [ "uuid", "event_type", "created_at", "component", "feature_step", "step", "details", "ip_address", "user_agent", "device_info", "file_url", "sent_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificatore dell'evento." }, "event_type": { "type": "string", "enum": [ "SESSION_CREATED", "SESSION_COMPLETED", "SESSION_STATUS_CHANGED", "LINK_OPENED", "FORM_SUBMITTED", "BUTTON_CLICKED", "FILE_UPLOADED", "ATTEMPT_FAILED", "FEATURE_STEP_CHANGED", "STEP_RENDERED", "NOTE_ADDED", "MANUAL_REVIEW_STARTED", "WORKFLOW_BRANCH_EVALUATED", "WORKFLOW_STATUS_NODE_REACHED", "LOG" ], "description": "Cosa è successo. Segnalato dal dispositivo durante il flusso ospitato o l'SDK: `LINK_OPENED`, `STEP_RENDERED`, `BUTTON_CLICKED`, `FORM_SUBMITTED`, `FILE_UPLOADED`, `ATTEMPT_FAILED` e `LOG` (debug). Registrato dal server: `SESSION_CREATED`, `SESSION_STATUS_CHANGED` (`details.old_status`, `details.current_status`), `FEATURE_STEP_CHANGED` (`details.old_feature_step`, `details.current_feature_step`), `WORKFLOW_BRANCH_EVALUATED` e `WORKFLOW_STATUS_NODE_REACHED` (la traccia di routing del workflow). `SESSION_COMPLETED`, `NOTE_ADDED` e `MANUAL_REVIEW_STARTED` possono apparire sulle sessioni meno recenti." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando Didit ha archiviato l'evento. Gli eventi vengono archiviati in modo asincrono, pochi secondi dopo `sent_at`." }, "component": { "type": "string", "nullable": true, "description": "Componente UI che ha segnalato l'evento (solo eventi del dispositivo)." }, "feature_step": { "type": "string", "nullable": true, "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "DOCUMENT_AI", "GEOLOCATION", null ], "description": "Funzionalità di verifica in cui si trovava la sessione quando si è verificato l'evento." }, "step": { "type": "string", "nullable": true, "description": "Schermata all'interno della funzionalità, ad esempio `DOCUMENT_CAPTURE_FRONT` o `FACE_PASSIVE_LIVENESS`." }, "details": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Dati specifici dell'evento. Le chiavi dipendono da `event_type`." }, "ip_address": { "type": "string", "nullable": true, "description": "Indirizzo IP da cui il dispositivo ha segnalato l'evento. `null` per gli eventi registrati dal server." }, "user_agent": { "type": "string", "nullable": true, "description": "User agent del dispositivo. `null` per gli eventi registrati dal server." }, "device_info": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Dettagli del dispositivo segnalati dall'SDK o dal browser." }, "file_url": { "type": "string", "format": "uri", "nullable": true, "description": "Link pre-firmato di breve durata a un file allegato all'evento (ad esempio un'immagine acquisita). `null` quando non ce n'è alcuno, e sempre `null` per una chiave API con ambito limitato senza `media: read`." }, "sent_at": { "type": "integer", "format": "int64", "description": "Data e ora in cui si è verificato l'evento, come timestamp Unix in millisecondi. I risultati sono ordinati in base a questo valore." } } }, "AMLDatasetSourceFreshness": { "type": "object", "description": "Grado di aggiornamento di una famiglia di dataset AML.", "required": [ "last_updated_at", "oldest_updated_at", "dataset_count", "dated_dataset_count" ], "properties": { "last_updated_at": { "type": "string", "format": "date-time", "description": "Aggiornamento più recente di qualsiasi set di dati della famiglia." }, "oldest_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Limite di obsolescenza: ogni dataset nella famiglia è aggiornato almeno a questa data. `null` quando almeno un dataset nella famiglia non ha riportato alcuna data di aggiornamento, poiché in tal caso il limite è sconosciuto." }, "dataset_count": { "type": "integer", "description": "Numero di dataset nella famiglia." }, "dated_dataset_count": { "type": "integer", "description": "Numero di quei dataset che hanno segnalato una data di aggiornamento." } } }, "AMLDatasetFreshness": { "type": "object", "description": "Livello di aggiornamento dei set di dati AML al momento dell'esecuzione dello screening. Le date non vengono mai stimate.", "required": [ "captured_at", "provider", "catalog_version", "sources" ], "properties": { "captured_at": { "type": "string", "format": "date-time", "description": "Quando Didit ha letto il catalogo del dataset da cui proviene questa informazione sulla freschezza." }, "provider": { "type": "string", "description": "Identificatore opaco della fonte di dati AML. Trattalo come una stringa opaca; non eseguire diramazioni su di esso.", "example": "aml_data_source" }, "catalog_version": { "type": "string", "nullable": true, "description": "Identificatore di versione del catalogo dei set di dati, quando la fonte ne segnala uno." }, "sources": { "type": "object", "description": "Grado di aggiornamento per famiglia di dataset. Una famiglia i cui dataset non hanno riportato alcuna data di aggiornamento è assente anziché compilata con `null`.", "properties": { "sanctions": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" }, "pep": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" }, "warnings": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" }, "adverse_media": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" } } } } }, "AMLScreeningRun": { "type": "object", "description": "Un nuovo screening completato nell'ambito del monitoraggio AML continuo di un controllo AML.", "required": [ "uuid", "run_id", "completed_at", "started_at", "outcome", "trigger", "provider", "status", "score", "total_hits", "new_hits", "entities_screened", "dataset_freshness" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificatore di questa esecuzione di screening." }, "run_id": { "type": "string", "format": "uuid", "description": "L'esecuzione di monitoraggio a cui appartiene questo screening. Tutte le verifiche sottoposte a screening nella stessa esecuzione la condividono." }, "completed_at": { "type": "string", "format": "date-time", "description": "Quando è terminato il nuovo screening di questo soggetto. I risultati sono ordinati in base ad esso, dal più recente." }, "started_at": { "type": "string", "format": "date-time", "description": "Quando è iniziato il lotto di monitoraggio a cui appartiene questo nuovo screening." }, "outcome": { "type": "string", "enum": [ "NO_CHANGE", "CHANGED", "FAILED" ], "description": "`NO_CHANGE`: completato e il risultato non è cambiato. `CHANGED`: completato e il punteggio, lo stato, il conteggio dei riscontri o i riscontri sono cambiati. `FAILED`: nessuna risposta utilizzabile per questo soggetto, quindi il controllo è stato lasciato invariato." }, "trigger": { "type": "string", "enum": [ "ONGOING_MONITORING" ], "description": "Cosa ha avviato lo screening. Attualmente sempre `ONGOING_MONITORING`." }, "provider": { "type": "string", "description": "Identificatore opaco della fonte di dati AML che ha risposto. Trattalo come una stringa opaca; non eseguire diramazioni su di esso.", "example": "aml_data_source" }, "status": { "type": "string", "nullable": true, "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested", null ], "description": "Stato del controllo AML in cui questa esecuzione ha lasciato il controllo." }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "Punteggio AML risultante al termine di questa esecuzione del controllo." }, "total_hits": { "type": "integer", "nullable": true, "description": "Numero di corrispondenze che questa esecuzione ha lasciato nel controllo." }, "new_hits": { "type": "integer", "nullable": true, "description": "Numero di corrispondenze trovate da questa esecuzione che il controllo non presentava in precedenza. `0` quando non è stato trovato nulla di nuovo; `null` quando l'esecuzione non è riuscita o è stata registrata prima che questo conteggio esistesse." }, "entities_screened": { "type": "integer", "minimum": 0, "maximum": 1, "description": "Numero di entità sottoposte a screening da questa esecuzione per la verifica: `1` quando il soggetto è stato sottoposto a screening, `0` quando l'esecuzione non è riuscita." }, "dataset_freshness": { "allOf": [ { "$ref": "#/components/schemas/AMLDatasetFreshness" } ], "nullable": true, "description": "Attualità del set di dati alla base di questa esecuzione, oppure `null` quando non erano disponibili date." } } }, "KYBKeyPeopleParty": { "type": "object", "description": "Una parte relativa alle persone chiave di una sessione di Verifica aziendale (KYB), con la relativa verifica figlia. La stessa parte compare in `key_people_checks[].submitted.parties[]` della decisione sulla sessione aziendale.", "required": [ "uuid", "entity_type", "source", "name", "is_active", "is_skipped", "requires_verification", "roles", "kyc_session_deleted", "kyb_sub_session_deleted" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Identificativo della parte." }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "Indica se la parte è una persona fisica o un'azienda." }, "source": { "type": "string", "enum": [ "REGISTRY", "USER" ], "description": "`REGISTRY`: ricavato dal registro delle imprese. `USER`: inserito nella schermata Persone chiave." }, "name": { "type": "string", "description": "Nome visualizzato della parte." }, "first_name": { "type": "string", "nullable": true, "description": "Nome (persone)." }, "last_name": { "type": "string", "nullable": true, "description": "Cognome (persone fisiche)." }, "company_name": { "type": "string", "nullable": true, "description": "Ragione sociale (parti aziendali)." }, "registration_number": { "type": "string", "nullable": true, "description": "Numero di registrazione dell'azienda (parti aziendali)." }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Email a cui viene inviato il link di verifica." }, "nationality": { "type": "string", "nullable": true, "description": "Nazionalità per le persone fisiche, paese di costituzione per le aziende." }, "phone_number": { "type": "string", "nullable": true, "description": "Numero di telefono raccolto per la parte." }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "Data di nascita (persone)." }, "position": { "type": "string", "nullable": true, "description": "Titolo professionale in formato testo libero (persone)." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Campi personalizzati definiti dal workflow raccolti per la parte, indicizzati per chiave del campo." }, "is_active": { "type": "boolean", "description": "Indica se la parte è attiva." }, "is_skipped": { "type": "boolean", "description": "Indica se la parte è esente dalla verifica. La rigenerazione cancella questa impostazione." }, "requires_verification": { "type": "boolean", "description": "Indica se il ruolo e le regole sull'assetto proprietario richiedono una verifica per questa parte." }, "roles": { "type": "array", "description": "Ruoli ricoperti dalla parte nell'azienda.", "items": { "type": "object", "required": [ "role", "ownership_percent", "voting_percent" ], "properties": { "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "Codice del ruolo." }, "ownership_percent": { "type": "number", "nullable": true, "description": "Percentuale dell'assetto proprietario per questo ruolo, quando nota." }, "voting_percent": { "type": "number", "nullable": true, "description": "Percentuale dei diritti di voto per questo ruolo, se nota." } } } }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessione KYC individuale figlia (persone fisiche)." }, "kyc_session_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User", null ], "description": "Stato della sessione KYC figlia. Una sessione eliminata mantiene lo stato che aveva al momento dell'eliminazione." }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "Link ospitato della sessione KYC secondaria. `null` quando non è presente alcuna sessione o è stata eliminata, e per una chiave API con ambito limitato senza `sessions: write`." }, "kyc_session_deleted": { "type": "boolean", "description": "La sessione KYC figlia è stata eliminata, pertanto non potrà mai concludersi." }, "kyb_sub_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Sessione KYB figlia (parti aziendali)." }, "kyb_sub_session_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User", null ], "description": "Stato della sessione KYB figlia." }, "kyb_sub_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "Link ospitato della sessione KYB secondaria, con le stesse regole per `null` di `kyc_session_url`." }, "kyb_sub_session_deleted": { "type": "boolean", "description": "Controparte a livello di azienda di `kyc_session_deleted`." }, "verification_workflow_type": { "type": "string", "nullable": true, "enum": [ "kyc", "kyb", "adaptive_age_verification", "biometric_authentication", "address_verification", "questionnaire_verification", "email_verification", "phone_verification", null ], "description": "Tipo di workflow eseguito dalla sessione figlia." }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Workflow eseguito dalla sessione figlia." }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "Etichetta di quel workflow." }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "Funzionalità del workflow della sessione figlia con il relativo stato attuale.", "items": { "type": "object", "required": [ "feature", "status" ], "properties": { "feature": { "type": "string", "description": "Codice della funzionalità, ad esempio `ID_VERIFICATION` o `LIVENESS`." }, "status": { "type": "string", "description": "Stato della funzionalità, `Not Finished` fino a quando non viene eseguita." } } } }, "didit_internal_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Identificatore Didit della persona verificata, una volta nota." } } }, "TravelRuleDelivery": { "type": "object", "description": "Lo stato dell'ultimo messaggio dovuto dal trasferimento alla controparte. Didit contatta la controparte dopo la restituzione della richiesta che ha creato o modificato il trasferimento, quindi questo oggetto indica se tale messaggio è andato a buon fine: in coda, in fase di invio, in attesa di un nuovo tentativo dopo un errore, consegnato o non riuscito. In caso di errore da cui la rete può ancora riprendersi (nessuna risposta in tempo, connessione non riuscita, HTTP `408`, `429` o `5xx`), viene effettuato un nuovo tentativo dopo 30 secondi, 2 minuti, 10 minuti, 30 minuti e 1 ora. Quando un primo messaggio (`kind: SEND`) fallisce definitivamente, perché la rete lo ha rifiutato o anche il sesto tentativo non è riuscito, il trasferimento passa a `COUNTERPARTY_VASP_NOT_REACHABLE` con `last_error` nella sua `timeline`; qualsiasi altro messaggio che fallisce definitivamente viene annotato nella `timeline`. Lo `status` del trasferimento rimane l'unica fonte di verità per lo scambio stesso.", "required": [ "kind", "status", "rail", "attempts", "last_error", "next_attempt_at", "delivered_at" ], "properties": { "kind": { "type": "string", "enum": [ "SEND", "ANSWER", "TXID", "CANCEL", "POLL" ], "description": "Cosa trasporta il messaggio. `SEND`: il primo messaggio del trasferimento verso la controparte (in uscita; il canale viene scelto al momento dell'invio). `ANSWER`: la tua accettazione o rifiuto, dovuta alla rete che ha effettuato la richiesta (in entrata). `TXID`: l'hash della transazione on-chain, dopo aver completato il trasferimento. `CANCEL`: l'annullamento, dopo averlo cancellato. `POLL`: una richiesta di stato verso una rete che la supporta, ripetuta ogni 5 minuti mentre il trasferimento è in attesa della controparte." }, "status": { "type": "string", "enum": [ "QUEUED", "SENDING", "RETRYING", "DELIVERED", "FAILED" ], "description": "`QUEUED`: in attesa di invio. `SENDING`: tentativo in corso. `RETRYING`: un tentativo non è riuscito e il prossimo verrà eseguito alle `next_attempt_at`. `DELIVERED`: l'altra parte ha ricevuto il messaggio. `FAILED`: l'altra parte lo ha rifiutato o l'ultimo tentativo non è riuscito." }, "rail": { "type": "string", "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "" ], "description": "Il canale (rail) che trasporta il messaggio. Vuoto finché Didit non ne sceglie uno per un primo messaggio." }, "attempts": { "type": "integer", "minimum": 0, "description": "Tentativi effettuati finora per questo messaggio. Per un messaggio che non è un polling di stato vengono effettuati al massimo 6 tentativi." }, "last_error": { "type": "string", "description": "Il tipo di errore riscontrato nell'ultimo tentativo, `\"\"` se non ce ne sono stati: ad esempio `email undeliverable`, `trp identity endpoint unreachable` o `trp transfer inquiry delivery failed`. Non contiene mai la risposta della controparte stessa, che rimane nella `timeline` del trasferimento.\nQuando GTR risponde con un errore, vengono inclusi il codice di stato e il messaggio restituiti. I corpi della risposta non vengono mai inclusi.", "example": "email undeliverable" }, "next_attempt_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando verrà eseguito il prossimo tentativo mentre il messaggio è in stato `QUEUED` o `RETRYING`." }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando l'altra parte ha preso in carico il messaggio." } } }, "TravelRuleDiscoveryStep": { "type": "object", "description": "Un passaggio del rilevamento della controparte eseguito da Didit per un trasferimento in uscita, nell'ordine in cui è stato eseguito. Il primo passaggio che identifica un VASP con un percorso conclude la catena.", "properties": { "step": { "type": "string", "enum": [ "internal_address_book", "wallet_attribution", "network_lookup", "customer_hint", "end_user" ], "description": "`internal_address_book`: un altro cliente Didit che ha dimostrato il controllo del wallet di destinazione. `wallet_attribution`: l'attribuzione di analisi blockchain del wallet. `network_lookup`: una rete in grado di indicare quale VASP detiene l'indirizzo. `customer_hint`: il nome del VASP, LEI o la giurisdizione che hai inviato in `beneficiary_data`. `end_user`: la controparte scelta dall'utente finale (o da te), oppure la richiesta di sceglierne una." }, "outcome": { "type": "string", "enum": [ "match", "miss", "skipped" ], "description": "`match`: il passaggio ha indicato una controparte. `miss`: è stato eseguito e non ne ha trovata nessuna. `skipped`: non è stato possibile eseguirlo e `reason` ne indica il motivo." }, "reason": { "type": "string", "description": "Motivo leggibile dalla macchina, `\"\"` in caso di corrispondenza: `no_proven_internal_wallet`, `attribution_disabled`, `already_attributed`, `no_attributed_entity`, `directory_match_no_route`, `gtr_address_lookup_runs_on_dispatch`, `no_membership`, `network_switched_off`, `no_network_address_lookup`, `no_directory_match`, `awaiting_end_user` o `picked_member_without_proven_wallet`." }, "vasp": { "type": "string", "format": "uuid", "nullable": true, "description": "Il VASP della directory indicato dal passaggio, qualora ne abbia indicato uno." }, "rail": { "type": "string", "nullable": true, "description": "Il canale (rail) che raggiunge tale controparte, quando il passaggio ne ha trovato uno." }, "at": { "type": "string", "format": "date-time" } } }, "TravelRuleNextAction": { "type": "object", "description": "Un elemento che consente di far progredire un trasferimento bloccato nello stato `COUNTERPARTY_VASP_NOT_FOUND` o `COUNTERPARTY_VASP_NOT_REACHABLE`. Consulta [Perché un trasferimento è bloccato](/it/transaction-monitoring/travel-rule#perché-un-trasferimento-è-bloccato).", "properties": { "action": { "type": "string", "enum": [ "select_counterparty_vasp", "declare_self_hosted", "add_vasp_hint", "update_compliance_email", "resend" ], "description": "`select_counterparty_vasp`: l'utente finale seleziona il VASP di destinazione nel widget di titolarità del wallet, oppure invii una richiesta PATCH con `action=beneficiary_vasp`. `declare_self_hosted`: l'utente finale dichiara che il wallet è in autocustodia nel widget. `add_vasp_hint`: indica a Didit chi è la controparte specificando nome del VASP, LEI o Travel Address (ad esempio un `travel_address` nella voce della rubrica del wallet di destinazione), quindi invia nuovamente. `update_compliance_email` e `resend` sono valori di `action` per `PATCH /v3/transactions/{transaction_id}/travel-rule/`: fornisci nuovamente l'email di compliance della controparte ed esegui nuovamente l'instradamento." }, "url": { "type": "string", "format": "uri", "description": "Il link al widget di verifica della proprietà del wallet, su `select_counterparty_vasp` e `declare_self_hosted` mentre il trasferimento ha una sessione widget aperta." } }, "required": [ "action" ] }, "TransactionTravelRule": { "type": "object", "description": "Il trasferimento Travel Rule di una transazione, come restituito da `GET /v3/transactions/{transaction_id}/`, dal `201` di `POST /v3/transactions/` e da ciascuna riga di `GET /v3/transactions/`. `direction`, `rail`, `counterparty_vasp`, `delivery`, `discovery`, `reason` e `next_actions` hanno la stessa struttura di `PATCH /v3/transactions/{transaction_id}/travel-rule/`, quindi una singola lettura di una transazione indica perché il suo trasferimento è bloccato e cosa consente di farlo avanzare.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "protocol": { "type": "string", "nullable": true }, "required": { "type": "boolean" }, "obligations_count": { "type": "integer" }, "originator_data": { "type": "object", "description": "Soggetto ordinante. Per un trasferimento in entrata, i valori della controparte sono oscurati fino alla conferma dell'assetto proprietario." }, "beneficiary_data": { "type": "object", "description": "Parte beneficiaria. Per un trasferimento in entrata i valori della controparte sono mascherati fino a quando non viene confermato l'assetto proprietario." }, "name_match": { "type": "object", "nullable": true, "description": "Il confronto dei nomi che ha determinato il trasferimento (punteggio e livello di rigore). Null fino all'esecuzione. I nomi confrontati vengono oscurati insieme alle parti." }, "data_match": { "$ref": "#/components/schemas/TravelRuleDataMatch" }, "mismatched_fields": { "type": "array", "items": { "type": "string" }, "description": "Scorciatoia per `data_match.mismatched_fields`. Vuoto quando non ci sono differenze." }, "data_unmasked": { "$ref": "#/components/schemas/TravelRuleDataUnmasked" }, "data_masked": { "type": "boolean", "description": "True mentre i dati personali della controparte sono mascherati in questa risposta." }, "metadata": { "type": "object" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "Quale lato dello scambio rappresenta questo trasferimento." }, "rail": { "type": "string", "nullable": true, "description": "Il canale (rail) utilizzato per il trasferimento: `INTERNAL`, `TRP`, `GTR`, `TRUST`, `VERIFYVASP`, `SYGNA` o `EMAIL` (`TEST_VASP` su un'applicazione sandbox, quando il Didit Test VASP ha risposto), oppure `null` finché non viene scelto un canale." }, "counterparty_vasp": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "lei": { "type": "string" }, "dd_score": { "type": "integer", "description": "Punteggio di due diligence da 0 a 100, dove un valore più alto è migliore. Stessa scala utilizzata nella directory dei VASP." }, "dd_score_breakdown": { "type": "object", "description": "Contributi per componente a dd_score, un oggetto per componente come nella directory VASP (giurisdizione, verifica, protocollo, lei, cronologia, elementi essenziali, reattività), ciascuno con {points, max, reason, detail}. {} finché la controparte non è stata valutata.", "additionalProperties": { "type": "object", "properties": { "points": { "type": "number", "description": "Punti assegnati per questo componente." }, "max": { "type": "integer", "description": "Punti massimi che questo componente può assegnare." }, "reason": { "type": "string", "description": "Codice leggibile dalla macchina dell'esito del componente." }, "detail": { "type": "string", "description": "Motivo leggibile dall'utente per i punti assegnati." } } } }, "dd_assessed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultima esecuzione della valutazione di adeguata verifica. Null finché la controparte non è stata valutata." } }, "description": "La voce di directory della controparte, oppure `null` se il trasferimento non ne collega alcuna." }, "delivery": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TravelRuleDelivery" } ], "description": "Il messaggio più recente che il trasferimento deve a un'altra parte. `null` quando non ne ha dovuti, ad esempio al di sotto di `threshold_amount` o per un wallet in autocustodia dichiarato." }, "discovery": { "type": "array", "description": "Modalità con cui Didit ha cercato la controparte, una voce per ogni passaggio eseguito. Vuoto se non è stata eseguita alcuna ricerca, ad esempio per un trasferimento in entrata.", "items": { "$ref": "#/components/schemas/TravelRuleDiscoveryStep" } }, "reason": { "type": "string", "description": "Il motivo per cui un trasferimento `COUNTERPARTY_VASP_NOT_FOUND` o `COUNTERPARTY_VASP_NOT_REACHABLE` è bloccato; `\"\"` per qualsiasi altro stato. Una consegna non riuscita lo determina per prima, solo su `COUNTERPARTY_VASP_NOT_REACHABLE`: `email_undeliverable` (il provider di posta ha rifiutato l'email di compliance e non è rimasto alcun indirizzo da provare: quando è stata inviata, in un promemoria o come bounce permanente segnalato successivamente) o `delivery_failed` (il canale che effettuava la consegna è fallito definitivamente: un canale di rete ha rifiutato il messaggio o ha esaurito i tentativi, un host di identità `TRP` non ha risposto o l'host `TRP` della controparte non ha accettato la richiesta). Altrimenti lo determina la traccia di `discovery`: `awaiting_end_user` (nessun passaggio ha indicato una controparte raggiungibile da Didit), `directory_match_no_route` (un passaggio ha indicato un VASP della directory privo di rotta), `picked_member_without_proven_wallet` (l'utente finale ha scelto un cliente Didit che non ha dimostrato il controllo del wallet) o `no_directory_match` quando la traccia non fornisce altri motivi. Un nuovo invio fa avanzare il trasferimento, quindi il motivo viene azzerato. Consulta [Perché un trasferimento è bloccato](/it/transaction-monitoring/travel-rule#perché-un-trasferimento-è-bloccato)." }, "next_actions": { "type": "array", "description": "Cosa fa procedere il trasferimento; `[]` per qualsiasi stato tranne `COUNTERPARTY_VASP_NOT_FOUND` o `COUNTERPARTY_VASP_NOT_REACHABLE`. `email_undeliverable` propone `update_compliance_email`, poi `resend`. `delivery_failed` propone `resend`. Un motivo di discovery propone `select_counterparty_vasp`, `declare_self_hosted`, `add_vasp_hint` e `resend`.", "items": { "$ref": "#/components/schemas/TravelRuleNextAction" } }, "chain_details": { "$ref": "#/components/schemas/TravelRuleChainDetails" } } }, "NetworkListCounts": { "type": "object", "description": "Conteggi delle reti per le viste e le opzioni di filtro dell'elenco, con ogni rete conteggiata una volta sola. Restituito solo quando `summary` non è `false`. `scopes` conta ogni rete visibile all'applicazione. `views` conta le reti visibili all'interno dello `scope` selezionato. `facets` conta le reti nello `scope` e nella vista `status` selezionati (le reti ignorate sono escluse a meno che `status` non le includa). Gli altri filtri dell'elenco non modificano questi conteggi.", "properties": { "scopes": { "type": "object", "description": "Reti visibili per prodotto.", "properties": { "all": { "type": "integer" }, "identity": { "type": "integer", "description": "Ogni altra rete." }, "transactions": { "type": "integer", "description": "Reti i cui membri sono tutti parti della transazione." } } }, "views": { "type": "object", "description": "Reti visibili all'interno dello `scope` selezionato, per stato, più due visualizzazioni salvate.", "properties": { "all": { "type": "integer" }, "active": { "type": "integer" }, "in_review": { "type": "integer" }, "resolved": { "type": "integer" }, "dismissed": { "type": "integer" }, "mine": { "type": "integer", "description": "Reti assegnate al membro della console che effettua la chiamata. Sempre 0 per una chiave API." }, "high_risk": { "type": "integer", "description": "Reti con un punteggio di rischio pari o superiore a 80 che non sono state ignorate." } } }, "facets": { "type": "object", "description": "Conteggi per ciascuna opzione di filtro, all'interno dello `scope` e della vista di stato selezionati.", "properties": { "total": { "type": "integer", "description": "Reti nello `scope` e nella vista di stato selezionati." }, "last_activity_days": { "type": "object", "description": "Reti con attività negli ultimi 7, 30 e 90 giorni, indicizzate per numero di giorni.", "properties": { "7": { "type": "integer" }, "30": { "type": "integer" }, "90": { "type": "integer" } } }, "risk_min": { "type": "object", "description": "Reti con un punteggio di rischio pari ad almeno 50 e ad almeno 80, indicizzate per soglia.", "properties": { "50": { "type": "integer" }, "80": { "type": "integer" } } }, "signal_types": { "type": "object", "description": "Reti con almeno un segnale di ciascun tipo.", "properties": { "ip_address": { "type": "integer" }, "device": { "type": "integer" }, "face": { "type": "integer" }, "document_number": { "type": "integer" }, "phone": { "type": "integer" }, "email": { "type": "integer" }, "address": { "type": "integer" } } }, "priority": { "type": "object", "description": "Reti per priorità. `none` conta le reti senza una priorità.", "properties": { "low": { "type": "integer" }, "medium": { "type": "integer" }, "high": { "type": "integer" }, "none": { "type": "integer" } } }, "assignee": { "type": "object", "description": "Reti per assegnatario.", "properties": { "me": { "type": "integer", "description": "Assegnato al membro della console che effettua la chiamata. Sempre 0 per una chiave API." }, "unassigned": { "type": "integer", "description": "Non assegnato a nessuno." }, "users": { "type": "array", "description": "Una voce per assegnatario, prima gli assegnatari con il maggior numero di reti.", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "full_name": { "type": "string", "description": "Il nome dell'assegnatario, o la sua email se non è impostato alcun nome." }, "email": { "type": "string" }, "count": { "type": "integer" } } } } } }, "has_case": { "type": "integer", "description": "Reti per cui questa applicazione ha aperto un caso." }, "min_size": { "type": "object", "description": "Reti con almeno 10 membri, indicizzate per dimensione minima.", "properties": { "10": { "type": "integer" } } } } } } }, "NetworkTag": { "type": "object", "description": "Uno dei tag della tua applicazione sulla rete.", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "L'UUID del tag, lo stesso valore passato come `tag_uuid`." }, "name": { "type": "string" }, "color": { "type": "string", "description": "Colore esadecimale, ad esempio `#6366F1`." }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "`didit` per un tag predefinito di Didit, `custom` per un tag creato dal tuo team." }, "added_by": { "type": "string", "nullable": true, "description": "Email del membro della console che ha aggiunto il tag. Null se aggiunto tramite chiave API." }, "added_at": { "type": "string", "format": "date-time" } } }, "NetworkOutcomes": { "type": "object", "description": "Lo stato delle persone e delle aziende della rete. Ciascun membro visibile viene conteggiato una sola volta, in base allo stato della verifica più recente che ha raggiunto una decisione. Le parti della transazione non vengono conteggiate.", "properties": { "approved": { "type": "integer", "description": "Membri la cui verifica decisa più recente è stata approvata." }, "declined": { "type": "integer", "description": "Membri la cui verifica decisa più recente è stata rifiutata." }, "in_review": { "type": "integer", "description": "Membri la cui verifica decisa più recente è in revisione." }, "total": { "type": "integer", "description": "Membri con almeno una verifica, decisa o meno. Un membro le cui verifiche sono tutte senza decisione (non avviata, in corso, scaduta o abbandonata) viene conteggiato qui e in nessun'altra chiave." } } }, "NetworkPatternScore": { "type": "object", "description": "Grado di somiglianza di un tipo di dati dei membri all'interno dell'intera rete. Un pattern non costituisce un segnale: nessun valore condiviso collega i membri.", "properties": { "type": { "type": "string", "enum": [ "background" ], "description": "`background`: la somiglianza media dello sfondo dei selfie di ogni coppia di membri, con la persona mascherata. Legge il selfie più recente di ciascuna persona, al massimo i 50 più recenti, ed esclude le sessioni di verifica dell'età. Copre l'intera rete, non solo i membri delle tue applicazioni." }, "score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1, "description": "Da 0 a 1, arrotondato a 4 decimali. Null quando `reason` è impostato." }, "members": { "type": "integer", "nullable": true, "description": "Di quanti membri sono stati confrontati i selfie dal punteggio. Un selfie illeggibile o con troppo poco sfondo non viene confrontato. Null durante `computing`; 0 o 1 con `not_enough_selfies`." }, "reason": { "type": "string", "enum": [ "computing", "not_enough_selfies" ], "nullable": true, "description": "Il motivo per cui non è presente un punteggio. `computing`: il punteggio per i membri attuali è in fase di calcolo; interroga nuovamente la rete più tardi. `not_enough_selfies`: meno di due membri hanno un selfie utilizzabile. Null quando è presente un punteggio." }, "computed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il punteggio è stato calcolato. Null mentre è in stato `computing`." } } }, "NetworkDetailResponse": { "description": "I dettagli della rete, oltre alla modalità di condivisione dell'organizzazione, all'eventuale applicazione di segnali tra organizzazioni, ai tag della tua applicazione sulla rete, agli esiti dei membri e ai punteggi dei pattern.", "allOf": [ { "$ref": "#/components/schemas/NetworkDetail" }, { "type": "object", "properties": { "sharing_mode": { "type": "string", "enum": [ "off", "private", "global" ], "description": "La modalità di condivisione tra organizzazioni dell'organizzazione. Solo `global` confronta le reti tra organizzazioni; `private` e `off` le limitano alla cronologia interna dell'organizzazione.", "example": "global" }, "cross_org_available": { "type": "boolean", "description": "Indica se i segnali tra organizzazioni si applicano a questa organizzazione. Richiedono sia il piano Enterprise sia la modalità di condivisione `global`.", "example": true }, "cross_org_unavailable_reason": { "type": "string", "enum": [ "plan", "sharing_mode" ], "nullable": true, "description": "Il motivo per cui i segnali inter-organizzazione non sono applicabili, verificati in questo ordine. `plan`: il piano dell'organizzazione non include la rete antifrode inter-organizzazione (richiede il piano Enterprise), indipendentemente dalla modalità di condivisione. `sharing_mode`: il piano la include, ma la modalità di condivisione è `private` o `off`. Null quando `cross_org_available` è `true`.", "example": null }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTag" }, "description": "I tag della tua applicazione sulla rete, dal meno recente al più recente. Ciascuna applicazione visualizza solo i propri tag. `fraud_tags` è separato e invariato: i tag associati ai membri della rete." }, "outcomes": { "$ref": "#/components/schemas/NetworkOutcomes" }, "patterns": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkPatternScore" }, "description": "Punteggi dei pattern sull'intera rete. Attualmente un elemento, `background`." } } } ] }, "NetworkTagRequest": { "type": "object", "required": [ "tag_uuid" ], "properties": { "tag_uuid": { "type": "string", "format": "uuid", "description": "UUID di uno dei tag della tua applicazione." } }, "example": { "tag_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "NetworkTimeline": { "title": "Default timeline (no contract)", "type": "object", "description": "Senza `contract`: gli eventi della rete stessa, dal più vecchio al più recente, non impaginati.", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTimelineEvent" } } } }, "NetworkTimelinePage": { "title": "Typed timeline page (contract=2)", "type": "object", "description": "Con `contract=2`: una pagina di eventi tipizzati, i più recenti per primi.", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTypedTimelineEvent" } }, "next_cursor": { "type": "string", "nullable": true, "description": "Passalo come `cursor` per leggere la pagina successiva. Null nell'ultima pagina." } } }, "NetworkTypedTimelineEvent": { "type": "object", "description": "Un singolo evento tipizzato della timeline: i quattro campi predefiniti, più il relativo id, la data e ora in cui Didit lo ha memorizzato, l'account membro e il record a cui appartiene, e il blocco dei dettagli del rispettivo tipo di evento. Gli altri blocchi dei dettagli sono null.", "properties": { "id": { "type": "string", "description": "`:`, univoco all'interno della cronologia.", "example": "session:3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "event_type": { "type": "string", "enum": [ "network_detected", "signal_observed", "network_active", "network_in_review", "network_resolved", "network_dismissed", "verification_attempt", "transaction", "login", "rule_hit", "case_linked", "note_added" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "Quando è avvenuto." }, "ingested_at": { "type": "string", "format": "date-time", "description": "Quando Didit lo ha archiviato." }, "label": { "type": "string", "description": "Una breve etichetta in inglese, ad esempio `Verification attempt 2 of 3`." }, "metadata": { "type": "object", "description": "Per gli eventi della rete stessa, gli stessi metadati della timeline predefinita. Vuoto in caso contrario." }, "account": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineAccount" } ], "nullable": true, "description": "L'account del membro. Null per gli eventi propri della rete, `case_linked` e `note_added`." }, "source_ref": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineSourceRef" } ], "nullable": true, "description": "Il record di origine. Null per gli eventi propri della rete e per `note_added`." }, "verification_attempt": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineAttempt" } ], "nullable": true, "description": "Impostato sugli eventi `verification_attempt`." }, "transaction": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineTransaction" } ], "nullable": true, "description": "Impostato sugli eventi `transaction`." }, "login": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineLogin" } ], "nullable": true, "description": "Impostato sugli eventi `login`." }, "rule_hit": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineRuleHit" } ], "nullable": true, "description": "Impostato sugli eventi `rule_hit`." }, "case_linked": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineCaseLinked" } ], "nullable": true, "description": "Impostato sugli eventi `case_linked`." }, "note_added": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineNoteAdded" } ], "nullable": true, "description": "Impostato sugli eventi `note_added`. Non viene mai restituito a una chiave API." } } }, "NetworkTimelineAccount": { "type": "object", "description": "L'account del membro a cui appartiene l'evento.", "properties": { "node_id": { "type": "string", "description": "`:`, dove il tipo è `vendor_user`, `vendor_business` o `transaction_party`.", "example": "vendor_user:3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "node_type": { "type": "string", "enum": [ "account", "business_account", "transaction_party" ] }, "uuid": { "type": "string", "format": "uuid" }, "vendor_data": { "type": "string", "nullable": true }, "display_name": { "type": "string", "nullable": true }, "ownership": { "type": "string", "enum": [ "owned", "organization" ], "description": "`owned` quando il record appartiene all'applicazione che hai chiamato (per un membro della console, a un'applicazione a cui ha accesso). `organization` quando appartiene a un'altra applicazione della tua organizzazione." }, "route": { "$ref": "#/components/schemas/NetworkTimelineRoute" } } }, "NetworkTimelineSourceRef": { "type": "object", "description": "Il record da cui è stato letto l'evento.", "properties": { "kind": { "type": "string", "enum": [ "session", "business_session", "transaction", "monitoring_event", "case" ] }, "id": { "type": "string", "format": "uuid" }, "ownership": { "type": "string", "enum": [ "owned", "organization" ], "description": "`owned` quando il record appartiene all'applicazione che hai chiamato (per un membro della console, a un'applicazione a cui ha accesso). `organization` quando appartiene a un'altra applicazione della tua organizzazione." }, "route": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineRoute" } ], "description": "Assente per `monitoring_event` e `case`." } } }, "NetworkTimelineRoute": { "type": "object", "description": "Dove si apre il record: il suo tipo, il suo UUID e l'applicazione a cui appartiene.", "properties": { "kind": { "type": "string", "description": "`user`, `business` o `transaction_party` per un account; `session`, `business_session` o `transaction` per un record di origine." }, "id": { "type": "string", "format": "uuid" }, "application_id": { "type": "string", "format": "uuid" } } }, "NetworkTimelineAttempt": { "type": "object", "description": "Una singola sessione di verifica dell'account.", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "L'UUID della sessione, o l'UUID della sessione aziendale per un'azienda." }, "session_number": { "type": "integer", "nullable": true }, "attempt": { "type": "integer", "description": "La posizione di questa sessione tra le sessioni dell'account, in ordine di creazione." }, "attempt_count": { "type": "integer", "description": "Quante sessioni ha l'account." }, "status": { "type": "string", "description": "Lo stato della sessione, ad esempio `Approved` o `Declined`." }, "status_changed_at": { "type": "string", "format": "date-time", "nullable": true }, "decline_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTimelineDeclineReason" }, "description": "Solo per una sessione rifiutata: i relativi avvisi, dal più vecchio al più recente, una volta per avviso. Vuoto in caso contrario." } } }, "NetworkTimelineDeclineReason": { "type": "object", "properties": { "risk": { "type": "string", "description": "Il codice dell'avviso." }, "feature": { "type": "string", "description": "La funzionalità che ha generato l'avviso." }, "short_description": { "type": "string" } } }, "NetworkTimelineTransaction": { "type": "object", "description": "Una transazione a cui ha partecipato un account membro, con data corrispondente a quella della transazione.", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "transaction_number": { "type": "integer", "nullable": true }, "transaction_type": { "type": "string" }, "action_type": { "type": "string" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineAmount" } ], "nullable": true, "description": "Null quando la transazione non ha alcun importo." }, "status": { "type": "string" }, "decision_reason_code": { "type": "string", "nullable": true }, "decision_reason_label": { "type": "string", "nullable": true }, "party_role": { "type": "string", "description": "Il ruolo dell'account nella transazione: `APPLICANT`, `REMITTER`, `BENEFICIARY` o `COUNTERPARTY`." } } }, "NetworkTimelineAmount": { "type": "object", "properties": { "value": { "type": "string", "description": "Importo decimale sotto forma di stringa." }, "currency": { "type": "string" }, "direction": { "type": "string", "nullable": true } } }, "NetworkTimelineLogin": { "type": "object", "description": "Un evento di accesso che hai inviato per una persona tramite l'API degli eventi.", "properties": { "action": { "type": "string", "description": "`.`: `auth.login` o `security.login_succeeded` per un accesso, `auth.login_failed` o `security.login_failed` per un accesso non riuscito." }, "succeeded": { "type": "boolean" }, "status": { "type": "string", "description": "Lo stato dell'evento." }, "ip": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineIP" } ], "nullable": true, "description": "Null quando l'evento non ha alcun indirizzo IP." }, "device": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineDevice" } ], "nullable": true, "description": "Null quando l'evento non ha impronta digitale o contesto del dispositivo." }, "is_first_login": { "type": "boolean", "description": "Il primo accesso riuscito registrato per l'account." }, "is_new_device": { "type": "boolean", "description": "Un accesso riuscito da un dispositivo dal quale non era stato effettuato alcuno dei precedenti accessi riusciti dell'account. Mai true al primo accesso." } } }, "NetworkTimelineIP": { "type": "object", "properties": { "address": { "type": "string" }, "country_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "connection_type": { "type": "string", "nullable": true, "description": "L'etichetta del tipo di connessione per l'indirizzo, come testo libero." }, "is_vpn_or_tor": { "type": "boolean" }, "is_data_center": { "type": "boolean" } } }, "NetworkTimelineDevice": { "type": "object", "properties": { "fingerprint": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true, "description": "Un'etichetta leggibile del dispositivo creata a partire dal contesto del dispositivo dell'evento." } } }, "NetworkTimelineRuleHit": { "type": "object", "description": "Una regola attiva che ha trovato corrispondenza con una transazione o un evento di un membro. Le corrispondenze in modalità test non sono incluse.", "properties": { "rule_id": { "type": "string", "format": "uuid" }, "rule_title": { "type": "string" }, "rule_category": { "type": "string" }, "rule_source": { "type": "string" }, "severity": { "type": "string", "nullable": true }, "score_delta": { "type": "integer" }, "status_target": { "type": "string", "nullable": true }, "action_summary": { "type": "string", "nullable": true } } }, "NetworkTimelineCaseLinked": { "type": "object", "description": "Un caso aperto per la rete all'interno della tua organizzazione. `source_ref.ownership` indica se appartiene all'applicazione che hai chiamato.", "properties": { "case_id": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true }, "status": { "type": "string" }, "author_email": { "type": "string", "nullable": true }, "author_name": { "type": "string", "nullable": true } } }, "NetworkTimelineNoteAdded": { "type": "object", "description": "Una nota lasciata sulla rete. Il testo della nota non è incluso.", "properties": { "note_id": { "type": "string", "format": "uuid" }, "author_email": { "type": "string" } } }, "FeatureStatusOverride": { "type": "object", "description": "Un override dello stato di un controllo (funzionalità) eseguito con `PATCH /v3/session/{sessionId}/features/{nodeId}/update-status/`: cosa modifica, se è stato applicato o è ancora in attesa che la persona completi il flusso, chi lo ha richiesto e perché.", "required": [ "id", "node_id", "feature_type", "feature_model", "previous_status", "new_status", "state", "forced", "reason", "requested_by", "requested_at", "applied_at", "cancelled_at", "cancel_reason" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificatore dell'override. Passalo all'endpoint di annullamento.", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "node_id": { "type": "string", "description": "Il nodo del workflow indicato dalla richiesta (`default` per un passaggio privo di nodo).", "example": "feature_ocr_1" }, "feature_type": { "type": "string", "description": "Il `feature_type` passato dalla richiesta, oppure una stringa vuota se non ne è stato passato alcuno.", "example": "" }, "feature_model": { "type": "string", "description": "Il tipo di controllo che è stato ignorato manualmente, ad esempio `KYC`, `Face`, `AML` o `GeolocationCheck`.", "example": "KYC" }, "previous_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Lo stato del controllo al momento della richiesta dell'override.", "example": "In Review" }, "new_status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "Lo stato impostato dall'override.", "example": "Approved" }, "state": { "type": "string", "enum": [ "applied", "pending_until_flow_finishes", "cancelled" ], "description": "`applied`: il controllo ha il nuovo stato. `pending_until_flow_finishes`: l'override resta in attesa e viene applicato quando la persona completa il flusso. `cancelled`: è rimasto in attesa e non è mai stato applicato (vedi `cancel_reason`).", "example": "applied" }, "forced": { "type": "boolean", "description": "`true` quando l'override è stato applicato immediatamente mentre la persona si trovava ancora nel flusso.", "example": false }, "reason": { "type": "string", "nullable": true, "description": "Il `comment` inviato con la richiesta, oppure `null`.", "example": "Document manually verified by compliance." }, "requested_by": { "type": "object", "nullable": true, "description": "Chi ha richiesto l'override, o `null` quando non è noto.", "properties": { "email": { "type": "string", "format": "email", "nullable": true, "description": "Email dell'utente della console, oppure `null` per le chiavi API e il sistema.", "example": "reviewer@example.com" }, "name": { "type": "string", "nullable": true, "description": "Nome visualizzato del richiedente, oppure `null`.", "example": "Alex Reviewer" }, "type": { "type": "string", "enum": [ "CONSOLE_USER", "API_KEY", "SYSTEM" ], "description": "Chi ha effettuato la richiesta: un utente della console, una chiave API o Didit stessa.", "example": "CONSOLE_USER" } } }, "requested_at": { "type": "string", "format": "date-time", "description": "Quando è stato richiesto l'override.", "example": "2026-10-13T09:15:00Z" }, "applied_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora in cui il controllo ha assunto il nuovo stato, oppure `null` mentre è in attesa o una volta annullato.", "example": "2026-10-13T09:15:00Z" }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando un override in attesa è stato annullato, oppure `null`.", "example": null }, "cancel_reason": { "type": "string", "nullable": true, "enum": [ "cancelled_by_reviewer", "replaced", "check_changed", "session_closed", null ], "description": "Il motivo per cui un override in attesa non è mai stato applicato, oppure `null`. `cancelled_by_reviewer`: annullato con l'endpoint di annullamento. `replaced`: sostituito da un override più recente sullo stesso controllo. `check_changed`: la persona ha ripetuto il controllo prima di completare il flusso. `session_closed`: la sessione è uscita dal flusso prima che la persona lo completasse (abbandonata, scaduta o decisa a metà flusso).", "example": null } } }, "SandboxSimulateRequest": { "type": "object", "description": "Forza lo stato di una sessione sandbox. Ogni campo è facoltativo, ma è richiesto almeno uno tra `new_status`, `scenario` o `risk`.", "properties": { "new_status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Abandoned" ], "description": "Lo stato da impostare. Se lo ometti, assume come valore predefinito lo stato predefinito del caso di rischio (`risk`, o il primo rischio associato ai valori magici dello scenario), altrimenti lo stato predefinito dello scenario.", "example": "Declined" }, "comment": { "type": "string", "maxLength": 500, "description": "Nota aggiunta alla voce di attività registrata dal cambio di stato.", "example": "Testing the decline path" }, "scenario": { "type": "string", "maxLength": 100, "description": "Uno slug di scenario dal catalogo (`GET /v1/sandbox/scenarios/`). Fornisce lo stato predefinito e, senza `risk`, l'avviso veicolato dai suoi valori magici. Uno slug sconosciuto restituisce `400`.", "example": "decline_aml_hit" }, "risk": { "type": "string", "maxLength": 128, "description": "Un caso di rischio dal catalogo. Il suo avviso viene aggiunto alla sessione, con un tipo di log che segue `new_status`. Un valore sconosciuto restituisce `400`.", "example": "POSSIBLE_MATCH_FOUND" }, "node_id": { "type": "string", "maxLength": 128, "description": "Nodo del workflow a cui è associato l'avviso di rischio. Il valore predefinito è il nodo corrente della sessione.", "example": "feature_aml_1" }, "send_webhooks": { "type": "boolean", "default": true, "description": "`true` invia esattamente i webhook che un vero cambio di stato invia alle destinazioni dell'applicazione sandbox: `status.updated`, oltre agli eventi `user.status.updated` / `user.data.updated` (o `business.status.updated` / `business.data.updated`) causati dalla modifica, per le destinazioni a essi iscritte. `false` modifica lo stato senza registrare né inviare alcun webhook: il recupero dei webhook mancati non reinvia mai tale decisione, la console si aggiorna comunque in tempo reale e il successivo cambio di stato della sessione invia i webhook normalmente.", "example": true } } }, "SandboxSimulateResponse": { "type": "object", "required": [ "session_id", "previous_status", "status", "scenario", "risk", "send_webhooks" ], "properties": { "session_id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "previous_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "Lo stato della sessione prima della simulazione.", "example": "In Progress" }, "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Abandoned" ], "description": "Lo stato impostato dalla simulazione.", "example": "Declined" }, "scenario": { "type": "string", "nullable": true, "description": "Lo slug dello scenario che hai passato, oppure `null`.", "example": "decline_aml_hit" }, "risk": { "type": "string", "nullable": true, "description": "Il caso di rischio applicato (`risk`, o quello ricavato dallo scenario), oppure `null` se non ne è stato applicato alcuno.", "example": "POSSIBLE_MATCH_FOUND" }, "send_webhooks": { "type": "boolean", "description": "Il valore `send_webhooks` applicato dalla simulazione.", "example": false } } }, "CaseTeamSummary": { "type": "object", "nullable": true, "description": "Il team di revisione assegnatario del caso, oppure null se non è assegnato ad alcun team. L'instradamento lo imposta quando una regola di instradamento assegna il caso a uno dei suoi team. Modificalo o cancellalo con `PATCH .../cases/{case_uuid}/` (`team`).", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "CaseChecker": { "type": "object", "nullable": true, "description": "Il membro designato per approvare o rifiutare la risoluzione in sospeso. Impostato solo mentre una risoluzione a quattro occhi attende un verificatore designato. Null quando non c'è nulla in sospeso, mentre la risoluzione in sospeso attende nella coda dei verificatori e una volta che la risoluzione è approvata, rifiutata o restituita per una nuova revisione a seguito della modifica delle prove.", "properties": { "member_uuid": { "type": "string", "format": "uuid", "description": "L'uuid utente del membro: il valore che passi come `checker` quando risolvi il caso." }, "name": { "type": "string", "nullable": true, "description": "Il nome completo del membro, o null se non noto." }, "email": { "type": "string", "format": "email" } } }, "ServiceStatusFeed": { "type": "object", "description": "Stato pubblico dei servizi: lo stato di ciascun servizio Didit, lo stato complessivo e gli incidenti in corso o risolti negli ultimi 7 giorni.", "required": [ "status", "updated_at", "services", "incidents" ], "properties": { "status": { "type": "string", "enum": [ "operational", "degraded", "down" ], "description": "Lo stato peggiore tra tutti i servizi in questo momento, determinato esclusivamente dagli incidenti in corso.", "example": "degraded" }, "updated_at": { "type": "string", "format": "date-time", "description": "Quando Didit ha generato questa risposta (ISO 8601, UTC). Le risposte sono memorizzate nella cache per 30 secondi, quindi possono risalire a un massimo di 30 secondi prima.", "example": "2026-10-13T09:41:07.512345Z" }, "services": { "type": "array", "description": "Una voce per servizio, con tutti i servizi sempre elencati.", "items": { "$ref": "#/components/schemas/ServiceStatusService" } }, "incidents": { "type": "array", "description": "`started_at` più recente per primo. Ogni incidente in corso, più gli incidenti risolti negli ultimi 7 giorni (al massimo 50 incidenti risolti). Vuoto se non si è verificato nulla in quel periodo.", "items": { "$ref": "#/components/schemas/ServiceStatusIncident" } } } }, "ServiceStatusService": { "type": "object", "required": [ "key", "name", "status" ], "properties": { "key": { "type": "string", "enum": [ "service_id_verification", "service_liveness_face_match", "service_aml_screening", "service_kyb_registries", "service_database_validation", "service_phone_delivery", "service_email_delivery", "service_transaction_monitoring" ], "description": "Chiave di servizio stabile. Esegui il confronto usando questa chiave, mai il nome visualizzato. `service_id_verification`: Verifica dell'identità, `service_liveness_face_match`: Rilevamento della vitalità e confronto facciale, `service_aml_screening`: Screening AML, `service_kyb_registries`: Registri KYB, `service_database_validation`: Validazione su database, `service_phone_delivery`: Consegna della verifica telefonica, `service_email_delivery`: Consegna della verifica email, `service_transaction_monitoring`: Monitoraggio delle transazioni.", "example": "service_database_validation" }, "name": { "type": "string", "description": "Nome visualizzato in inglese del servizio.", "example": "Database validation" }, "status": { "type": "string", "enum": [ "operational", "degraded", "down" ], "description": "`operational` quando non ci sono incidenti in corso per il servizio, altrimenti lo stato peggiore tra i suoi incidenti in corso.", "example": "degraded" } } }, "ServiceStatusIncident": { "type": "object", "required": [ "id", "service", "service_name", "state", "status", "title", "body", "affected", "country_name", "started_at", "resolved_at", "duration_minutes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID dell'incidente.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "service": { "type": "string", "enum": [ "service_id_verification", "service_liveness_face_match", "service_aml_screening", "service_kyb_registries", "service_database_validation", "service_phone_delivery", "service_email_delivery", "service_transaction_monitoring" ], "description": "Chiave del servizio interessato (vedi `services[].key`).", "example": "service_database_validation" }, "service_name": { "type": "string", "description": "Nome visualizzato in inglese del servizio interessato.", "example": "Database validation" }, "state": { "type": "string", "enum": [ "degraded", "down" ], "description": "Impatto sul servizio. Un incidente risolto mantiene l'ultimo stato che aveva.", "example": "degraded" }, "status": { "type": "string", "enum": [ "ongoing", "resolved" ], "description": "`ongoing` fino al ripristino del servizio, poi `resolved`.", "example": "ongoing" }, "title": { "type": "string", "description": "Titolo in inglese. Per tradurlo, componi il tuo testo a partire da `service`, `state` e `country_name`.", "example": "Database validation is degraded in Brazil." }, "body": { "type": "string", "description": "Riga di dettaglio in inglese: da quando i controlli potrebbero essere lenti o fallire, oppure quando il servizio si è ripristinato.", "example": "Checks against Brazil (CPF) may be slow or fail since 08:55 UTC." }, "affected": { "type": "string", "description": "Paesi o registri interessati, ad esempio `Brazil (CPF)`. Vuoto quando l'incidente non è collegato a un paese o a un registro.", "example": "Brazil (CPF)" }, "country_name": { "type": "string", "description": "Paese interessato, in inglese. Vuoto quando l'incidente non è collegato a un paese.", "example": "Brazil" }, "started_at": { "type": "string", "format": "date-time", "description": "Quando è iniziato l'incidente (ISO 8601, UTC).", "example": "2026-10-13T08:55:00Z" }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando il servizio è stato ripristinato (ISO 8601, UTC). `null` finché l'incidente è in corso." }, "duration_minutes": { "type": "integer", "nullable": true, "description": "Minuti interi da `started_at` a `resolved_at`. `null` finché l'incidente è in corso." } } }, "TravelRuleJoinInvitation": { "type": "object", "description": "Cosa mostra la pagina di adesione prima che venga digitato qualsiasi testo.", "properties": { "email": { "type": "string", "format": "email", "description": "L'indirizzo a cui è stato inviato l'invito." }, "vasp_name": { "type": "string" }, "source": { "type": "string", "description": "Da dove proviene l'invito, ad esempio `pickup`." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "prefill": { "type": "object", "properties": { "vasp_id": { "type": "string", "format": "uuid", "nullable": true }, "legal_name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } } } } } }, "TravelRuleJoinRegisterRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Deve essere l'indirizzo a cui è stato inviato l'invito." }, "password": { "type": "string", "minLength": 8, "maxLength": 128 } } }, "TravelRuleJoinVerifyRequest": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "code": { "type": "string", "minLength": 6, "maxLength": 6, "description": "Il codice di 6 caratteri inviato via email dopo la registrazione." } } }, "TravelRuleJoinCredentials": { "type": "object", "description": "La nuova organizzazione gratuita e le credenziali con cui la sua applicazione chiama l'API.", "properties": { "organization": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } }, "application": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } }, "client_id": { "type": "string" }, "api_key": { "type": "string", "description": "Invia come intestazione `x-api-key` sugli endpoint del workspace." } } }, "TravelRuleWorkspaceClaimRequest": { "type": "object", "required": [ "vasp_id" ], "properties": { "vasp_id": { "type": "string", "format": "uuid", "description": "La voce della directory corrispondente a questo spazio di lavoro. Leggi gli ID da `GET /v3/travel-rule/vasps/`." } } }, "TravelRuleWorkspaceDomainConfirmRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6 } } }, "TravelRuleWorkspaceBillingRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "È accettato solo `true`: la fatturazione in uscita non può essere disattivata nuovamente tramite l'API." } } }, "TravelRuleWorkspaceDomainCodeResponse": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "unverified", "code_sent", "verified" ] }, "txt": { "$ref": "#/components/schemas/TravelRuleWorkspaceTxtRecord" } } }, "TravelRuleWorkspaceTxtRecord": { "type": "object", "description": "Il record TXT da pubblicare per la prova DNS. Vuoto finché non viene avviata una prova.", "properties": { "host": { "type": "string", "example": "didit-tr-verify.example.com" }, "value": { "type": "string" } } }, "TravelRuleWorkspace": { "type": "object", "description": "Il workspace gratuito di Travel Rule di un'applicazione che ha aderito al piano gratuito.", "properties": { "joined_free": { "type": "boolean" }, "work_email": { "type": "string", "format": "email" }, "joined_at": { "type": "string", "format": "date-time", "nullable": true }, "claim": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unclaimed", "pending_review", "claimed", "rejected" ] }, "proved_by_domain": { "type": "boolean" }, "claimed_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "review_note": { "type": "string" }, "vasp_id": { "type": "string", "format": "uuid", "nullable": true }, "vasp_name": { "type": "string" } } }, "prefill": { "type": "object", "description": "Valori del profilo ricavati dalla voce dell'elenco: `vasp_id`, `legal_name`, `lei`, `jurisdiction`, `compliance_email`, `domains`. Non viene scritto nulla finché non viene effettuata la rivendicazione." }, "domain": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "unverified", "code_sent", "verified" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "txt": { "$ref": "#/components/schemas/TravelRuleWorkspaceTxtRecord" } } }, "billing_enabled": { "type": "boolean", "description": "La ricezione dei dati della Travel Rule è gratuita. L'invio viene fatturato solo dopo l'abilitazione della fatturazione." }, "billing_enabled_at": { "type": "string", "format": "date-time", "nullable": true }, "didit_network": { "type": "object", "description": "Indica se la rete Didit elenca questo VASP e, in caso contrario, ciascuna condizione ancora mancante." }, "settings": { "$ref": "#/components/schemas/TravelRuleSettingsDetail" } } }, "InvestigatorDecision": { "type": "object", "description": "Come l'elemento è uscito dalla coda Investigator. `decided_by`, `original_outcome` e `overrides` sono restituiti dagli endpoint di approvazione e modifica (override) e dal report; il blocco `investigator` di una decisione di sessione contiene gli altri campi.", "properties": { "outcome": { "type": "string", "enum": [ "accepted", "edited", "overridden", "decided_elsewhere", "automated" ], "description": "`accepted` o `edited` ha accolto la raccomandazione (`edited` con una narrativa riscritta), `overridden` ha intrapreso un'altra azione, `decided_elsewhere` è una decisione presa all'esterno dell'Investigator mentre il report era aperto, `automated` è una decisione che l'Investigator ha preso autonomamente." }, "action": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "override_category": { "type": "string", "enum": [ "missing_context", "needs_information", "policy_differs", "evidence_misread", "other", "" ], "nullable": true }, "override_reason": { "type": "string", "nullable": true }, "final_status": { "type": "string", "description": "Lo stato dell'elemento dopo la decisione." }, "agreed": { "type": "boolean", "description": "Indica se la decisione corrispondeva alla raccomandazione.", "nullable": true }, "decided_at": { "type": "string", "format": "date-time" }, "billed": { "type": "boolean", "description": "La revisione è stata addebitata." }, "decided_by": { "type": "string", "enum": [ "investigator", "member" ] }, "original_outcome": { "type": "object", "description": "La decisione presa autonomamente dall'Investigator, non modificata da successive sovrascritture. Null per una decisione presa dal team.", "properties": { "action": { "type": "string" }, "final_status": { "type": "string" }, "decided_at": { "type": "string", "format": "date-time" } }, "nullable": true }, "overrides": { "type": "array", "description": "Ogni override di una decisione presa autonomamente dall'Investigator, dalla più vecchia alla più recente.", "items": { "type": "object", "properties": { "action": { "type": "string" }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "override_category": { "type": "string" }, "override_reason": { "type": "string" }, "previous_status": { "type": "string" }, "final_status": { "type": "string" }, "agreed": { "type": "boolean", "nullable": true }, "overridden_at": { "type": "string", "format": "date-time" } } } } } }, "InvestigatorBlock": { "type": "object", "nullable": true, "description": "L'ultima revisione Investigator dell'elemento, o null se non ne ha mai avuta una. Inclusa nella decisione della sessione V3 e della sessione aziendale (e quindi dai webhook `status.updated`).", "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "stage": { "type": "string", "enum": [ "shadow", "live" ] }, "queue": { "type": "string", "enum": [ "kyc", "kyb", "aml", "transactions", "cases" ] }, "is_open": { "type": "boolean" }, "recommendation": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ], "nullable": true }, "recommendation_detail": { "type": "string", "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "moderate", "low" ], "nullable": true }, "summary": { "type": "string", "nullable": true }, "ready_to_accept": { "type": "boolean" }, "prepared_at": { "type": "string", "format": "date-time", "nullable": true }, "automated": { "type": "boolean", "description": "L'Investigator ha deciso in autonomia, anche se la decisione è stata successivamente sovrascritta." }, "decided_by": { "type": "string", "enum": [ "investigator", "member" ], "nullable": true }, "decision": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InvestigatorDecision" } ], "type": "object" } } }, "InvestigatorQueueRow": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "session", "business_session", "transaction", "case" ] }, "queue": { "type": "string", "enum": [ "kyc", "kyb", "aml", "transactions", "cases" ] }, "stage": { "type": "string", "enum": [ "shadow", "live" ] }, "subject": { "type": "object", "description": "L'elemento in revisione: `id`, `number`, `status`, `name` e, a seconda della tipologia, `country`, `workflow`, `vendor_data`, `txn_id`, `amount`, `currency`, `direction`, `title` o `priority`.", "additionalProperties": true }, "recommendation": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] }, "recommendation_detail": { "type": "string" }, "confidence": { "type": "string", "enum": [ "high", "moderate", "low" ] }, "summary": { "type": "string" }, "sources_count": { "type": "integer" }, "ready_to_accept": { "type": "boolean" }, "guardrails": { "description": "I guardrail bloccati a cui è soggetto questo elemento, se presenti." }, "waiting_since": { "type": "string", "format": "date-time", "nullable": true }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "prepared_at": { "type": "string", "format": "date-time", "nullable": true } } }, "InvestigatorRunDetail": { "allOf": [ { "$ref": "#/components/schemas/InvestigatorQueueRow" }, { "type": "object", "properties": { "status": { "type": "string" }, "is_open": { "type": "boolean" }, "lookups": { "type": "integer", "description": "Quante sezioni e record collegati ha letto." }, "duration_ms": { "type": "integer", "nullable": true }, "agent_version": { "type": "string" }, "prepared_before_opened": { "type": "boolean", "nullable": true }, "report": { "type": "object", "additionalProperties": true, "description": "Il report: motivazione, elementi probatori con il relativo verdetto (`ok`, `risk`, `look`, `explained`, `context`) e fonti citate, verdetti delle corrispondenze di screening (`same`, `not_same`, `unclear`) e passaggi successivi suggeriti." }, "trail": { "description": "Cosa ho verificato: la panoramica, le sezioni e i record letti, nell'ordine." }, "decision": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InvestigatorDecision" } ], "type": "object" }, "autonomy": { "type": "object", "additionalProperties": true, "description": "Cosa ha stabilito il sistema autonomo riguardo al report (`result`, `reason`, `tier`, `policy_version`, `rule`, `agreement`, `decisions`, `threshold`, `at`). Null quando la coda non è automatizzata.", "nullable": true } } } ] }, "InvestigatorAcceptRequest": { "type": "object", "properties": { "narrative": { "type": "string", "maxLength": 4000, "description": "Una descrizione riscritta. L'invio di una di esse registra la decisione come modificata e accettata." }, "send_email": { "type": "boolean", "default": false, "description": "Invia un'email alla persona riguardo alla decisione." }, "email_address": { "type": "string", "format": "email", "description": "Obbligatorio quando `send_email` è true." }, "email_language": { "type": "string", "default": "en", "maxLength": 16 } } }, "InvestigatorOverrideRequest": { "type": "object", "required": [ "action", "category", "reason" ], "properties": { "action": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] }, "category": { "type": "string", "enum": [ "missing_context", "needs_information", "policy_differs", "evidence_misread", "other" ] }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 }, "send_email": { "type": "boolean", "default": false, "description": "Invia un'email alla persona riguardo alla decisione." }, "email_address": { "type": "string", "format": "email", "description": "Obbligatorio quando `send_email` è true." }, "email_language": { "type": "string", "default": "en", "maxLength": 16 } } }, "InvestigatorBatchAcceptRequest": { "type": "object", "required": [ "run_ids" ], "properties": { "run_ids": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "format": "uuid" } } } }, "InvestigatorBatchAcceptResponse": { "type": "object", "properties": { "accepted": { "type": "integer" }, "skipped": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" }, "result": { "type": "string", "enum": [ "accepted", "skipped" ] }, "reason": { "type": "string", "enum": [ "not_found", "forbidden", "already_decided", "not_ready", "guardrail", "invalid" ] }, "detail": {}, "action": { "type": "string" }, "final_status": { "type": "string" } } } } } }, "InvestigatorSettings": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "none", "shadow", "live" ] }, "stage_changed_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "stage_changed_by": { "type": "string", "readOnly": true }, "monthly_spend_limit": { "type": "string", "format": "decimal", "description": "Limite mensile nella tua valuta di fatturazione, da 0.01 a 1,000,000. Null lo disattiva.", "nullable": true }, "spend_limit": { "type": "object", "readOnly": true, "properties": { "enabled": { "type": "boolean" }, "limit": { "type": "string", "format": "decimal", "nullable": true }, "spent": { "type": "string", "format": "decimal" }, "reviews": { "type": "integer" }, "reserved": { "type": "string", "format": "decimal", "description": "Il prezzo di ogni report di produzione aperto, trattenuto poiché accettarlo comporta un addebito." }, "currency": { "type": "string" }, "paused": { "type": "boolean", "description": "Al limite: non viene avviata alcuna nuova revisione." } } } } }, "TravelRuleUtxoEntry": { "type": "object", "description": "Un input o output di una transazione UTXO, così come registrato dalla blockchain.", "required": [ "address" ], "properties": { "address": { "type": "string", "maxLength": 128 }, "amount": { "type": "string", "nullable": true, "description": "Stringa decimale nell'unità propria della moneta (BTC, non satoshi). Facoltativo.", "example": "0.0125" }, "txid": { "type": "string", "maxLength": 128, "description": "Opzionale. La transazione utilizzata da un input." }, "vout": { "type": "integer", "nullable": true, "minimum": 0, "description": "Opzionale. L'indice di output speso da un input." } } }, "TravelRuleUtxo": { "type": "object", "description": "Gli input e gli output di un trasferimento UTXO (BTC, LTC, BCH, DOGE). Accettati solo su queste blockchain: su qualsiasi altra blockchain restituisce `400`. Da essi Didit deduce il wallet dell'ordinante (quello dichiarato, altrimenti l'indirizzo di input che ha contribuito di più) e l'output del beneficiario (quello dichiarato, altrimenti l'unico output che non restituisce il resto a un indirizzo di input, altrimenti l'output che paga l'importo del trasferimento). Il risultato si trova in `chain_details` del trasferimento.", "required": [ "outputs" ], "properties": { "inputs": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" }, "description": "Opzionale. Senza input non viene dedotto alcun ordinante e non viene riconosciuto alcun output di resto." }, "outputs": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" } } } }, "TravelRuleChainSide": { "type": "object", "description": "Il wallet di una delle parti, così come Didit lo ha risolto a partire dai dati della blockchain.", "properties": { "address": { "type": "string", "description": "Il wallet. Su una rete con memo l'indirizzo classico (un X-address XRP viene suddiviso nel relativo indirizzo classico e tag); su Lightning l'ID del nodo del beneficiario o il Lightning Address." }, "memo": { "type": "string", "description": "Il destination tag o memo che fa parte del wallet; `\"\"` se assente." }, "source": { "type": "string", "enum": [ "declared", "x_address", "largest_input", "only_non_change_output", "amount_match", "invoice_payee", "updated" ], "description": "Origine del wallet: `declared` (la tua richiesta), `x_address` (estratto da un X-address XRP), `largest_input` (l'indirizzo di input UTXO che ha contribuito maggiormente), `only_non_change_output` (l'unico output UTXO non di resto), `amount_match` (l'unico output UTXO che paga l'importo del trasferimento), `invoice_payee` (il beneficiario indicato in una richiesta di pagamento Lightning), `updated` (impostato successivamente con `action: update_originator_wallet`)." } } }, "TravelRuleChainDetails": { "type": "object", "description": "In che modo la blockchain del trasferimento identifica i suoi due wallet, quando si tratta di più di un indirizzo che ne paga un altro. Vuoto (`{}`) per un trasferimento su blockchain basata su account (EVM, Solana, Tron), dove i due indirizzi corrispondono ai wallet. La corrispondenza, l'instradamento e la rubrica leggono innanzitutto i wallet da qui.", "properties": { "chain": { "type": "string", "description": "Rete blockchain canonica, ad es. `BTC`, `XRP` o `LIGHTNING` per un trasferimento Lightning." }, "shape": { "type": "string", "enum": [ "utxo", "memo", "lightning" ] }, "originator": { "$ref": "#/components/schemas/TravelRuleChainSide" }, "beneficiary": { "$ref": "#/components/schemas/TravelRuleChainSide" }, "utxo": { "type": "object", "description": "Su un trasferimento UTXO: gli input e gli output come memorizzati (importi come stringhe decimali) e quali output Didit ha interpretato come cosa.", "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" } }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" } }, "change_output_indexes": { "type": "array", "items": { "type": "integer" }, "description": "Output che rimborsano un indirizzo di input." }, "beneficiary_output_index": { "type": "integer", "nullable": true, "description": "L'output che paga il beneficiario; null quando non è stato possibile distinguerne alcuno." } } }, "lightning": { "type": "object", "description": "Su un trasferimento Lightning: ciò che indica la richiesta di pagamento. Sempre `kind` (`bolt11`, `bolt12_offer`, `bolt12_invoice`, `bolt12_invoice_request`, `lnurl`, `lightning_address`, `node_id` o `unknown`); una fattura BOLT11 aggiunge `network`, `payee_node_id`, `payment_hash`, `amount_msat`, `created_at` e `expires_at`; una stringa BOLT12 `blinded_paths` e `payee_node_id`; un LNURL o un Lightning Address il suo `domain`. Nulla viene risolto sulla rete: la richiesta viene solo decodificata.", "additionalProperties": true }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "declared_originator_not_an_input", "declared_beneficiary_not_an_output", "beneficiary_output_ambiguous", "beneficiary_output_amount_differs" ] }, "description": "Incongruenze UTXO da esaminare: l'ordinante dichiarato non è un input, il beneficiario dichiarato non è un output, non è stato possibile distinguere un singolo output del beneficiario, oppure l'output del beneficiario corrisponde a un importo diverso rispetto a quello indicato nella transazione." }, "not_applicable_reason": { "type": "string", "enum": [ "LIGHTNING_NO_PAYEE_IDENTIFIER", "LIGHTNING_BOLT12_BLINDED_PAYEE", "LIGHTNING_LNURL_NAMES_NO_PAYEE" ], "description": "Su un trasferimento Lightning in uscita la cui richiesta di pagamento non indica alcun beneficiario: perché il trasferimento è `NOT_APPLICABLE`. `LIGHTNING_NO_PAYEE_IDENTIFIER` (la richiesta non indica alcun nodo beneficiario o non è stato possibile decodificarla), `LIGHTNING_BOLT12_BLINDED_PAYEE` (l'offerta nasconde il proprio beneficiario dietro percorsi ciechi), `LIGHTNING_LNURL_NAMES_NO_PAYEE` (un LNURL indica un servizio, non un beneficiario). Lo stesso codice apre l'ultima voce `timeline` del trasferimento." } } }, "WalletAddressImportRow": { "type": "object", "description": "Un singolo wallet da importare: tramite il relativo `address`, il relativo `address_hash` o entrambi. Sono accettate anche le forme camelCase di questi campi, così come `walletAddress`, `walletAddressHash`, `destinationTag` ed `externalUserId`.", "properties": { "address": { "type": "string", "maxLength": 128, "description": "L'indirizzo del wallet. Alias: `walletAddress`." }, "address_hash": { "type": "string", "description": "SHA-256 dell'indirizzo in minuscolo, come 64 caratteri esadecimali o 44 caratteri base64. Invialo da solo per registrare un wallet senza rivelarne l'indirizzo; se inviato con `address`, deve essere l'hash di quell'indirizzo. Alias: `walletAddressHash`." }, "chain": { "type": "string", "maxLength": 32 }, "memo": { "type": "string", "maxLength": 256, "description": "Il tag o memo di destinazione. XRP: un destination tag, un numero intero da 0 a 4294967295 (è accettato un numero JSON). XLM: un memo testuale fino a 28 byte, un ID a 64 bit o un hash di 32 byte in formato esadecimale. EOS: fino a 256 byte. ATOM: fino a 256 caratteri. HBAR: fino a 100 byte. I wallet Bitcoin, EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin e Lightning non supportano memo: specificarne uno restituisce un errore `400`." }, "holder_name": { "type": "string", "maxLength": 255 }, "holder_vendor_data": { "type": "string", "maxLength": 255, "description": "Il tuo identificatore interno per il titolare. Alias: `externalUserId`." }, "entity_type": { "type": "string", "enum": [ "individual", "company" ], "default": "individual" }, "label": { "type": "string", "maxLength": 255 }, "owner_type": { "type": "string", "enum": [ "customer", "internal", "vasp" ], "default": "customer" }, "travel_address": { "type": "string", "maxLength": 512 }, "self_declared": { "type": "boolean", "default": false, "description": "Crea la voce già verificata tramite autodichiarazione, quando le tue impostazioni lo consentono." } } }, "WalletAddressImportReport": { "type": "object", "description": "Cosa è successo a ciascuna riga di un'importazione, nell'ordine inviato.", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "existing": { "type": "integer" }, "duplicate": { "type": "integer" }, "failed": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "description": "Il numero della riga, a partire da 1." }, "status": { "type": "string", "enum": [ "created", "existing", "duplicate", "failed" ], "description": "`created`: aggiunto alla rubrica. `existing`: il wallet è già presente nella rubrica ed è rimasto invariato. `duplicate`: ripete una riga precedente di questa importazione. `failed`: vedi `errors`." }, "entry_id": { "type": "string", "format": "uuid", "nullable": true, "description": "La voce della rubrica creata o trovata dalla riga." }, "errors": { "type": "object", "description": "Errori di campo di una riga `failed`; vuoto altrimenti." }, "duplicate_of_row": { "type": "integer", "nullable": true, "description": "Su una riga `duplicate`, la riga che ripete." } } } } } }, "TravelRuleCounterpartyContact": { "type": "object", "description": "Un indirizzo di compliance a cui la via EMAIL scrive per una voce della directory.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "counterparty": { "type": "string", "format": "uuid", "description": "L'`id` della voce della directory, come mostrato da GET /v3/travel-rule/vasps/." }, "counterparty_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "description": "Etichetta opzionale, ad esempio il nome del team." }, "source": { "type": "string", "enum": [ "staff", "application", "learned" ], "description": "staff: curato da Didit. learned: un indirizzo presso uno dei domini propri del VASP che ha risposto a una richiesta tramite il relativo link di risposta. application: aggiunto dalla tua applicazione." }, "scope": { "type": "string", "enum": [ "platform", "application" ], "description": "platform: curato da Didit o appreso da una risposta verificata, utilizzato per ogni cliente Didit, in sola lettura per te. application: privato per la tua applicazione." }, "created_by": { "type": "string", "description": "Vuoto per i contatti della piattaforma e per i contatti aggiunti da una chiave API." }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando questo indirizzo ha risposto l'ultima volta a una richiesta tramite il relativo link di risposta." }, "is_invalid": { "type": "boolean", "description": "true quando l'indirizzo ha generato un bounce o un reclamo; il rail EMAIL lo salta." }, "invalid_reason": { "type": "string", "enum": [ "", "hard_bounce", "soft_bounce", "spam_complaint", "suppressed" ] }, "invalid_detail": { "type": "string", "description": "Il motivo fornito dal server di posta ricevente, se disponibile." }, "invalid_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleCounterpartyContactCreate": { "type": "object", "required": [ "counterparty", "email" ], "properties": { "counterparty": { "type": "string", "format": "uuid", "description": "L'`id` della voce della directory." }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "name": { "type": "string", "description": "Etichetta opzionale.", "maxLength": 255 } } }, "TravelRuleNameMatch": { "type": "object", "nullable": true, "description": "Il confronto dei nomi che ha determinato il trasferimento, o null fino all'esecuzione. Mentre le parti sono oscurate, e sulla copia dell'altro cliente di uno scambio INTERNAL, `transfer_name`, `compared_name`, `matched_names` e `mismatched_names` rimangono nascosti. `score` e `matched` possono discordare: `matched` segue il livello di rigore, `score` è la somiglianza dei due nomi completi.", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Somiglianza dei due nomi completi, da 0 a 100. 0 quando uno dei due nomi è vuoto." }, "matched": { "type": "boolean", "description": "Indica se i nomi soddisfano `strictness`. L'esito del trasferimento segue `data_match`, che confronta ogni campo, pertanto un trasferimento può essere COUNTERPARTY_MISMATCHED_DATA anche quando questo valore è true." }, "method": { "type": "string", "enum": [ "none", "exact_token", "token_subset", "token_containment", "sequence_ratio" ], "description": "Modalità con cui è stato determinato `matched`: nessuno (`NONE`), exact_token (`STRICT`), token_subset (`DEFAULT`), token_containment (`CONTAINS`) o sequence_ratio (`FUZZY`)." }, "strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ] }, "compared_with": { "type": "string", "enum": [ "wallet_holder", "counterparty_vasp" ], "description": "wallet_holder: il titolare registrato per il wallet. counterparty_vasp: il nome indicato dalla controparte nella pagina di risposta via email, o la risposta di Didit Test VASP in sandbox." }, "transfer_name": { "type": "string", "description": "Il nome sul trasferimento." }, "compared_name": { "type": "string", "description": "Il nome con cui è stato confrontato." }, "matched_names": { "type": "array", "items": { "type": "string" }, "description": "Parole di `transfer_name` trovate in `compared_name`." }, "mismatched_names": { "type": "array", "items": { "type": "string" }, "description": "Parole di `transfer_name` mancanti da `compared_name`, seguite dalle parole di `compared_name` mancanti da `transfer_name`." } } }, "TravelRuleTransferRow": { "type": "object", "description": "Un trasferimento Travel Rule così come mostrato nell'elenco dei trasferimenti: solo nomi dei VASP, wallet e memo, mai i dati personali dell'ordinante o del beneficiario.", "properties": { "id": { "type": "string", "format": "uuid", "description": "L'id del trasferimento." }, "transaction_id": { "type": "string", "format": "uuid", "description": "La transazione Didit a cui appartiene il trasferimento." }, "txn_id": { "type": "string", "nullable": true, "description": "Il tuo ID per la transazione. I trasferimenti che Didit registra per te, come un trasferimento in entrata di un Test VASP Didit, ne includono uno generato automaticamente." }, "txn_date": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "withdrawal", "deposit", "message" ], "description": "withdrawal: in uscita. message: un trasferimento in entrata creato da un rail a partire dal messaggio di una controparte (una richiesta TRP, la tratta in entrata INTERNAL o un messaggio GTR, VerifyVASP o Sygna Bridge). deposit: qualsiasi altro trasferimento in entrata." }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string", "enum": [ "AWAITING_COUNTERPARTY", "ON_HOLD", "COMPLETED", "FINISHED", "CANCELLED", "EXPIRED", "COUNTERPARTY_MISMATCHED_DATA", "COUNTERPARTY_VASP_NOT_FOUND", "COUNTERPARTY_VASP_NOT_REACHABLE", "UNCONFIRMED_OWNERSHIP", "COUNTERPARTY_VASP_GENERAL_DECLINE", "NOT_ENOUGH_COUNTERPARTY_DATA", "NOT_APPLICABLE" ] }, "reason": { "type": "string", "description": "Il motivo per cui un trasferimento `COUNTERPARTY_VASP_NOT_FOUND` o `COUNTERPARTY_VASP_NOT_REACHABLE` è bloccato, lo stesso valore di `reason` del trasferimento stesso, così che l'elenco distingua un'email di compliance rimbalzata da una controparte senza rotta senza dover aprire ciascun trasferimento. `\"\"` per qualsiasi altro stato. Consulta [Perché un trasferimento è bloccato](/it/transaction-monitoring/travel-rule#perché-un-trasferimento-è-bloccato)." }, "rail": { "type": "string", "nullable": true, "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "TEST_VASP", null ] }, "asset": { "type": "string", "description": "La valuta della transazione." }, "amount": { "type": "string", "description": "L'importo come valore decimale semplice, ad esempio \"1.25\"." }, "originator_vasp": { "type": "string", "description": "In uscita: la ragione sociale del tuo VASP. In entrata: il nome della controparte, dalla relativa voce di directory, dal membro della rete Didit, dal mittente TRP, dal Didit Test VASP o dal nome dichiarato dal trasferimento. Vuoto se non è noto alcun nome." }, "beneficiary_vasp": { "type": "string", "description": "In uscita: il nome della controparte, ricavato nello stesso modo. In entrata: la ragione sociale del tuo VASP." }, "originator_wallet": { "type": "string" }, "beneficiary_wallet": { "type": "string" }, "originator_memo": { "type": "string", "description": "Memo o tag di destinazione, vuoto sulle blockchain che non ne prevedono uno." }, "beneficiary_memo": { "type": "string" }, "originator_wallet_type": { "type": "string", "enum": [ "vasp", "self_hosted", "own" ], "description": "vasp, self_hosted (dichiarato non custodito) o own (un wallet registrato come tuo nella tua rubrica). La tua parte è sempre vasp." }, "beneficiary_wallet_type": { "type": "string", "enum": [ "vasp", "self_hosted", "own" ] }, "matched_transaction_id": { "type": "string", "format": "uuid", "nullable": true, "description": "La controparte di un deposito associata manualmente a un trasferimento annunciato." }, "deadline_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando scade il trasferimento se è ancora in attesa della controparte. Viene impostato su ogni trasferimento creato con `POST /v3/transactions/` che richiede uno scambio, in uscita o in entrata. Null al di sotto della soglia, su un pagamento Lightning a cui non si applica la Travel Rule e sui trasferimenti in entrata creati da Didit quando una controparte ti contatta (un'indagine TRP in entrata, un messaggio di rete o la tratta in entrata INTERNAL)." }, "created_at": { "type": "string", "format": "date-time" } } }, "BankAccountCheckHolder": { "description": "Il nome rispetto al quale viene verificato il conto. Invia esattamente uno tra `full_name` e `business_name`.", "oneOf": [ { "$ref": "#/components/schemas/BankAccountCheckPersonHolder" }, { "$ref": "#/components/schemas/BankAccountCheckBusinessHolder" } ] }, "BankAccountCheckRequest": { "type": "object", "required": [ "country", "account", "holder" ], "properties": { "country": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Il paese del conto, come codice ISO 3166-1 alpha-3, ad esempio `NGA`. I caratteri minuscoli sono accettati.", "example": "NGA" }, "account": { "type": "object", "description": "Il conto bancario nel formato previsto dal relativo paese: un `iban`, oppure un `account_number` accompagnato dal codice bancario o di filiale richiesto dal paese (`sort_code`, `routing_number`, `transit_institution`, `bsb`, `ifsc`, `bank_code` o `bic`). Il Messico prevede una `clabe` e l'Argentina un `cbu_cvu`, che identificano già la banca. Un conto aziendale aggiunge un `registration_id` laddove il paese lo richieda. Spazi, trattini e punti vengono ignorati. Le chiavi non utilizzate dal controllo del paese vengono ignorate; una chiave necessaria ma assente restituisce un `400` indicandone il nome.", "properties": { "iban": { "type": "string", "maxLength": 64, "description": "L'IBAN, in un paese che utilizza gli IBAN. Deve appartenere a `country`." }, "account_number": { "type": "string", "maxLength": 64, "description": "Il numero di conto, in un paese in cui il conto viene indicato con un codice bancario o di filiale separato." }, "sort_code": { "type": "string", "maxLength": 64, "description": "Regno Unito: il sort code a 6 cifre." }, "routing_number": { "type": "string", "maxLength": 64, "description": "Stati Uniti: il routing number ABA a 9 cifre." }, "transit_institution": { "type": "string", "maxLength": 64, "description": "Canada: il numero di transito e dell'istituto, composto da 8 cifre." }, "bsb": { "type": "string", "maxLength": 64, "description": "Australia: il BSB a 6 cifre." }, "ifsc": { "type": "string", "maxLength": 64, "description": "India: codice IFSC di 11 caratteri." }, "bank_code": { "type": "string", "maxLength": 64, "description": "Il codice della banca, laddove il paese ne richieda uno, ad esempio in Nigeria." }, "bic": { "type": "string", "maxLength": 64, "description": "Il BIC della banca, laddove il controllo del paese ne richieda uno." }, "clabe": { "type": "string", "maxLength": 64, "description": "Messico: la CLABE a 18 cifre. Specifica già la banca." }, "cbu_cvu": { "type": "string", "maxLength": 64, "description": "Argentina: il CBU o CVU a 22 cifre. Identifica già la banca." }, "registration_id": { "type": "string", "maxLength": 64, "description": "Il numero di registrazione di un account aziendale, laddove il paese ne richieda uno." } }, "additionalProperties": { "type": "string", "maxLength": 64 }, "example": { "bank_code": "000014", "account_number": "0123450001" } }, "holder": { "$ref": "#/components/schemas/BankAccountCheckHolder" }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questo controllo, restituito invariato.", "example": "payout_20481" }, "consent": { "type": "boolean", "default": false, "description": "Imposta su `true` quando il titolare del conto ha acconsentito esplicitamente a questo controllo. Obbligatorio nei paesi in cui il controllo del conto richiede tale consenso: senza di esso il controllo viene rifiutato con un errore `400` il cui `field` è `consent` e il cui `reason` è `required`, e non viene addebitato nulla. Altrove è facoltativo e Didit lo registra insieme all'addebito del controllo quando lo invii.", "example": true } } }, "BankAccountCheckResponse": { "type": "object", "required": [ "request_id", "result", "holder_name", "account", "vendor_data", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "L'ID di questo controllo." }, "result": { "type": "string", "enum": [ "match", "close_match", "no_match", "cannot_verify" ], "description": "`match`: il conto presso la banca è intestato al nome che hai inviato. `close_match`: a un nome simile, ad esempio con un secondo nome mancante o un refuso. `no_match`: a un altro nome, oppure il conto non esiste. `cannot_verify`: la banca ha risposto senza confrontare il nome, ad esempio per un conto bloccato o chiuso." }, "holder_name": { "type": "string", "nullable": true, "description": "Solo in caso di `close_match`, e solo se restituito dalla banca: il nome presente sul conto, così come registrato dalla banca. In caso contrario, `null`." }, "account": { "type": "string", "description": "Il conto, mascherato lasciando visibili solo gli ultimi 4 caratteri." }, "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento, così come lo hai inviato." }, "created_at": { "type": "string", "format": "date-time", "description": "Data e ora di esecuzione del controllo, in formato UTC." } } }, "BankAccountCheckError": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string", "description": "Cosa è andato storto, in inglese." }, "code": { "type": "string", "description": "Un codice stabile su cui creare diramazioni. Assente su `401` e `403`." }, "field": { "type": "string", "description": "Solo per `400`: il campo del corpo della richiesta da correggere, come percorso separato da punti, ad esempio `account.sort_code`." }, "reason": { "type": "string", "enum": [ "required", "length", "format", "checksum", "country_mismatch", "rejected" ], "description": "Solo per `400`: il motivo per cui il campo è stato rifiutato. `required`, `length`, `format`, `checksum` e `country_mismatch` (un IBAN di un altro paese) sono controlli propri di Didit; `rejected` indica che la banca ha rifiutato il conto così come inviato." } } }, "BankVerificationResult": { "type": "object", "description": "Il risultato di un passaggio di verifica bancaria, per Verifica degli utenti e Verifica aziendale (KYB). `method` indica come è stato verificato il conto, e `none` che la persona ha continuato senza una banca prima che venisse valutato qualsiasi tentativo. `continued_without_bank` indica che la persona ha continuato senza una banca, anche dopo un tentativo valutato. Consulta [Metodi di verifica bancaria](/it/core-technology/bank-verification/verification-methods) e [Quando la persona non può verificare il proprio conto bancario](/it/core-technology/bank-verification/fallbacks).", "properties": { "schema_version": { "type": "integer", "description": "Versione della struttura di questo risultato. Attualmente `1`." }, "bank_verification_id": { "type": "string", "format": "uuid", "description": "L'ID di questo risultato." }, "node_id": { "type": "string", "description": "Il nodo del workflow a cui appartiene questo risultato." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Expired" ], "description": "Il verdetto del passaggio, dopo le relative azioni e regole di stato." }, "original_status": { "type": "string", "nullable": true, "description": "Il primo verdetto raggiunto dal passaggio, prima di qualsiasi modifica successiva come una revisione manuale." }, "method": { "type": "string", "nullable": true, "enum": [ "open_banking", "account_lookup", "microdeposits", "statement", "none" ], "description": "Come è stato verificato il conto: `open_banking` (accesso bancario: la persona ha effettuato l'accesso presso la propria banca), `account_lookup` (controllo del conto: la persona ha inserito le coordinate bancarie e la banca ha confermato il nome), `microdeposits` o `statement` (caricamento di un estratto conto). `none` quando la persona ha proseguito senza banca prima che venisse valutato qualsiasi tentativo, quindi nessun conto è stato verificato. Dopo un tentativo valutato, mantiene il metodo di quel tentativo. `null` finché un conto non viene valutato e quando il workflow riduce i dati restituiti. Le regole del workflow leggono lo stesso valore come `bank.method`." }, "provider": { "type": "string", "nullable": true, "description": "La chiave della route che ha eseguito la connessione. Leggi `method`, non questa chiave, per determinare come è stato verificato l'account." }, "credential_source": { "type": "string", "nullable": true, "enum": [ "native", "byok" ], "description": "`native`: la route proprietaria di Didit, addebitata sul tuo saldo Didit. `byok`: un provider del marketplace che hai collegato con le tue credenziali." }, "route": { "type": "object", "nullable": true, "description": "Il percorso scelto prima del consenso. Non cambia mai in seguito.", "properties": { "provider_key": { "type": "string", "nullable": true, "description": "La chiave del percorso." }, "credential_source": { "type": "string", "enum": [ "native", "byok" ] }, "is_fallback": { "type": "boolean", "description": "Indica se il percorso di Didit ha sostituito un fornitore del marketplace che non è riuscito a connettersi." }, "provider_connection_id": { "type": "string", "nullable": true, "description": "La connessione al marketplace utilizzata, per `byok`." }, "requested_scopes": { "type": "array", "items": { "type": "string" }, "description": "I dati richiesti dalla connessione, ad esempio `ownership` o `balances`." } } }, "connection": { "type": "object", "nullable": true, "description": "La connessione dell'ultimo tentativo. `null` prima del primo tentativo.", "properties": { "status": { "type": "string", "enum": [ "pending", "connected", "cancelled", "timeout", "failed", "unsupported", "revoked", "expired" ] }, "institution_id": { "type": "string", "nullable": true, "description": "L'ID della banca. `null` per un controllo del conto in cui non è selezionata alcuna banca." }, "institution_name": { "type": "string", "nullable": true, "description": "Il nome della banca. `null` per un controllo del conto." }, "institution_country": { "type": "string", "nullable": true, "description": "Il paese del conto, ISO 3166-1 alpha-3." }, "oauth": { "type": "boolean", "nullable": true, "description": "Indica se l'accesso bancario è avvenuto tramite OAuth o app-to-app. `null` per un controllo del conto." }, "connected_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora in cui la connessione è riuscita." }, "consent_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora di termine del consenso bancario, per l'accesso bancario." }, "last_refreshed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora dell'ultima rilettura dei dati finanziari." }, "attempts": { "type": "integer", "description": "I tentativi impiegati dalla persona in questo passaggio, considerando tutti i metodi insieme." }, "reason_code": { "type": "string", "nullable": true, "description": "Il motivo per cui la connessione non è semplicemente `connected`, ad esempio `USER_CANCELLED`, `INSTITUTION_DOWN`, `ACCOUNT_NOT_FOUND`, `REFERENCE_IDENTITY_MISSING` o `VERIFICATION_COMPLETED`." } } }, "account": { "type": "object", "nullable": true, "description": "L'account valutato. `null` finché l'account non viene valutato.", "properties": { "account_id_masked": { "type": "string", "nullable": true, "description": "Il numero di conto, mascherato." }, "iban_masked": { "type": "string", "nullable": true, "description": "L'IBAN, mascherato." }, "sort_code": { "type": "string", "nullable": true, "description": "Il sort code, nel Regno Unito." }, "routing_number_masked": { "type": "string", "nullable": true, "description": "Il numero di routing, mascherato." }, "type": { "type": "string", "nullable": true, "enum": [ "checking", "current", "savings", "business", "other" ] }, "subtype": { "type": "string", "nullable": true, "description": "Il sottotipo di conto proprio della banca." }, "currency": { "type": "string", "nullable": true, "description": "Valuta ISO 4217 del conto." }, "holder_type": { "type": "string", "nullable": true, "enum": [ "person", "business", "unknown" ] }, "holders_count": { "type": "integer", "nullable": true }, "is_joint": { "type": "boolean", "nullable": true }, "is_business": { "type": "boolean", "nullable": true } } }, "ownership": { "type": "object", "nullable": true, "description": "Come l'intestatario del conto è stato confrontato con l'identità verificata. `null` finché un conto non viene valutato.", "properties": { "result": { "type": "string", "enum": [ "match", "partial_match", "no_match", "unknown", "not_verifiable" ], "description": "`partial_match` è una corrispondenza stretta. `not_verifiable`: la banca ha risposto senza un titolare con cui effettuare il confronto. `unknown`: non è stato possibile leggere la prova, oppure non c'era alcuna identità con cui effettuare il confronto." }, "reference_identity_source": { "type": "string", "nullable": true, "description": "Il passaggio rispetto alla cui identità è stato confrontato il titolare: `kyc`, `database_validation`, `expected_details`, `questionnaire`, `document_ai` o `kyb`." }, "name_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "Punteggio del nome del titolare calcolato da Didit." }, "provider_name_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "Il punteggio del nome dell'intestatario fornito dalla banca, se ne ha restituito uno." }, "address_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "Il punteggio dell'indirizzo del titolare, quando è stato eseguito il confronto dell'indirizzo." }, "email_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "Il punteggio dell'email del titolare, quando è stato eseguito il confronto dell'email." }, "phone_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "Il punteggio del telefono del titolare, quando è stato eseguito il confronto del telefono." }, "dob_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "Il punteggio della data di nascita del titolare, quando condivisa dalla banca." }, "close_match": { "type": "boolean", "nullable": true, "description": "Indica se il nome rientra nella fascia di corrispondenza ravvicinata." }, "holder_confirmation": { "type": "string", "nullable": true, "enum": [ "pending", "confirmed", "rejected" ], "description": "La risposta della persona alla richiesta di confermare un nome con corrispondenza ravvicinata. `null` se non è mai stato richiesto." }, "method": { "type": "string", "nullable": true, "enum": [ "exact", "token_set", "nickname", "transliteration", "fuzzy", "provider_only", "microdeposits" ], "description": "Quale confronto dei nomi ha generato il punteggio. Questo non rappresenta il metodo di verifica: consulta il campo `method` di primo livello a tale scopo." }, "matched_holder_index": { "type": "integer", "nullable": true }, "holders": { "type": "array", "items": { "type": "object" }, "description": "Ciascun titolare elencato dalla banca, con i relativi punteggi." }, "owner_identity_available": { "type": "boolean", "nullable": true }, "evidence_freshness": { "type": "string", "nullable": true, "enum": [ "live", "cached", "refreshed" ] }, "evaluated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando è stato calcolato il verdetto." } } }, "financial_data": { "type": "object", "description": "I dati finanziari letti dal passaggio. Solo l'accesso bancario li legge.", "properties": { "balances": { "type": "object", "nullable": true, "description": "Con l'ambito `balances`." }, "transactions": { "type": "object", "nullable": true, "description": "Con l'ambito `transactions`." }, "income": { "type": "object", "nullable": true, "description": "Con l'ambito `income`." }, "categorization": { "type": "object", "nullable": true, "description": "Categorizzazione Didit delle transazioni lette. `null` in loro assenza." }, "not_collected": { "type": "array", "items": { "type": "string", "enum": [ "balances", "income", "transactions" ] }, "description": "I dati richiesti dal passaggio che il metodo utilizzato per verificare il conto non raccoglie. I saldi, le transazioni e il reddito provengono esclusivamente dall'accesso bancario, pertanto un conto verificato tramite controllo del conto li elenca qui. Non è mai un errore. Vuoto altrimenti." } } }, "billing": { "type": "object", "nullable": true, "properties": { "route": { "type": "string", "enum": [ "native", "byok" ] }, "billed": { "type": "boolean" }, "marketplace_fee": { "type": "string", "nullable": true, "description": "La commissione della piattaforma marketplace addebitata, per `byok`." }, "usage_type": { "type": "string", "nullable": true, "description": "La voce di utilizzo su cui è stato addebitato il costo: `bank_verification` per un accesso bancario o una verifica del conto, `bank_statement_upload` per il caricamento di un estratto conto senza alcun tentativo bancario a pagamento precedente, e `bank_byok_fee` per la commissione del marketplace sul proprio provider. `null` quando non è stato fatturato nulla." } } }, "reference_identity": { "type": "object", "nullable": true, "description": "L'identità con cui il titolare è stato confrontato, insieme alla relativa fonte." }, "signals": { "type": "object", "nullable": true, "description": "Segnali dell'account letti dalla cronologia delle transazioni, se il passaggio ne ha letta una." }, "connection_abandoned": { "type": "boolean", "nullable": true, "description": "Indica se il passaggio si è concluso senza corrispondenza dopo che la persona ha abbandonato presso la propria banca." }, "not_covered": { "type": "boolean", "nullable": true, "description": "Indica se la banca o il paese della persona non sono stati raggiungibili in questo passaggio. È `true` anche quando la persona ha proseguito senza banca poiché nessun metodo era in grado di verificarne il paese o la banca." }, "continued_without_bank": { "type": "boolean", "description": "Indica se la persona ha abbandonato il passaggio con **Continue without your bank**. In tal caso `continuation` ne indica il motivo. `method` è `none` se non è stato valutato alcun tentativo prima di continuare. Dopo un tentativo valutato, ad esempio per un intestatario non corrispondente, `method` mantiene il metodo di tale tentativo e il relativo verdetto e i codici di motivo restano validi. Restituito anche quando il workflow limita i dati restituiti." }, "continuation": { "type": "object", "nullable": true, "description": "Come la persona ha proseguito senza banca. `null` quando non lo ha fatto. Quando il workflow riduce i dati restituiti, `reason` viene comunque restituito e ogni altra chiave è `null`.", "properties": { "reason": { "type": "string", "enum": [ "no_route", "institution_unsupported", "attempts_exhausted", "person_choice" ], "description": "Il motivo, determinato da Didit quando la persona ha proseguito: `no_route` (nessun accesso bancario o controllo del conto è disponibile nel suo paese), `institution_unsupported` (la banca selezionata non può essere utilizzata per questo passaggio), `attempts_exhausted` (tutti i tentativi sono già stati esauriti e nessuno era in corso) o `person_choice` (era disponibile un metodo di verifica e l'utente ha scelto di proseguire, anche quando la banca non era raggiungibile in quel momento). `no_route` e `institution_unsupported` seguono `bank_unsupported_action`, `attempts_exhausted` segue `bank_attempts_exhausted_action` e `person_choice` segue `bank_skipped_action`, a meno che un tentativo valutato non abbia già deciso il passaggio." }, "country": { "type": "string", "nullable": true, "description": "Il paese in cui la persona stava effettuando la verifica, in formato ISO 3166-1 alpha-3. `null` se ha proseguito prima di selezionarne uno." }, "offered": { "type": "array", "items": { "type": "string", "enum": [ "statement", "microdeposits" ] }, "nullable": true, "description": "Gli altri metodi di verifica offerti alla persona per quel paese quando ha proseguito, nell'ordine in cui sono stati proposti: `statement` (caricamento di un estratto conto), quindi `microdeposits`. Vuoto se non ne è stato offerto alcuno." }, "institution_id": { "type": "string", "nullable": true, "description": "Per `institution_unsupported`, l'ID della banca che la persona non ha potuto utilizzare: la banca scelta o la banca su cui si è concluso l'ultimo tentativo. Didit lo ricava dal proprio elenco di banche, mai dal dispositivo della persona, pertanto una banca non presente in tale elenco è `null`. `null` per qualsiasi altro motivo." }, "institution_name": { "type": "string", "nullable": true, "description": "Per `institution_unsupported`, il nome di tale banca, ricavato dallo stesso elenco di `institution_id`. `null` quando tale elenco non include la banca, e per qualsiasi altro motivo." }, "continued_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Quando la persona ha continuato." } } }, "evidence_purged_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora di eliminazione della prova bancaria ai sensi di `bank_evidence_retention_days`. `null` altrimenti." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Codici informativi, ad esempio `holder_declared`. Un avviso non modifica mai lo stato da solo." }, "reason_codes": { "type": "array", "items": { "type": "string" }, "description": "Il motivo per cui è stato emesso tale verdetto, ad esempio `OWNER_NAME_PARTIAL`. Possono applicarsene diversi. `NOT_COVERED`: la persona ha continuato senza banca perché nessun metodo poteva verificare il suo paese o la sua banca. `SKIPPED`: la persona ha scelto di continuare senza banca anche se era disponibile un metodo di verifica. Nessuno dei due viene aggiunto se un tentativo valutato ha già deciso il passaggio." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BankAccountCheckPersonHolder": { "type": "object", "description": "La persona che dovrebbe essere titolare dell'account.", "required": [ "full_name" ], "properties": { "full_name": { "type": "string", "maxLength": 255, "description": "Il nome completo dell'intestatario previsto per il conto.", "example": "Maria Oliveira" } } }, "BankAccountCheckBusinessHolder": { "type": "object", "description": "L'azienda che dovrebbe essere titolare del conto. Verifica un conto aziendale.", "required": [ "business_name" ], "properties": { "business_name": { "type": "string", "maxLength": 255, "description": "Il nome dell'azienda a cui deve essere intestato il conto. Verifica un conto aziendale." } } }, "BankVerificationPricing": { "type": "object", "description": "Prezzi di listino pubblici per Bank Verification: il caricamento dell'estratto conto, la commissione per la chiave del proprio provider e i metodi di ciascun paese.", "required": [ "currency", "statement_upload", "own_provider_fee_usd", "countries" ], "properties": { "currency": { "type": "string", "enum": [ "USD" ], "description": "Valuta di ciascun prezzo nella risposta.", "example": "USD" }, "statement_upload": { "$ref": "#/components/schemas/BankStatementUploadPricing" }, "own_provider_fee_usd": { "type": "string", "description": "Commissione per ogni verifica dell'assetto proprietario fatturabile su un percorso che utilizza il contratto del tuo provider anziché quello di Didit, addebitata indipendentemente dal risultato. Una connessione annullata, scaduta per timeout o abbandonata non viene fatturata. Stringa decimale con 4 cifre decimali, in USD.", "example": "0.0200" }, "countries": { "type": "object", "description": "Ogni paese, indicizzato per codice ISO 3166-1 alpha-3.", "additionalProperties": { "$ref": "#/components/schemas/BankVerificationPricingCountry" } } } }, "BankStatementUploadPricing": { "type": "object", "description": "Come viene tariffato il caricamento dell'estratto conto bancario.", "required": [ "price_usd", "included_after_charged_bank_attempt", "standalone_available" ], "properties": { "price_usd": { "type": "string", "description": "Prezzo del caricamento di un estratto conto dopo un tentativo bancario addebitato. Stringa decimale con 4 decimali, in USD.", "example": "0.0000" }, "included_after_charged_bank_attempt": { "type": "boolean", "description": "`true` quando il caricamento è incluso senza costi aggiuntivi dopo un tentativo bancario a pagamento nella stessa sessione.", "example": true }, "standalone_available": { "type": "boolean", "description": "`true` quando il caricamento di un estratto conto può essere eseguito autonomamente, senza un precedente tentativo bancario. `false` in produzione; le sessioni sandbox possono testarlo senza fatturazione.", "example": false } } }, "BankVerificationPricingCountry": { "type": "object", "description": "I metodi di verifica bancaria di un paese e i relativi prezzi di listino.", "required": [ "name", "methods" ], "properties": { "name": { "type": "string", "description": "Nome del paese in inglese.", "example": "United Kingdom" }, "methods": { "$ref": "#/components/schemas/BankVerificationPricingMethods" } } }, "BankVerificationPricingMethods": { "type": "object", "description": "I due metodi di Bank Verification in un paese.", "required": [ "open_banking", "account_lookup" ], "properties": { "open_banking": { "$ref": "#/components/schemas/BankSignInPricing" }, "account_lookup": { "$ref": "#/components/schemas/BankAccountCheckPricing" } } }, "BankSignInPricing": { "type": "object", "description": "Accesso bancario: la persona accede alla propria banca. Prezzo stabilito in base al mercato, identico per ogni banca al suo interno.", "required": [ "available", "market", "price_usd", "add_ons" ], "properties": { "available": { "type": "boolean", "description": "`true` solo dove Didit supporta l'accesso bancario in questo paese in produzione.", "example": true }, "market": { "type": "string", "nullable": true, "description": "Il mercato a cui si applica il prezzo. `null` se non disponibile.", "example": "UK and EEA" }, "price_usd": { "type": "string", "nullable": true, "description": "Prezzo di listino di un accesso a un conto bancario. `null` se non disponibile. Stringa decimale con 4 decimali, in USD.", "example": "0.7900" }, "add_ons": { "type": "object", "description": "Componenti aggiuntivi tariffati in questo paese, ciascuno come stringa decimale con 4 decimali in USD, aggiunti al prezzo dell'accesso bancario. Sono elencati solo i componenti aggiuntivi offerti dal paese; vuoto quando l'accesso bancario non è disponibile.", "properties": { "balance": { "type": "string", "description": "Componente aggiuntivo per il saldo dell'account.", "example": "0.3500" }, "transactions": { "type": "string", "description": "Add-on per le transazioni.", "example": "1.3000" } } } } }, "BankAccountCheckPricing": { "type": "object", "description": "Controllo del conto: la persona inserisce il proprio numero di conto e Didit lo verifica con la banca. Prezzo per paese.", "required": [ "available", "price_usd" ], "properties": { "available": { "type": "boolean", "description": "`true` solo dove Didit supporta la verifica del conto in questo paese in produzione.", "example": true }, "price_usd": { "type": "string", "nullable": true, "description": "Prezzo di listino di un controllo del conto a cui risponde la banca. `null` se non disponibile. Stringa decimale con 4 decimali, in USD.", "example": "0.4000" } } }, "ImportProvider": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ] }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "api_list", "api_ids", "export_file" ], "description": "`api_list`: Didit elenca i record con la chiave. `api_ids`: carica gli ID dei record da un'esportazione. `export_file`: carica un'esportazione nel formato di Didit." }, "record_noun": { "type": "string" }, "credential_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "secret": { "type": "boolean" } } } }, "regions": { "type": "array", "items": { "type": "string" } }, "required_permissions": { "type": "array", "items": { "type": "string" } }, "docs_url": { "type": "string", "nullable": true }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] } } } }, "ImportJobSummary": { "type": "object", "description": "Un job di importazione di qualsiasi tipo, nel formato letto dal pannello dei job di importazione della console.", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "sessions", "businesses", "users", "status_rules", "transactions" ] }, "source": { "type": "string", "enum": [ "file", "api", "provider" ] }, "provider": { "type": "string", "nullable": true }, "provider_name": { "type": "string", "nullable": true }, "filename": { "type": "string", "nullable": true }, "state": { "type": "string", "enum": [ "ready", "queued", "running", "paused", "completed", "errors", "failed", "cancelled" ], "description": "Lo stato del job così come mostrato nella console; `errors` corrisponde a un job completato con righe rifiutate." }, "status": { "type": "string" }, "is_dry_run": { "type": "boolean" }, "credential_hint": { "type": "string", "nullable": true }, "resumes_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "nullable": true }, "started_by": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "progress": { "type": "object", "properties": { "total": { "type": "integer", "format": "int64" }, "processed": { "type": "integer", "format": "int64" }, "imported": { "type": "integer", "format": "int64" }, "updated": { "type": "integer", "format": "int64" }, "already_in_didit": { "type": "integer", "format": "int64" }, "failed": { "type": "integer", "format": "int64" }, "not_finished": { "type": "integer", "format": "int64" }, "same_person": { "type": "integer", "format": "int64" } } }, "face_templates": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "built": { "type": "integer", "format": "int64" }, "duplicates": { "type": "integer", "format": "int64" }, "blocklisted": { "type": "integer", "format": "int64" } } }, "eta_seconds": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "FiledRegulatoryReport": { "type": "object", "description": "Un report normativo finalizzato che impedisce l'eliminazione richiesta.", "required": [ "uuid", "report_number", "report_type", "case_uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID del report." }, "report_number": { "type": "string", "description": "Numero del report mostrato nella Console (ad esempio, SAR-0001)." }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ], "description": "Tipo di report normativo." }, "case_uuid": { "type": "string", "format": "uuid", "description": "Caso a cui appartiene il report." } } }, "FiledReportTransaction": { "type": "object", "description": "Una transazione che non può essere eliminata perché inclusa in un report normativo finalizzato.", "required": [ "uuid", "transaction_id", "reports" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "UUID della transazione Didit." }, "transaction_id": { "type": "string", "description": "L'identificatore della transazione fornito al momento della creazione della transazione." }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/FiledRegulatoryReport" }, "description": "Report finalizzati che includono questa transazione." } } }, "InFiledReportError": { "type": "object", "description": "L'eliminazione è stata rifiutata perché i dati selezionati si trovano in un report normativo finalizzato. Non viene eliminato nulla. Elimina il report, quindi ripeti la richiesta.", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "in_filed_report" ], "description": "Codice di errore stabile per un'eliminazione bloccata da un report normativo finalizzato." }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/FiledRegulatoryReport" }, "description": "Report che bloccano l'eliminazione di una persona, azienda, caso o sessione." }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/FiledReportTransaction" }, "description": "Transazioni che bloccano l'eliminazione di una transazione, ciascuna con i report che la elencano." } } }, "SubjectDeletionInProgressError": { "type": "object", "description": "Un'altra richiesta sta ancora eliminando questa persona o azienda. Questa richiesta non ha eliminato nulla e può essere ripetuta una volta terminata tale eliminazione; un nuovo tentativo eliminerà quindi ciò che è ancora selezionato.", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "subject_deletion_in_progress" ], "description": "Codice di errore stabile per una persona o un'azienda che un'altra richiesta sta ancora eliminando." } } }, "TravelRuleNetworkParticipantSummary": { "type": "object", "nullable": true, "description": "Il partecipante di questa applicazione sulla rete, oppure null se non ne ha nessuno.", "properties": { "mode": { "type": "string", "enum": [ "platform", "own" ], "description": "platform: veicolato tramite la membership di Didit; own: sottoposto a onboarding sotto la membership dell'applicazione." }, "status": { "type": "string", "enum": [ "not_requested", "questionnaire_pending", "submitted_to_network", "active", "suspended", "rejected" ], "description": "not_requested: mai richiesta, oppure la rete ha rifiutato la prima richiesta (vedi last_error); questionnaire_pending: in attesa dell'approvazione del questionario di due diligence; submitted_to_network: trasmessa all'onboarding della rete; active: la rete ha assegnato a questa applicazione il proprio codice partecipante; suspended / rejected: Didit l'ha sospesa o rifiutata." }, "participant_code": { "type": "string", "description": "Il codice assegnato dalla rete a questa applicazione (per GTR, il relativo codice VASP). I messaggi in uscita riportano questo codice, mai quello di Didit." }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "activated_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "description": "La risposta della rete in caso di rifiuto della registrazione; vuota altrimenti." } } }, "TravelRuleNetworkState": { "type": "object", "description": "Come verrebbero inviati i messaggi Travel Rule su una rete per questa applicazione e perché non è possibile farlo. Stato della configurazione, non una verifica in tempo reale dello stato o della consegna.", "properties": { "rail": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "mode": { "type": "string", "enum": [ "own", "didit", "off", "unavailable" ], "description": "own: viene utilizzata la membership collegata dell'applicazione; didit: la membership di Didit include l'applicazione come partecipante attivo proprio; off: routing di piattaforma disabilitato in disabled_networks senza una propria membership; unavailable: nessun elemento può ancora trasmettere su questa rete (vedi state e reason)." }, "state": { "type": "string", "enum": [ "own_membership", "live_through_didit", "off", "didit_onboarding", "questionnaire_needed", "questionnaire_in_review", "request_access", "request_sent", "unavailable", "error" ], "description": "own_membership: trasmette la tua membership collegata; live_through_didit: trasmette il tuo partecipante sulla membership di Didit; off: hai disattivato il routing di piattaforma; didit_onboarding: la membership di Didit per questa rete non è ancora attiva, quindi non può veicolare alcun partecipante; questionnaire_needed / questionnaire_in_review: il questionario di due diligence deve essere inviato o è presso Didit; request_access: il questionario è approvato, richiedi l'accesso alla rete; request_sent: l'onboarding del tuo partecipante è in corso; unavailable: vedi reason; error: vedi reason." }, "reason": { "type": "string", "enum": [ "own_membership_connected", "platform_network_switched_off", "own_membership_only", "sandbox_application", "didit_membership_not_live", "participant_suspended", "participant_rejected", "questionnaire_not_submitted", "questionnaire_submitted", "questionnaire_changes_requested", "questionnaire_rejected", "participant_not_requested", "participant_active", "participant_key_missing", "participant_key_unresolved", "provisioning_failed", "questionnaire_pending", "submitted_to_network" ], "description": "Dettaglio dello stato leggibile dalla macchina. own_membership_only: Didit non supporta applicazioni su questa rete (TRUST), collega la tua iscrizione; sandbox_application: i trasferimenti in sandbox non raggiungono mai una rete; provisioning_failed: la rete ha rifiutato la registrazione, il last_error del partecipante ne indica il motivo e una nuova richiesta alla rete avvia un nuovo tentativo." }, "platform_available": { "type": "boolean", "description": "Indica se la partecipazione di Didit a questa rete è configurata; non si tratta di un controllo in tempo reale dello stato." }, "connected": { "type": "boolean", "description": "Indica se esiste un'adesione cliente collegata. Le credenziali vengono convalidate localmente; la convalida di rete avviene su uno scambio in tempo reale." }, "participant": { "$ref": "#/components/schemas/TravelRuleNetworkParticipantSummary" }, "vasps_reachable": { "type": "integer", "description": "VASP presenti nella directory e raggiungibili su questa rete." }, "routed_30d": { "type": "integer", "description": "I trasferimenti di questa applicazione veicolati su questa rete negli ultimi 30 giorni." } } }, "TravelRuleNetworkQuestionnaireAnswers": { "type": "object", "description": "Questionario di due diligence di rete di Didit. I salvataggi sono parziali: un salvataggio conserva ogni risposta non indicata. L'invio richiede tutti i campi tranne lei e data_protection_contact_email, e che le tre attestazioni siano true.", "properties": { "legal_name": { "type": "string", "maxLength": 255 }, "registration_number": { "type": "string", "maxLength": 255 }, "incorporation_country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Codice paese ISO 3166-1 alpha-2." }, "registered_address": { "type": "string", "maxLength": 1000 }, "website": { "type": "string", "format": "uri", "maxLength": 500 }, "lei": { "type": "string", "maxLength": 20, "description": "Opzionale. Un LEI ISO 17442 valido, se fornito." }, "licences": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "regulator", "jurisdiction", "licence_type", "licence_number" ], "properties": { "regulator": { "type": "string", "maxLength": 255 }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Codice paese ISO 3166-1 alpha-2." }, "licence_type": { "type": "string", "maxLength": 255 }, "licence_number": { "type": "string", "maxLength": 255 } } }, "description": "Ogni licenza o registrazione detenuta dal VASP." }, "operating_jurisdictions": { "type": "array", "minItems": 1, "maxItems": 250, "items": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Codice paese ISO 3166-1 alpha-2." } }, "compliance_officer_name": { "type": "string", "maxLength": 255 }, "compliance_officer_email": { "type": "string", "format": "email" }, "aml_ctf_policy_attested": { "type": "boolean", "description": "Deve essere true per l'invio." }, "sanctions_screening_attested": { "type": "boolean", "description": "Deve essere true per l'invio." }, "data_protection_attested": { "type": "boolean", "description": "Deve essere true per l'invio." }, "data_protection_contact_email": { "type": "string", "format": "email", "description": "Opzionale." }, "expected_monthly_transfers": { "type": "integer", "minimum": 0 }, "expected_monthly_volume_usd": { "type": "string", "format": "decimal", "description": "Volume mensile previsto in USD, fino a 2 cifre decimali. Restituito come stringa." }, "assets": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "maxLength": 32 }, "description": "Ticker degli asset, memorizzati in maiuscolo, ordinati e deduplicati." } } }, "TravelRuleNetworkQuestionnaire": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "submitted", "changes_requested", "approved", "rejected" ], "description": "Le risposte possono essere salvate mentre sono in bozza o in modifiche richieste; gli stati di invio, approvazione e rifiuto vengono gestiti da Didit." }, "answers": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaireAnswers" }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "review_note": { "type": "string", "description": "Nota di Didit sulla sua ultima decisione, ad esempio le modifiche da apportare." }, "history": { "type": "array", "readOnly": true, "description": "Ogni cambio di stato, dal più vecchio al più recente.", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "string" }, "note": { "type": "string", "description": "Nota di revisione o risposta della rete, quando presente." } } } }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "TravelRuleNetworkParticipant": { "type": "object", "description": "Il partecipante di questa applicazione su una rete.", "properties": { "network": { "type": "string", "enum": [ "gtr", "trust", "verifyvasp", "sygna" ] }, "rail": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "mode": { "type": "string", "enum": [ "platform", "own" ] }, "status": { "type": "string", "enum": [ "not_requested", "questionnaire_pending", "submitted_to_network", "active", "suspended", "rejected" ], "description": "not_requested: mai richiesta, oppure la rete ha rifiutato la prima richiesta (vedi last_error); questionnaire_pending: in attesa dell'approvazione del questionario di due diligence; submitted_to_network: trasmessa all'onboarding della rete; active: la rete ha assegnato a questa applicazione il proprio codice partecipante; suspended / rejected: Didit l'ha sospesa o rifiutata." }, "participant_code": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "activated_at": { "type": "string", "format": "date-time", "nullable": true }, "suspended_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "description": "La risposta della rete in caso di rifiuto della registrazione; vuota altrimenti." }, "history": { "type": "array", "readOnly": true, "description": "Ogni cambio di stato, dal più vecchio al più recente.", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "string" }, "note": { "type": "string", "description": "Nota di revisione o risposta della rete, quando presente." } } } } } }, "TravelRuleNetworksOverview": { "type": "object", "properties": { "platform_networks_enabled": { "type": "boolean", "description": "Indica se l'accesso di rete tramite l'adesione di Didit è aperto. Finché è impostato su false, i salvataggi dei questionari, gli invii e le richieste di rete rispondono con 403." }, "questionnaire": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleNetworkParticipant" } }, "networks": { "type": "object", "readOnly": true, "description": "Per ciascuna rete, come questa applicazione invierebbe e perché non può farlo. Nessuna rete, inclusa GTR, è inclusa per impostazione predefinita: una rete è raggiungibile tramite la tua adesione connessa, oppure tramite l'adesione di Didit una volta che l'adesione di Didit a tale rete è attiva e il tuo partecipante su di essa è attivo. Non si tratta di un controllo di stato o consegna in tempo reale.", "properties": { "gtr": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "trust": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "verifyvasp": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "sygna": { "$ref": "#/components/schemas/TravelRuleNetworkState" } } } } }, "AddressValidationResult": { "type": "object", "description": "Il risultato di una verifica dell'indirizzo (Address Validation): se l'indirizzo esiste e la sua forma normalizzata. Conferma esclusivamente l'indirizzo; non collega mai l'indirizzo a una persona.", "required": [ "status", "verification_level", "address", "formatted_address", "latitude", "longitude" ], "properties": { "status": { "type": "string", "enum": [ "verified", "partially_verified", "not_verified", "unavailable" ], "description": "`verified`: l'indirizzo è stato confermato fino all'edificio (o all'appartamento o alla casella postale). `partially_verified`: è stato confermato solo fino alla via, o al livello più preciso disponibile nei dati di riferimento postali per quel luogo. `not_verified`: corrisponde solo la regione o la città, oppure non corrisponde nulla. `unavailable`: non è stato possibile eseguire la validazione (ad esempio il servizio di riferimento non ha risposto); non viene addebitata e non influisce mai su una verifica." }, "verification_level": { "type": "string", "nullable": true, "enum": [ "administrative_area", "locality", "thoroughfare", "premise", "delivery_point", null ], "description": "Il livello più preciso a cui è stato associato l'indirizzo. `null` se non è stata trovata alcuna corrispondenza o se `status` è `unavailable`." }, "address": { "type": "object", "nullable": true, "description": "L'indirizzo normalizzato. `null` quando `status` è `unavailable`.", "properties": { "address_line_1": { "type": "string", "nullable": true, "description": "Prima riga di recapito, scritta secondo le convenzioni del paese.", "example": "1600 Amphitheatre Pkwy" }, "address_line_2": { "type": "string", "nullable": true, "description": "Seconda riga di recapito (appartamento, edificio o quartiere), se presente nell'indirizzo." }, "city": { "type": "string", "nullable": true, "example": "Mountain View" }, "region": { "type": "string", "nullable": true, "description": "Stato, provincia o regione.", "example": "CA" }, "postal_code": { "type": "string", "nullable": true, "example": "94043-1351" }, "country": { "type": "string", "nullable": true, "description": "Codice paese ISO 3166-1 alpha-2.", "example": "US" } } }, "formatted_address": { "type": "string", "nullable": true, "description": "L'indirizzo normalizzato su una riga.", "example": "1600 Amphitheatre Pkwy, Mountain View CA 94043-1351" }, "latitude": { "type": "number", "nullable": true, "example": 37.422022 }, "longitude": { "type": "number", "nullable": true, "example": -122.08429 } } }, "AddressValidationRequest": { "type": "object", "required": [ "country" ], "description": "Un indirizzo: su una riga (`address`) o come campi strutturati con almeno `address_line_1`, mai entrambi.", "properties": { "address": { "type": "string", "maxLength": 500, "description": "L'indirizzo completo su una sola riga.", "example": "Paseo de la Castellana 259, 28046 Madrid" }, "address_line_1": { "type": "string", "maxLength": 255, "description": "Via e numero civico.", "example": "1600 Amphitheatre Pkwy" }, "address_line_2": { "type": "string", "maxLength": 255, "description": "Appartamento, suite, piano o edificio." }, "city": { "type": "string", "maxLength": 128, "description": "Città o località.", "example": "Mountain View" }, "region": { "type": "string", "maxLength": 128, "description": "Stato, provincia o regione.", "example": "CA" }, "postal_code": { "type": "string", "maxLength": 32, "example": "94043" }, "country": { "type": "string", "maxLength": 3, "description": "Codice ISO 3166-1 alpha-2 o alpha-3 del paese dell'indirizzo.", "example": "US" } } }, "AddressValidationResponse": { "type": "object", "required": [ "request_id", "address_validation", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Identificatore di questa richiesta; comunicalo all'assistenza. Non viene creata alcuna sessione." }, "address_validation": { "$ref": "#/components/schemas/AddressValidationResult" }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleWalletProofFailureReason": { "type": "string", "enum": [ "", "SIGNATURE_INVALID", "SIGNATURE_UNSUPPORTED_SCHEME", "DEPOSIT_NOT_FOUND", "DEPOSIT_UNCONFIRMED", "DEPOSIT_LOOKUP_FAILED", "DEPOSIT_MISMATCH", "DEPOSIT_STALE", "TXID_REUSED", "CHAIN_UNSUPPORTED", "WINDOW_EXPIRED", "OWNERSHIP_CHANGED", "METHOD_SWITCHED", "REVIEW_REJECTED", "ABANDONED" ], "description": "Il motivo per cui una prova di titolarità del wallet, o il suo ultimo tentativo, non ha raggiunto lo stato VERIFIED. Vuoto se non si è verificato alcun errore. Una prova PENDING può contenerne uno: l'ultimo tentativo è fallito e l'utente finale può riprovare. DEPOSIT_MISMATCH, DEPOSIT_STALE, TXID_REUSED e REVIEW_REJECTED chiudono la prova come REJECTED. SIGNATURE_INVALID: la firma non corrisponde al wallet e alla challenge. SIGNATURE_UNSUPPORTED_SCHEME: il wallet ha firmato in un formato non verificato da Didit. DEPOSIT_NOT_FOUND, DEPOSIT_UNCONFIRMED, DEPOSIT_LOOKUP_FAILED: il deposito di prova non è leggibile o non è ancora confermato; Didit continua a verificarlo fino alla chiusura della finestra di prova. DEPOSIT_MISMATCH: la transazione non invia l'importo previsto dal wallet all'indirizzo di deposito. DEPOSIT_STALE: la transazione è antecedente alla challenge. TXID_REUSED: la transazione ha già dimostrato la titolarità di un altro wallet. CHAIN_UNSUPPORTED: il metodo non è disponibile su questa blockchain. WINDOW_EXPIRED: la finestra di prova si è chiusa. OWNERSHIP_CHANGED: il titolare del wallet è cambiato, oppure il wallet è stato eliminato dalla tua rubrica, dopo la generazione della sessione del widget. METHOD_SWITCHED: l'utente finale ha scelto un altro metodo prima di completare questo. REVIEW_REJECTED: il tuo revisore ha rifiutato lo screenshot. ABANDONED: la sessione del widget è scaduta prima che l'utente finale terminasse." }, "TravelRuleWidgetProofError": { "type": "object", "properties": { "detail": { "type": "string", "description": "Messaggio di facile lettura in inglese." }, "code": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "Motivo leggibile dalla macchina, che consente a un client di mostrare il proprio messaggio tradotto." }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ], "description": "Presente quando la prova è chiusa: REJECTED dal deposito appena inviato (400), oppure REJECTED o EXPIRED quando viene inviata un'evidenza a una prova già chiusa (409)." }, "proof_id": { "type": "string", "format": "uuid", "description": "Presente con status: la prova chiusa." }, "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ], "description": "Presente con status: il metodo della prova chiusa." }, "max_attempts": { "type": "integer", "description": "Presente con status: prove del wallet rifiutate consentite da questa sessione." }, "attempts_used": { "type": "integer", "description": "Presente con status: prove rifiutate finora." }, "attempts_remaining": { "type": "integer", "description": "Presente con status: quando è 0, l'avvio di un'altra prova restituisce 409 e crei una nuova sessione del widget." } } }, "TravelRuleWidgetProofCreate": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ], "description": "Il metodo di prova scelto dall'utente finale. Deve essere uno dei allowed_methods del contesto." }, "wallet_address": { "type": "string", "maxLength": 128, "description": "Assume come valore predefinito il wallet_address della sessione. Deve corrispondere al wallet del trasferimento quando la sessione è collegata a un trasferimento." }, "chain": { "type": "string", "maxLength": 32, "description": "Assume come valore predefinito la rete della sessione." } } }, "TravelRuleWidgetProofVerifyResult": { "type": "object", "properties": { "proof_id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ] }, "is_ownership_verified": { "type": "boolean", "description": "Presente quando la prova è VERIFIED: la titolarità della voce della rubrica è ora verificata." }, "transfer_status": { "type": "string", "nullable": true, "description": "Presente quando la prova è VERIFIED: lo stato del trasferimento collegato, null se assente." }, "detail": { "type": "string", "description": "Presente mentre la prova rimane PENDING: uno screenshot inviato in attesa di revisione, o un deposito di prova non ancora confermato." }, "code": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "Presente su un deposito di prova in sospeso: il motivo per cui non è ancora confermato." } } }, "TravelRuleWalletProofReview": { "type": "object", "properties": { "proof_id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "SCREENSHOT" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ] }, "wallet_address": { "type": "string" }, "chain": { "type": "string", "description": "Identificatore canonico della rete blockchain, ad es. ETH, BTC, SOL, TRX." }, "holder_name": { "type": "string" }, "is_ownership_verified": { "type": "boolean", "description": "Indica se la voce della rubrica ha la titolarità verificata, tramite questa prova o un'altra." }, "transaction_id": { "type": "string", "format": "uuid", "nullable": true, "description": "La transazione per il cui trasferimento Travel Rule è stata generata la sessione del widget. Null per una sessione generata senza transaction_id." }, "file_name": { "type": "string", "nullable": true }, "content_type": { "type": "string", "nullable": true }, "screenshot_url": { "type": "string", "nullable": true, "description": "Link a tempo allo screenshot caricato. Elenca nuovamente la coda per ottenere un link aggiornato." }, "attempts": { "type": "integer", "description": "Quanti file l'utente finale ha caricato per questa prova." }, "failure_reason": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "REVIEW_REJECTED dopo un rifiuto, OWNERSHIP_CHANGED quando il wallet ha cambiato titolare o è stato eliminato prima di una decisione. Vuoto altrimenti." }, "method_chosen_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora in cui l'utente finale ha scelto il metodo dello screenshot." }, "decided_at": { "type": "string", "format": "date-time", "nullable": true }, "decided_by": { "type": "string", "description": "Chi ha chiuso la prova: review: per un revisore della console, review per una decisione tramite chiave API, widget o sweeper quando Didit l'ha chiusa automaticamente. Vuoto finché è PENDING." }, "review_note": { "type": "string", "description": "La nota inviata con la decisione. Vuota se assente." }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleWalletProofDecision": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "note": { "type": "string", "maxLength": 512, "description": "Opzionale. Conservato con la prova e restituito come review_note." } } }, "DigitalIdWalletApiWalletDigitalCredentialsRequest": { "type": "object", "properties": { "protocol": { "type": "string", "description": "openid4vp-v1-signed." }, "request": { "type": "object", "additionalProperties": {}, "description": "Passalo così com'è: navigator.credentials.get({digital: request}) nel browser, oppure JSON.stringify(request) come requestJson di GetDigitalCredentialOption su Android. Firmato da Didit per la tua applicazione." } }, "required": [ "protocol", "request" ] }, "DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest": { "type": "object", "description": "Avvia una verifica Google Wallet (USA, GBR, BRA, SGP, TWN).", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "Il tuo riferimento per questa verifica (es. il tuo ID utente). Restituito nei risultati e nei webhook." }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "Oggetto JSON opzionale memorizzato con la verifica e restituito nei risultati e nei webhook." }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "Solo per applicazioni sandbox: l'esito simulato - 'wallet_cancelled', 'wallet_timeout' o 'wallet_provider_error'; qualsiasi altro scenario (o nessuno) viene verificato. Rifiutato sulle applicazioni in produzione. Il catalogo completo è disponibile su GET /v1/sandbox/scenarios/." }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartCountryEnum" } ], "description": "Paese ISO 3166-1 alpha-3 dell'identità Google Wallet.\n\n* `USA` - USA\n* `GBR` - GBR\n* `BRA` - BRA\n* `SGP` - SGP\n* `TWN` - TWN" }, "origin": { "type": "string", "minLength": 1, "description": "Dove la tua pagina o app effettuerà la richiesta al wallet: l'origine https della tua pagina (il relativo host deve essere presente in allowed_return_hosts dell'applicazione o corrispondere al suo dominio white label), ad es. https://app.example.com, oppure android:apk-key-hash:. Il wallet rifiuta la richiesta in qualsiasi altra posizione.", "maxLength": 256 } }, "required": [ "country", "origin" ] }, "DigitalIdWalletApiGoogleWalletWalletVerificationStartCountryEnum": { "enum": [ "USA", "GBR", "BRA", "SGP", "TWN" ], "type": "string", "description": "* `USA` - USA\n* `GBR` - GBR\n* `BRA` - BRA\n* `SGP` - SGP\n* `TWN` - TWN" }, "DigitalIdWalletApiWalletDigitalCredentialResponseRequest": { "type": "object", "description": "Cosa ha risposto il wallet alla tua pagina o app, per una verifica ``request_digital_credential``.", "properties": { "response": { "type": "object", "additionalProperties": {}, "description": "Esattamente ciò che il wallet ha restituito: {protocol, data} di DigitalCredential da navigator.credentials.get, o il credentialJson analizzato di DigitalCredential di Android. Crittografato per Didit; non modificarlo." } }, "required": [ "response" ] }, "SessionFilesExport": { "type": "object", "description": "Uno ZIP con tutti i file di una sessione, in qualità originale.", "required": [ "export_id", "session_id", "status", "file_count", "size_bytes", "download_url", "expires_at", "error", "created_at", "completed_at" ], "properties": { "export_id": { "type": "string", "format": "uuid", "description": "ID dell'esportazione. Passalo a `GET /v3/session/{sessionId}/files-export/{exportId}/`." }, "session_id": { "type": "string", "format": "uuid", "description": "La sessione da cui provengono i file." }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "READY", "FAILED", "EXPIRED" ], "description": "`PENDING` e `PROCESSING` durante la preparazione dello ZIP, `READY` non appena può essere scaricato, `FAILED` quando non è stato possibile prepararlo (richiedi una nuova esportazione), `EXPIRED` una volta che lo ZIP è stato eliminato." }, "file_count": { "type": "integer", "nullable": true, "description": "File presenti nel file ZIP. Impostato solo quando `status` è `READY`." }, "size_bytes": { "type": "integer", "format": "int64", "nullable": true, "description": "Dimensione dello ZIP in byte. Impostata solo mentre `status` è `READY`." }, "download_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL firmato dello ZIP, valido per un breve periodo di tempo. Impostato solo mentre `status` è `READY`; leggi nuovamente l'esportazione per ottenerne uno nuovo." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora di eliminazione del file ZIP, 24 ore dopo essere stato pronto. Impostato solo mentre `status` è `READY`." }, "error": { "type": "string", "nullable": true, "description": "Il motivo per cui l'esportazione è fallita, quando `status` è `FAILED`." }, "created_at": { "type": "string", "format": "date-time", "description": "Data e ora della richiesta di esportazione." }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e ora in cui il file ZIP era pronto o in cui l'esportazione non è riuscita." } } }, "TransactionRuleSuggestionsCreatedEvent": { "description": "Un'esecuzione di suggerimento regole per le transazioni ha proposto nuove modifiche alle regole per la tua applicazione. Inviato quando le impostazioni dei suggerimenti sulle regole hanno le notifiche webhook attive. Non è presente alcuno `status` di primo livello.", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "transaction_rule_suggestions.created" ], "description": "Sempre `transaction_rule_suggestions.created`." }, "run_id": { "type": "string", "format": "uuid", "description": "L'esecuzione dei suggerimenti che ha prodotto i nuovi suggerimenti." }, "open_count": { "type": "integer", "description": "Numero di suggerimenti ancora aperti dopo questa esecuzione, inclusi quelli nuovi." }, "suggestions": { "type": "array", "description": "I suggerimenti creati da questa esecuzione.", "items": { "type": "object", "required": [ "suggestion_id", "kind", "title", "rule_id", "expected_impact" ], "properties": { "suggestion_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "ADD", "TWEAK", "DISABLE" ], "description": "`ADD` propone una nuova regola, `TWEAK` ne modifica una esistente, `DISABLE` ne disattiva una." }, "title": { "type": "string" }, "rule_id": { "type": "string", "format": "uuid", "nullable": true, "description": "La regola a cui si applica un suggerimento `TWEAK` o `DISABLE`; `null` per `ADD`." }, "expected_impact": { "type": "object", "additionalProperties": true, "description": "Cosa farebbe la modifica, così come viene mostrata dal suggerimento nella Console." } } } } }, "required": [ "webhook_type", "run_id", "open_count", "suggestions" ] } ] }, "GeolocationCheck": { "type": "object", "description": "Un risultato di verifica della posizione, il tentativo accettato di un nodo del workflow. Misurazione, incertezza e autenticità sono chiavi distinte, pertanto una rilevazione precisa non attestata viene interpretata diversamente da una imprecisa attestata.", "properties": { "node_id": { "type": "string", "nullable": true, "description": "Nodo del workflow che ha generato questo risultato, così che un workflow con due passaggi di verifica della posizione rimanga leggibile." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato a livello di funzionalità di questo passaggio di verifica della posizione, risolto a partire dai relativi avvisi. Indipendente dallo `status` della sessione." }, "outcome": { "type": "string", "nullable": true, "description": "Cosa è successo in questo tentativo.", "enum": [ "verified", "low_accuracy", "accuracy_undetermined", "stale", "approximate", "denied", "restricted", "unavailable", "timeout", "mock_detected", "outside_geofence", "in_blocked_area", "anonymizer_detected", "skipped", "replay_rejected", "unsupported_client", null ] }, "permission": { "type": "string", "nullable": true, "description": "Cosa ha concesso il sistema operativo o il browser. `not_requested` indica che il passaggio utilizza esclusivamente la posizione IP della connessione, pertanto alla persona non viene mai richiesta un'autorizzazione.", "enum": [ "granted_precise", "granted_approximate", "denied", "restricted", "unavailable", "timeout", "dismissed", "not_requested", null ] }, "latitude": { "type": "number", "nullable": true, "description": "Latitudine WGS84 del punto rilevato. `null` in assenza di rilevamento.", "format": "double" }, "longitude": { "type": "number", "nullable": true, "description": "Longitudine WGS84 del punto rilevato. `null` in assenza di rilevamento.", "format": "double" }, "accuracy_m": { "type": "number", "nullable": true, "description": "Raggio di incertezza in metri, al livello di affidabilità indicato in `accuracy_confidence`.", "format": "double" }, "accuracy_confidence": { "type": "string", "nullable": true, "description": "Livello di affidabilità assegnato dalla piattaforma a `accuracy_m`: `p95` (browser), `p68` (Android) o `unspecified` (iOS).", "enum": [ "p95", "p68", "unspecified", null ] }, "measured_at": { "type": "string", "nullable": true, "description": "Data e ora in cui il dispositivo ha acquisito la correzione, in base al proprio orologio.", "format": "date-time" }, "age_seconds": { "type": "integer", "nullable": true, "description": "Secondi trascorsi tra il rilevamento della posizione da parte del dispositivo e la ricezione da parte di Didit." }, "source": { "type": "string", "nullable": true, "description": "Da dove proviene il fix, se indicato dalla piattaforma. `ip` indica che la posizione corrisponde a quella dell'IP della connessione.", "enum": [ "gps", "fused", "network", "wifi", "cell", "browser", "unknown", "ip", null ] }, "platform": { "type": "string", "nullable": true, "description": "Il client che ha generato la correzione.", "enum": [ "web", "ios", "android", "react_native", "flutter", null ] }, "sdk_version": { "type": "string", "nullable": true, "description": "Versione dell'SDK che ha prodotto la correzione." }, "is_mock": { "type": "boolean", "nullable": true, "description": "`true` quando il dispositivo indica che la posizione rilevata proviene da un provider di geolocalizzazione fittizia o da un software di simulazione. `null` quando la piattaforma non lo segnala (i browser non sono in grado di determinarlo); `null` non equivale a `false`." }, "produced_by_accessory": { "type": "boolean", "nullable": true, "description": "Solo iOS: `true` quando il fix proviene da un accessorio esterno. `null` altrove." }, "integrity": { "type": "string", "enum": [ "attested", "not_attested", "failed", "unsupported", "not_determined" ], "description": "Indica se l'attestazione del dispositivo supporta il fix. `unsupported` è quanto segnalato dai browser, poiché il web non dispone di un meccanismo di attestazione; non costituisce un errore." }, "country_code": { "type": "string", "nullable": true, "description": "Paese ISO 3166-1 alpha-2 in cui si trova la posizione rilevata." }, "region_code": { "type": "string", "nullable": true, "description": "Suddivisione ISO 3166-2 in cui si trova il rilevamento." }, "city": { "type": "string", "nullable": true, "description": "Centro abitato più vicino, un'etichetta per i revisori." }, "geofence": { "type": "object", "description": "Risultato delle regole su paese e area geografica del passaggio.", "properties": { "enabled": { "type": "boolean", "description": "Indica se il passaggio applica una regola su paese o area geografica." }, "result": { "type": "string", "nullable": true, "description": "La posizione rispetto alle regole. `undetermined` significa che il cerchio di accuratezza si trova a cavallo del confine o che la posizione non è stata risolta in alcun paese; non costituisce una prova di trovarsi all'esterno.", "enum": [ "inside", "outside", "undetermined", null ] } } }, "inside_geofence": { "type": "boolean", "nullable": true, "description": "`true` quando `geofence.result` è `inside`, `false` quando è `outside`, `null` altrimenti." }, "geofence_basis": { "type": "string", "nullable": true, "description": "Da quale posizione è stato valutato il risultato dell'area: la posizione rilevata dal `device` o la posizione `ip` della connessione.", "enum": [ "device", "ip", null ] }, "inside_areas": { "type": "array", "items": { "type": "string" }, "description": "ID delle aree consentite configurate in cui si trova la posizione." }, "blocked_areas": { "type": "array", "items": { "type": "string" }, "description": "ID delle aree bloccate configurate in cui si trova la posizione." }, "position_source": { "type": "string", "nullable": true, "description": "Da dove il passaggio rileva la posizione, come configurato: il dispositivo confrontato con la posizione IP, solo il dispositivo o solo la posizione IP.", "enum": [ "device_and_ip", "device_only", "ip_only", null ] }, "anonymizers": { "type": "object", "nullable": true, "description": "Come appaiono la connessione e il dispositivo, ciascuno impostato su `true`, `false` o `null` quando la sorgente non è in grado di determinarlo.", "properties": { "vpn": { "type": "boolean", "nullable": true }, "proxy": { "type": "boolean", "nullable": true }, "tor": { "type": "boolean", "nullable": true }, "spoofing": { "type": "boolean", "nullable": true }, "emulator": { "type": "boolean", "nullable": true } } }, "ip_distance_km": { "type": "number", "nullable": true, "description": "Distanza dalla posizione IP della sessione dopo aver sottratto entrambi i raggi di incertezza; `0` quando si sovrappongono.", "format": "double" }, "ip_distance_uncertainty_km": { "type": "number", "nullable": true, "description": "Raggio combinato sottratto: il raggio della posizione IP più l'accuratezza di questa posizione.", "format": "double" }, "ip_consistent": { "type": "boolean", "nullable": true, "description": "Indica se `ip_distance_km` rientra nella distanza configurata nel passaggio. `null` quando una delle due posizioni è sconosciuta." }, "document_distance_km": { "type": "number", "nullable": true, "description": "Distanza dall'indirizzo geocodificato sul documento d'identità o sulla prova di residenza. `null` quando non è presente alcun indirizzo registrato.", "format": "double" }, "travel_excused": { "type": "boolean", "nullable": true, "description": "Indica se la tolleranza di spostamento del passaggio ha giustificato la distanza dall'indirizzo. `null` se la tolleranza è disattivata." }, "consecutive_mismatches": { "type": "integer", "nullable": true, "description": "Al tentativo finale: questo controllo più le precedenti mancate corrispondenze consecutive della stessa persona." }, "attempts": { "type": "integer", "description": "Numero di questo tentativo all'interno del nodo, a partire da 1." }, "consent": { "type": "object", "nullable": true, "description": "Il consenso fornito dalla persona prima del prompt di sistema, registrato con la versione del testo e la lingua visualizzate.", "properties": { "accepted_at": { "type": "string", "format": "date-time" }, "version": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACEMATCH", "PROOF_OF_ADDRESS", "PHONE", "EMAIL", "AML", "LOCATION", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "GEOLOCATION", "SIGNATURE" ], "description": "La funzionalità che ha generato questo avviso. Il valore identifica il blocco della funzionalità a cui appartiene l'avviso. L'array degli avvisi di ciascun modulo utilizza in genere il valore corrispondente al proprio modulo (es. `PHONE` all'interno di `phone_verifications[].warnings`), ma l'enum riportato sopra fa fede per tutti gli avvisi delle funzionalità presenti nel payload della decisione." }, "risk": { "type": "string" }, "additional_data": { "type": "object", "nullable": true }, "log_type": { "type": "string" }, "short_description": { "type": "string" }, "long_description": { "type": "string" }, "node_id": { "type": "string", "description": "L'ID del nodo del grafo del workflow che ha generato questo avviso" } } }, "description": "Avvisi generati da questo passaggio di verifica della posizione, con `feature` impostato su `GEOLOCATION`. I codici di avviso iniziano con `LOCATION_`." } } }, "GeolocationAttempt": { "type": "object", "description": "Un tentativo di un passaggio di verifica della posizione: le stesse chiavi di `geolocation_checks[]` tranne `warnings`, più il momento in cui Didit lo ha ricevuto.", "properties": { "node_id": { "type": "string", "nullable": true, "description": "Nodo del workflow che ha generato questo risultato, così che un workflow con due passaggi di verifica della posizione rimanga leggibile." }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "Stato a livello di funzionalità di questo passaggio di verifica della posizione, risolto a partire dai relativi avvisi. Indipendente dallo `status` della sessione." }, "outcome": { "type": "string", "nullable": true, "description": "Cosa è successo in questo tentativo.", "enum": [ "verified", "low_accuracy", "accuracy_undetermined", "stale", "approximate", "denied", "restricted", "unavailable", "timeout", "mock_detected", "outside_geofence", "in_blocked_area", "anonymizer_detected", "skipped", "replay_rejected", "unsupported_client", null ] }, "permission": { "type": "string", "nullable": true, "description": "Cosa ha concesso il sistema operativo o il browser. `not_requested` indica che il passaggio utilizza esclusivamente la posizione IP della connessione, pertanto alla persona non viene mai richiesta un'autorizzazione.", "enum": [ "granted_precise", "granted_approximate", "denied", "restricted", "unavailable", "timeout", "dismissed", "not_requested", null ] }, "latitude": { "type": "number", "nullable": true, "description": "Latitudine WGS84 del punto rilevato. `null` in assenza di rilevamento.", "format": "double" }, "longitude": { "type": "number", "nullable": true, "description": "Longitudine WGS84 del punto rilevato. `null` in assenza di rilevamento.", "format": "double" }, "accuracy_m": { "type": "number", "nullable": true, "description": "Raggio di incertezza in metri, al livello di affidabilità indicato in `accuracy_confidence`.", "format": "double" }, "accuracy_confidence": { "type": "string", "nullable": true, "description": "Livello di affidabilità assegnato dalla piattaforma a `accuracy_m`: `p95` (browser), `p68` (Android) o `unspecified` (iOS).", "enum": [ "p95", "p68", "unspecified", null ] }, "measured_at": { "type": "string", "nullable": true, "description": "Data e ora in cui il dispositivo ha acquisito la correzione, in base al proprio orologio.", "format": "date-time" }, "age_seconds": { "type": "integer", "nullable": true, "description": "Secondi trascorsi tra il rilevamento della posizione da parte del dispositivo e la ricezione da parte di Didit." }, "source": { "type": "string", "nullable": true, "description": "Da dove proviene il fix, se indicato dalla piattaforma. `ip` indica che la posizione corrisponde a quella dell'IP della connessione.", "enum": [ "gps", "fused", "network", "wifi", "cell", "browser", "unknown", "ip", null ] }, "platform": { "type": "string", "nullable": true, "description": "Il client che ha generato la correzione.", "enum": [ "web", "ios", "android", "react_native", "flutter", null ] }, "sdk_version": { "type": "string", "nullable": true, "description": "Versione dell'SDK che ha prodotto la correzione." }, "is_mock": { "type": "boolean", "nullable": true, "description": "`true` quando il dispositivo indica che la posizione rilevata proviene da un provider di geolocalizzazione fittizia o da un software di simulazione. `null` quando la piattaforma non lo segnala (i browser non sono in grado di determinarlo); `null` non equivale a `false`." }, "produced_by_accessory": { "type": "boolean", "nullable": true, "description": "Solo iOS: `true` quando il fix proviene da un accessorio esterno. `null` altrove." }, "integrity": { "type": "string", "enum": [ "attested", "not_attested", "failed", "unsupported", "not_determined" ], "description": "Indica se l'attestazione del dispositivo supporta il fix. `unsupported` è quanto segnalato dai browser, poiché il web non dispone di un meccanismo di attestazione; non costituisce un errore." }, "country_code": { "type": "string", "nullable": true, "description": "Paese ISO 3166-1 alpha-2 in cui si trova la posizione rilevata." }, "region_code": { "type": "string", "nullable": true, "description": "Suddivisione ISO 3166-2 in cui si trova il rilevamento." }, "city": { "type": "string", "nullable": true, "description": "Centro abitato più vicino, un'etichetta per i revisori." }, "geofence": { "type": "object", "description": "Risultato delle regole su paese e area geografica del passaggio.", "properties": { "enabled": { "type": "boolean", "description": "Indica se il passaggio applica una regola su paese o area geografica." }, "result": { "type": "string", "nullable": true, "description": "La posizione rispetto alle regole. `undetermined` significa che il cerchio di accuratezza si trova a cavallo del confine o che la posizione non è stata risolta in alcun paese; non costituisce una prova di trovarsi all'esterno.", "enum": [ "inside", "outside", "undetermined", null ] } } }, "inside_geofence": { "type": "boolean", "nullable": true, "description": "`true` quando `geofence.result` è `inside`, `false` quando è `outside`, `null` altrimenti." }, "geofence_basis": { "type": "string", "nullable": true, "description": "Da quale posizione è stato valutato il risultato dell'area: la posizione rilevata dal `device` o la posizione `ip` della connessione.", "enum": [ "device", "ip", null ] }, "inside_areas": { "type": "array", "items": { "type": "string" }, "description": "ID delle aree consentite configurate in cui si trova la posizione." }, "blocked_areas": { "type": "array", "items": { "type": "string" }, "description": "ID delle aree bloccate configurate in cui si trova la posizione." }, "position_source": { "type": "string", "nullable": true, "description": "Da dove il passaggio rileva la posizione, come configurato: il dispositivo confrontato con la posizione IP, solo il dispositivo o solo la posizione IP.", "enum": [ "device_and_ip", "device_only", "ip_only", null ] }, "anonymizers": { "type": "object", "nullable": true, "description": "Come appaiono la connessione e il dispositivo, ciascuno impostato su `true`, `false` o `null` quando la sorgente non è in grado di determinarlo.", "properties": { "vpn": { "type": "boolean", "nullable": true }, "proxy": { "type": "boolean", "nullable": true }, "tor": { "type": "boolean", "nullable": true }, "spoofing": { "type": "boolean", "nullable": true }, "emulator": { "type": "boolean", "nullable": true } } }, "ip_distance_km": { "type": "number", "nullable": true, "description": "Distanza dalla posizione IP della sessione dopo aver sottratto entrambi i raggi di incertezza; `0` quando si sovrappongono.", "format": "double" }, "ip_distance_uncertainty_km": { "type": "number", "nullable": true, "description": "Raggio combinato sottratto: il raggio della posizione IP più l'accuratezza di questa posizione.", "format": "double" }, "ip_consistent": { "type": "boolean", "nullable": true, "description": "Indica se `ip_distance_km` rientra nella distanza configurata nel passaggio. `null` quando una delle due posizioni è sconosciuta." }, "document_distance_km": { "type": "number", "nullable": true, "description": "Distanza dall'indirizzo geocodificato sul documento d'identità o sulla prova di residenza. `null` quando non è presente alcun indirizzo registrato.", "format": "double" }, "travel_excused": { "type": "boolean", "nullable": true, "description": "Indica se la tolleranza di spostamento del passaggio ha giustificato la distanza dall'indirizzo. `null` se la tolleranza è disattivata." }, "consecutive_mismatches": { "type": "integer", "nullable": true, "description": "Al tentativo finale: questo controllo più le precedenti mancate corrispondenze consecutive della stessa persona." }, "attempts": { "type": "integer", "description": "Numero di questo tentativo all'interno del nodo, a partire da 1." }, "consent": { "type": "object", "nullable": true, "description": "Il consenso fornito dalla persona prima del prompt di sistema, registrato con la versione del testo e la lingua visualizzate.", "properties": { "accepted_at": { "type": "string", "format": "date-time" }, "version": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true } } }, "received_at": { "type": "string", "nullable": true, "description": "Quando Didit ha ricevuto il tentativo.", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "BiometricRetention": { "type": "object", "description": "Quando i dati biometrici acquisiti durante questa sessione vengono eliminati.", "required": [ "jurisdictions", "deletes_at" ], "properties": { "jurisdictions": { "type": "array", "items": { "type": "string" }, "description": "Codici degli stati degli Stati Uniti le cui norme biometriche stabiliscono un limite di cancellazione per questa persona (`US` se lo stato è sconosciuto). Vuoto se non si applica alcuno stato." }, "deletes_at": { "type": "string", "format": "date-time", "nullable": true, "description": "La data in cui i dati biometrici live (immagini del volto e modelli biometrici) di questa sessione vengono eliminati, in base all'impostazione di conservazione della tua applicazione e, ove applicabile, al limite legale per la giurisdizione della persona. `null` quando non è ancora applicabile alcuna data." } } }, "TravelRuleManualMatchRequest": { "type": "object", "required": [ "transaction_id" ], "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "Il `transaction_id` del messaggio Travel Rule ricevuto (una riga con `kind: message`)." } } }, "TravelRuleManualMatchResponse": { "type": "object", "required": [ "deposit", "message" ], "properties": { "deposit": { "$ref": "#/components/schemas/TravelRuleTransferRow" }, "message": { "$ref": "#/components/schemas/TravelRuleTransferRow" } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys." }, "TransactionTokenAuth": { "type": "apiKey", "in": "header", "name": "X-Transaction-Token", "description": "Token con ambito limitato di breve durata generato dal tuo backend tramite POST /v3/transactions/sdk-token/. Utilizzato dagli SDK Didit sugli endpoint /v1/transactions/ esposti ai dispositivi." }, "SessionTokenAuth": { "type": "apiKey", "in": "header", "name": "Session-Token", "description": "Token di breve durata restituito nel campo `session_token` di POST /v3/session/. Utilizzato dal flusso di verifica ospitato (e dalle UI sandbox personalizzate) per chiamare endpoint con ambito di sessione per conto dell'utente in fase di verifica, senza la tua chiave API lato server." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Il token di accesso client-credentials dell'applicazione." }, "CaseRequestToken": { "type": "apiKey", "in": "header", "name": "X-Case-Request-Token", "description": "Credenziale specifica della richiesta proveniente dal link sicuro. Concede l'accesso esclusivamente a questa richiesta." } }, "responses": { "Unauthorized": { "description": "Non autorizzato", "content": { "application/json": { "examples": { "Invalid API Key": { "summary": "Chiave API non valida", "value": { "detail": "Invalid API Key." } } } } } }, "Forbidden": { "description": "Vietato", "content": { "application/json": { "examples": { "No Permission": { "summary": "Nessuna autorizzazione", "value": { "detail": "You do not have permission to perform this action." } }, "Not Enough Credits": { "summary": "Crediti insufficienti", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "NotFound": { "description": "Non trovato", "content": { "application/json": { "examples": { "Not Found": { "summary": "Non trovato", "value": { "detail": "Resource not found." } } } } } }, "PhoneRiskValidationError": { "description": "Validazione della richiesta non riuscita.", "content": { "application/json": { "examples": { "Missing phone number": { "summary": "Numero di telefono mancante", "value": { "phone_number": [ "This field is required." ] } }, "Invalid phone number": { "summary": "Numero di telefono non valido", "value": { "phone_number": [ "Invalid phone number provided." ] } }, "Invalid signal IP": { "summary": "IP di segnale non valido", "value": { "signals": { "ip": [ "Enter a valid IPv4 or IPv6 address." ] } } } } } } }, "EmailRiskValidationError": { "description": "Validazione della richiesta non riuscita.", "content": { "application/json": { "examples": { "Missing email": { "summary": "Email mancante", "value": { "email": [ "This field is required." ] } }, "Invalid email": { "summary": "Email non valida", "value": { "email": [ "Enter a valid email address." ] } }, "Invalid country hint": { "summary": "Suggerimento per il paese non valido", "value": { "country_code": [ "Ensure this field has no more than 3 characters." ] } } } } } }, "IPRiskValidationError": { "description": "Validazione della richiesta non riuscita.", "content": { "application/json": { "examples": { "Missing IP address": { "summary": "Indirizzo IP mancante", "value": { "ip_address": [ "This field is required." ] } }, "Invalid IP address": { "summary": "Indirizzo IP non valido", "value": { "ip_address": [ "Enter a valid IPv4 or IPv6 address." ] } }, "Country hint too long": { "summary": "Suggerimento del paese troppo lungo", "value": { "claimed_country": [ "Ensure this field has no more than 3 characters." ] } } } } } }, "RiskPermissionDenied": { "description": "La chiave API è mancante o non valida, oppure l'organizzazione non può coprire la ricerca in tempo reale. Questa API non restituisce mai `401`.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "Nessuna intestazione `x-api-key`, oppure la chiave non è valida o è stata revocata", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "Il saldo dell'organizzazione non è sufficiente per coprire il prezzo della ricerca", "value": { "error": "You don't have enough credits to perform this request." } } } } } }, "RateLimitedWrite": { "description": "Il limite di scrittura condiviso di 300 richieste al minuto per chiave API è stato superato. Rispetta `Retry-After` prima di riprovare.", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } }, "AddressValidationValidationError": { "description": "Il corpo della richiesta non è valido: `country` mancante o sconosciuto, nessun indirizzo, oppure sia `address` che i campi strutturati presenti contemporaneamente.", "content": { "application/json": { "examples": { "Unknown country": { "value": { "country": [ "Use an ISO 3166-1 alpha-2 or alpha-3 country code, e.g. 'US' or 'USA'." ] } }, "No address": { "value": { "address": [ "Send the address: 'address' on one line, or the structured fields with 'address_line_1'." ] } }, "Both shapes": { "value": { "address": [ "Send either 'address' or the structured fields (address_line_1, ...), not both." ] } } } } } }, "AddressValidationPermissionDenied": { "description": "La chiave API è mancante o non valida, una chiave con ambito limitato non dispone dell'accesso in scrittura a `sessions`, oppure l'organizzazione non può coprire la validazione. Questa API non restituisce mai `401`.", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me", "code": "insufficient_credits" } } } } } }, "DocumentProcessingBusy": { "description": "Al momento sono in fase di elaborazione troppi documenti, pertanto questo caricamento non è stato elaborato: non è stato memorizzato nulla e non è stato utilizzato alcun tentativo. Invia nuovamente lo stesso file dopo il numero di secondi indicato in `Retry-After`. Basa la logica su `code`, non sul testo del messaggio.", "headers": { "Retry-After": { "description": "Secondi da attendere prima di inviare nuovamente la stessa richiesta.", "schema": { "type": "integer", "example": 10 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "document_processing_busy" ] } } }, "example": { "detail": "We are busy processing documents. Please try again in a moment.", "code": "document_processing_busy" } } } } }, "parameters": { "WebhookSignature": { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 esadecimale in caratteri minuscoli, calcolato usando il segreto della destinazione come chiave, dell'esatto corpo grezzo della richiesta." }, "WebhookSignatureV2": { "name": "X-Signature-V2", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 esadecimale in lettere minuscole, calcolato usando il segreto della destinazione come chiave, del JSON canonico del corpo (chiavi ordinate, nessuno spazio vuoto, caratteri non ASCII senza caratteri di escape). Consigliato, poiché sopravvive ai middleware che ricodificano il corpo." }, "WebhookSignatureSimple": { "name": "X-Signature-Simple", "in": "header", "required": true, "deprecated": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 esadecimale in lettere minuscole, calcolato usando il segreto della destinazione come chiave, di `{timestamp}:{session_id}:{status}:{webhook_type}` (campi mancanti come stringhe vuote). Copre solo l'involucro, mai il payload." }, "WebhookTimestamp": { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Ora Unix in secondi, uguale al `timestamp` del corpo. Rifiuta le consegne più vecchie di qualche minuto." } } }, "x-webhooks": { "status.updated": { "post": { "summary": "Stato della sessione modificato", "description": "Una sessione di verifica ha modificato lo stato. `decision` viene inviata solo per `Approved`, `Declined`, `In Review` e `Abandoned`; ha la forma di `GET /v3/session/{sessionId}/decision/` per le destinazioni sulla versione 3 del webhook (quella predefinita), e la forma ridotta precedente per le destinazioni di versione 1 o 2. Le sessioni aziendali ricevono sempre la decisione aziendale di versione 3.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "data.updated": { "post": { "summary": "Dati della sessione modificati", "description": "I dati di una sessione di verifica sono cambiati senza una modifica di stato, ad esempio dopo una modifica durante la revisione manuale, l'override di un passaggio o un nuovo screening del monitoraggio continuo. `decision` viene inviato solo per `Approved`, `Declined`, `In Review` e `Abandoned`; ha la forma di `GET /v3/session/{sessionId}/decision/` per le destinazioni con webhook versione 3 (predefinita), e la forma ridotta precedente per le destinazioni con versione 1 o 2. Le sessioni aziendali ricevono sempre la decisione aziendale della versione 3.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDataUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "user.status.updated": { "post": { "summary": "Stato dell'utente modificato", "description": "Un utente ha modificato lo stato. Non viene inviato quando l'utente viene creato.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "user.data.updated": { "post": { "summary": "Dati utente modificati", "description": "I campi di un utente sono cambiati. Non viene inviato quando l'utente viene creato. Un singolo salvataggio può produrre sia un evento di stato sia un evento di dati.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDataUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "business.status.updated": { "post": { "summary": "Stato dell'azienda modificato", "description": "Un'azienda ha cambiato stato. Non viene inviato al momento della creazione dell'azienda.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "business.data.updated": { "post": { "summary": "Dati aziendali modificati", "description": "I campi di un'azienda sono cambiati. Non viene inviato quando l'azienda viene creata. Un singolo salvataggio può produrre sia un evento di stato sia un evento di dati.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDataUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "transaction.created": { "post": { "summary": "Transazione creata", "description": "Una transazione è stata creata e sottoposta a screening. Inviato solo per le applicazioni in produzione.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCreatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "transaction.status.updated": { "post": { "summary": "Stato della transazione modificato", "description": "Una transazione ha cambiato stato, in seguito a una regola, a una revisione o a un'azione dell'utente finale. Inviato solo per le applicazioni in produzione.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "travel_rule.status.updated": { "post": { "summary": "Stato Travel Rule modificato", "description": "Uno scambio Travel Rule ha cambiato stato. Inviato per ogni transizione fino a `FINISHED`, `CANCELLED` o `EXPIRED` inclusi, mai dopo. Inviato per le applicazioni di produzione e, per gli scambi Travel Rule, anche per le applicazioni sandbox (`environment: sandbox`). Non è presente alcuno `status` di primo livello.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "workflow.compliance_changed": { "post": { "summary": "Conformità del workflow modificata", "description": "Lo stato di compliance di un workflow pubblicato è cambiato dopo una rivalutazione. Un evento per workflow. Non è presente alcuno `status` di primo livello.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowComplianceChangedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "kyb.registry_search.resolved": { "post": { "summary": "Ricerca dell'azienda risolta (callback non firmato)", "description": "Corpo del callback inviato all'URL specificato in `webhook_url` di `POST /v3/kyb/search/` una volta risolta la ricerca nel registro. Non è firmato: la richiesta contiene `X-Didit-Unsigned-Callback: true` e nessuna delle intestazioni di firma, pertanto confermalo verificando che `request_id` corrisponda a una ricerca avviata da te. Utilizza `event_type`, non `webhook_type`.", "tags": [ "Webhook" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistrySearchResolvedCallback" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } }, "transaction_rule_suggestions.created": { "post": { "summary": "Suggerimenti per regole di transazione creati", "description": "Un'esecuzione di suggerimento regole per le transazioni ha proposto nuove modifiche alle regole per la tua applicazione. Inviato quando le impostazioni dei suggerimenti sulle regole hanno le notifiche webhook attive. Non è presente alcuno `status` di primo livello.", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleSuggestionsCreatedEvent" } } } }, "responses": { "2XX": { "description": "Qualsiasi risposta 2xx conferma la consegna. Per le altre risposte e i timeout vengono effettuati nuovi tentativi; vedi https://docs.didit.me/integration/webhooks." } } } } } }