Report Analisi dispositivo e IP: campi e corrispondenze

Panoramica

L’analisi dispositivo e IP profila ogni sessione in base a geolocalizzazione IP, fingerprint del dispositivo, browser/SO e tipo di rete. Geolocalizzazione, arricchimento del rischio di rete, corrispondenza dei dispositivi e controlli remoti sull’integrità del dispositivo vengono eseguiti in modo asincrono mentre l’utente completa la verifica. Le osservazioni su dispositivo e IP rimangono disponibili mentre l’analisi è in sospeso; i campi di geolocalizzazione possono essere vuoti finché non arrivano i risultati, oppure quando l’indirizzo non è pubblico. Se il tuo workflow utilizza questi controlli per determinare l’esito o scegliere un passaggio successivo, la sessione rimane In Progress finché i risultati richiesti non sono disponibili. Se l’analisi richiesta rimane non disponibile dopo un numero limitato di nuovi tentativi, la sessione passa a In Review per una decisione manuale. Gli errori di arricchimento opzionali non impediscono il completamento, e le decisioni manuali rimangono vincolanti. Fornisce:

Un blocco di geolocalizzazione IP (paese, stato/regione, città, latitudine/longitudine, fuso orario) ricavato dall’IP pubblico.
Flag di rischio di rete — is_vpn_or_tor e is_data_center — per rilevare tentativi di mascheramento (VPN, nodi di uscita Tor, provider di hosting, anonimizzatori).
Calcoli della distanza tra documenti — km in linea d’aria tra la posizione dell’IP, la posizione del documento d’identità e la posizione del documento di prova di residenza.
Corrispondenze tra sessioni — quando lo stesso indirizzo IP o identità del dispositivo compare tra sessioni appartenenti a utenti diversi (raggruppate per vendor_data).
Recupero del fingerprint del dispositivo — un segnale di recupero ad alta affidabilità che collega le sessioni anche dopo che l’utente cancella lo storage, passa alla navigazione in incognito o reinstalla l’app.

Screenshot del report di analisi dispositivo e IP di Didit con geolocalizzazione, fingerprint del dispositivo e flag di rischio

Dove compare nelle risposte API

L’endpoint di decisione restituisce l’analisi dispositivo e IP come array plurale ip_analyses[] in GET /v3/session/{sessionId}/decision/. Le voci sono osservazioni Location deduplicate con chiave basata su (node_id, ip_address, device_fingerprint) — un singolo nodo può produrre più voci quando l’IP o il dispositivo dell’utente cambiano durante la sessione.

GET /v3/session/{sessionId}/decision/
  ──▶ { "ip_analyses": [ { status, node_id, ip_address, ip, id_document, poa_document, warnings, matches, … }, … ] }

La struttura seguente rispecchia lo schema canonico — vedi Modelli di dati.

Schema

Vedi Analisi dispositivo e IP nella guida di riferimento sui Modelli di dati per lo schema canonico.

interface IPAnalysisV3 {
  status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review' | 'Resub Requested';
  node_id: string | null;

  // Device
  device_brand: string | null;
  device_model: string | null;
  browser_family: string | null;
  os_family: string | null;
  platform: 'mobile' | 'tablet' | 'desktop' | null;
  device_fingerprint: string | null;

  // IP geolocation
  ip_country: string | null;
  ip_country_code: string | null;           // ISO 3166-1 alpha-2
  ip_state: string | null;
  ip_city: string | null;
  latitude: number | null;
  longitude: number | null;
  ip_address: string;
  isp: string | null;
  organization: string | null;
  is_vpn_or_tor: boolean;
  is_data_center: boolean;
  time_zone: string | null;
  time_zone_offset: string | null;

  // Distance blocks — each carries its own location + distances to the other two
  ip: {
    location: { latitude: number; longitude: number } | null;
    distance_from_id_document: number | null;   // km
    distance_from_poa_document: number | null;  // km
  };
  id_document: {
    location: { latitude: number; longitude: number } | null;
    distance_from_ip: number | null;
    distance_from_poa_document: number | null;
  };
  poa_document: {
    location: { latitude: number; longitude: number } | null;
    distance_from_ip: number | null;
    distance_from_id_document: number | null;
  };

  warnings: Warning[];          // see Data Models — Warning object

  // Cross-session matches — up to 5 IP matches + 5 device matches
  matches: IPAnalysisMatch[];
}

interface IPAnalysisMatch {
  session_id: string;                       // matching session UUID
  session_number: number;
  vendor_data: string | null;
  verification_date: string | null;         // "YYYY-MM-DDTHH:MM:SSZ"
  match_type: 'ip_address' | 'device_fingerprint';
  match_source: 'ip_address' | 'persistent_id' | 'legacy_fp' | 'recovered_high';
  matched_value: string | null;             // shared IP, device identifier, or recovered device UUID
  status: string;                           // lifecycle status of the matching session
  is_blocklisted: boolean;                  // currently always false
  api_service: string | null;               // standalone API service; null for workflow sessions
  source: 'session';
  device_info: {
    device_brand: string | null;
    device_model: string | null;
    browser_family: string | null;
    os_family: string | null;
    platform: string | null;
    device_fingerprint: string | null;
  };
  location_info: {
    ip_address: string | null;
    ip_country: string | null;
    ip_country_code: string | null;
    ip_state: string | null;
    ip_city: string | null;
    is_vpn_or_tor: boolean;
    is_data_center: boolean;
  };
  confidence: number;                       // 0–1, = 1 - P(false positive)
  match_mode: 'deterministic' | 'probabilistic' | 'co_occurrence';

  // Present only when match_source = 'recovered_high'
  recovery_similarity?: number;             // cosine similarity, 4 decimals
  tls_ja4_corroborated?: boolean;           // TLS JA4 fingerprints of both observations agree
  recovery_gate_reason?: string;            // e.g. 'hardware_root_match'
}

Semantica delle corrispondenze

match_source indica come è stata ottenuta la corrispondenza e confidence attribuisce un punteggio alla probabilità che sia errata (confidence = 1 - P(false positive)):

`match_source`	Significato	`confidence`	`match_mode`
`ip_address`	IP condiviso — compresenza sulla stessa rete, mai una dichiarazione di identità del dispositivo.	`0.0`	`co_occurrence`
`persistent_id`	Identificatore persistente esatto del dispositivo memorizzato.	`1.0`	`deterministic`
`legacy_fp`	Hash del fingerprint del dispositivo `didit-fp-*` legacy.	`0.5`	`probabilistic`
`recovered_high`	Riscontro di recupero approssimativo del fingerprint ad alta affidabilità dopo rigidi controlli vincolanti.	`1.0` quando radicato nell’hardware, altrimenti `< 1.0`, incrementato quando TLS JA4 e paese dell’IP concordano in modo indipendente	`deterministic` o `probabilistic`

I candidati al recupero con minore affidabilità emergono solo come avvisi di rischio — mai in matches[]. Le corrispondenze IP e le corrispondenze di dispositivo sono limitate a un massimo di 5 ciascuna, pertanto l’array contiene al massimo 10 voci.

Valori di stato

Gli stati sono valori FeatureStatusChoices a livello di funzionalità. Ogni avviso attivato corrisponde all’azione configurata per esso sul nodo del workflow; l’azione più severa ha la precedenza.

Valore	Significato
`Not Finished`	Il nodo di analisi IP non è stato completato per questa sessione (predefinito).
`Approved`	Nessun avviso attivato, oppure ogni avviso attivato è configurato su Nessuna azione.
`In Review`	Almeno un avviso attivato è configurato su Revisione (vedi avvisi).
`Declined`	Si è attivato un avviso di blocklist (`IP_ADDRESS_IN_BLOCKLIST` o `DEVICE_FINGERPRINT_IN_BLOCKLIST` — comporta sempre il rifiuto), oppure un avviso configurabile è impostato su Rifiuta per il tuo workflow.
`Resub Requested`	Un revisore ha richiesto il reinvio di questo passaggio.

Le regole di stato personalizzate configurate sul nodo di analisi IP possono modificare ulteriormente lo stato risultante.

Rilevamento di VPN, proxy e Tor

is_vpn_or_tor e is_data_center sono flag booleani indipendenti restituiti per ogni sessione. Quando is_vpn_or_tor è true, Didit genera anche l’avviso PRIVATE_NETWORK_DETECTED in modo che il tuo team possa intervenire tramite la configurazione del workflow. Il traffico proveniente esclusivamente da data center (senza VPN/Tor) imposta is_data_center=true ma non genera automaticamente un avviso — utilizzalo come segnale aggiuntivo nel tuo punteggio.

Esempi

Approvata

{
  "ip_analyses": [
    {
      "status": "Approved",
      "node_id": "ip-1",
      "device_brand": "Apple",
      "device_model": "iPhone",
      "browser_family": "Mobile Safari",
      "os_family": "iOS",
      "platform": "mobile",
      "device_fingerprint": "didit-fp-8d2c7a91f4b3e042",
      "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": "Telefonica",
      "organization": "Telefonica de Espana",
      "is_vpn_or_tor": false,
      "is_data_center": false,
      "time_zone": "Europe/Madrid",
      "time_zone_offset": "+0100",
      "ip": {
        "location": { "latitude": 41.4022, "longitude": 2.1407 },
        "distance_from_id_document": 23.4,
        "distance_from_poa_document": 12.3
      },
      "id_document": {
        "location": { "latitude": 41.2706, "longitude": 1.9770 },
        "distance_from_ip": 23.4,
        "distance_from_poa_document": 18.7
      },
      "poa_document": {
        "location": { "latitude": 41.3128, "longitude": 2.0540 },
        "distance_from_ip": 12.3,
        "distance_from_id_document": 18.7
      },
      "warnings": [],
      "matches": []
    }
  ]
}

Rifiutata — Corrispondenza con la blocklist degli IP + VPN + dispositivo duplicato

{
  "ip_analyses": [
    {
      "status": "Declined",
      "node_id": "ip-1",
      "device_brand": null,
      "device_model": null,
      "browser_family": "Chrome",
      "os_family": "Linux",
      "platform": "desktop",
      "device_fingerprint": "didit-fp-a13c0d22e8b94471",
      "ip_country": "Netherlands",
      "ip_country_code": "NL",
      "ip_state": "North Holland",
      "ip_city": "Amsterdam",
      "latitude": 52.3676,
      "longitude": 4.9041,
      "ip_address": "45.61.20.5",
      "isp": "Example Hosting",
      "organization": "Example Hosting BV",
      "is_vpn_or_tor": true,
      "is_data_center": true,
      "time_zone": "Europe/Amsterdam",
      "time_zone_offset": "+0100",
      "ip": {
        "location": { "latitude": 52.3676, "longitude": 4.9041 },
        "distance_from_id_document": 1834.2,
        "distance_from_poa_document": 1822.5
      },
      "id_document": {
        "location": { "latitude": 40.4168, "longitude": -3.7038 },
        "distance_from_ip": 1834.2,
        "distance_from_poa_document": 14.0
      },
      "poa_document": {
        "location": { "latitude": 40.5070, "longitude": -3.6720 },
        "distance_from_ip": 1822.5,
        "distance_from_id_document": 14.0
      },
      "warnings": [
        {
          "feature": "LOCATION",
          "risk": "IP_ADDRESS_IN_BLOCKLIST",
          "additional_data": { "ip_address": "45.61.20.5" },
          "log_type": "error",
          "short_description": "IP address in blocklist",
          "long_description": "The IP address used for this session was found in the application's IP blocklist, indicating a known suspicious or forbidden origin.",
          "node_id": "ip-1"
        },
        {
          "feature": "LOCATION",
          "risk": "PRIVATE_NETWORK_DETECTED",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Private network (VPN/Tor) detected",
          "long_description": "The system detected that the user tried to use a private network (VPN/TOR) to complete the verification process.",
          "node_id": "ip-1"
        },
        {
          "feature": "LOCATION",
          "risk": "COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP",
          "additional_data": { "document_country_code": "ESP", "ip_country_code": "NLD" },
          "log_type": "warning",
          "short_description": "Document country does not match IP country",
          "long_description": "The country from the document does not match the country from the IP address, suggesting a potential mismatch between the document and the user's location.",
          "node_id": "ip-1"
        },
        {
          "feature": "LOCATION",
          "risk": "DUPLICATED_DEVICE_FINGERPRINT",
          "additional_data": {
            "duplicated_session_id": "11111111-2222-3333-4444-555555555555",
            "duplicated_session_number": 1042,
            "api_service": null,
            "match_source": "persistent_id"
          },
          "log_type": "warning",
          "short_description": "Duplicated device fingerprint from another session",
          "long_description": "The same device fingerprint was detected in another session with a different vendor_data, which may indicate multiple identities verified from the same device.",
          "node_id": "ip-1"
        }
      ],
      "matches": [
        {
          "session_id": "11111111-2222-3333-4444-555555555555",
          "session_number": 1042,
          "vendor_data": "user-other",
          "verification_date": "2026-05-28T14:03:21Z",
          "match_type": "device_fingerprint",
          "match_source": "persistent_id",
          "matched_value": "pid_9f1c2b7a8d3e4f50",
          "status": "Declined",
          "is_blocklisted": false,
          "api_service": null,
          "source": "session",
          "device_info": {
            "device_brand": null,
            "device_model": null,
            "browser_family": "Chrome",
            "os_family": "Linux",
            "platform": "desktop",
            "device_fingerprint": "didit-fp-a13c0d22e8b94471"
          },
          "location_info": {
            "ip_address": "45.61.23.99",
            "ip_country": "Netherlands",
            "ip_country_code": "NL",
            "ip_state": "North Holland",
            "ip_city": "Amsterdam",
            "is_vpn_or_tor": true,
            "is_data_center": true
          },
          "confidence": 1.0,
          "match_mode": "deterministic"
        }
      ]
    }
  ]
}

Correlati

Avvisi dell’analisi dispositivo e IP — tutti i codici di avviso che l’analisi IP può generare
Panoramica dell’analisi dispositivo e IP — cosa misura ciascun blocco
Modelli di dati — Analisi IP — schema canonico
Webhook — status.updated include lo stesso payload dell’analisi IP

Autenticazione

Verifica

Monitoraggio

Piattaforma

Report Analisi dispositivo e IP: campi e corrispondenze

Panoramica

Dove compare nelle risposte API

Schema

Semantica delle corrispondenze

Valori di stato

Rilevamento di VPN, proxy e Tor

Esempi

Approvata

Rifiutata — Corrispondenza con la blocklist degli IP + VPN + dispositivo duplicato

Correlati

​Panoramica

​Dove compare nelle risposte API

​Schema

​Semantica delle corrispondenze

​Valori di stato

​Rilevamento di VPN, proxy e Tor

​Esempi

​Approvata

​Rifiutata — Corrispondenza con la blocklist degli IP + VPN + dispositivo duplicato

​Correlati

Panoramica

Dove compare nelle risposte API

Schema

Semantica delle corrispondenze

Valori di stato

Rilevamento di VPN, proxy e Tor

Esempi

Approvata

Rifiutata — Corrispondenza con la blocklist degli IP + VPN + dispositivo duplicato

Correlati