Anàlisi de dispositiu i IP: informe, camps, coincidències

Visió general

L’anàlisi de dispositiu i IP perfila cada sessió segons la geolocalització de l’adreça IP, la petjada digital del dispositiu, el navegador/SO i el tipus de xarxa. La geolocalització, l’enriquiment de riscos de xarxa, la coincidència de dispositius i les comprovacions remotes d’integritat del dispositiu s’executen de manera asíncrona mentre l’usuari completa la verificació. Les observacions del dispositiu i de la IP continuen estant disponibles mentre l’anàlisi està pendent; els camps de geolocalització poden estar buits fins que arribin els resultats, o quan l’adreça no sigui pública. Si el teu flux de treball utilitza aquestes comprovacions per determinar el resultat o triar un pas posterior, la sessió roman In Progress fins que els resultats requerits estiguin disponibles. Si l’anàlisi requerida no està disponible després d’un nombre limitat de reintents, la sessió passa a In Review per a una decisió manual. Les fallades en l’enriquiment opcional no impedeixen la finalització, i les decisions manuals continuen sent les que prevalen. Genera el següent:

Un bloc de geolocalització d’IP (país, estat, ciutat, latitud/longitud, zona horària) derivat de la IP pública.
Indicadors de risc de xarxa — is_vpn_or_tor i is_data_center — per detectar intents d’emmascarament (VPN, nodes de sortida de Tor, proveïdors d’allotjament, anonimitzadors).
Càlculs de distància creuada entre documents — quilòmetres en línia recta entre la ubicació de l’adreça IP, la ubicació del document d’identitat i la del comprovant de domicili.
Coincidències entre sessions — quan la mateixa adreça IP o identitat de dispositiu apareix en sessions que pertanyen a usuaris diferents (agrupades per vendor_data).
Recuperació de la petjada digital del dispositiu — un senyal de recuperació d’alta confiança que enllaça sessions fins i tot després que l’usuari netegi l’emmagatzematge, canviï de mode d’incògnit o reinstal·li l’aplicació.

Captura de pantalla de l'informe d'anàlisi de dispositiu i IP de Didit amb geolocalització, petjada digital del dispositiu i indicadors de risc

On apareix a les respostes de l’API

L’endpoint de decisió retorna l’anàlisi de dispositiu i IP com a matriu en plural ip_analyses[] a GET /v3/session/{sessionId}/decision/. Les entrades són observacions de Location deduplicades identificades per (node_id, ip_address, device_fingerprint); un sol node pot generar múltiples entrades quan l’adreça IP o el dispositiu de l’usuari canvien a meitat de la sessió.

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

L’estructura següent reflecteix l’esquema canònic; consulta Models de dades.

Esquema

Consulta Anàlisi de dispositiu i IP a la referència de models de dades per veure l’esquema canònic.

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'
}

Semàntica de coincidències

match_source indica com s’ha arribat a la coincidència, i confidence puntua la probabilitat que sigui errònia (confidence = 1 - P(false positive)):

`match_source`	Significat	`confidence`	`match_mode`
`ip_address`	IP compartida: colocalització de xarxa, mai una afirmació d’identitat del dispositiu.	`0.0`	`co_occurrence`
`persistent_id`	Identificador persistent exacte del dispositiu emmagatzemat.	`1.0`	`deterministic`
`legacy_fp`	Hash heretat de la petjada digital del dispositiu `didit-fp-*`.	`0.5`	`probabilistic`
`recovered_high`	Coincidència de recuperació difusa de petjada digital d’alta confiança després de filtres estrictes.	`1.0` quan es basa en el maquinari; en cas contrari `< 1.0`, amb un increment quan TLS JA4 i el país de l’adreça IP coincideixen de manera independent	`deterministic` o `probabilistic`

Els candidats de recuperació amb menor confiança es mostren només com a advertències de risc, mai a matches[]. Les coincidències d’IP i de dispositius estan limitades a 5 cadascuna, de manera que la matriu conté un màxim de 10 entrades.

Valors d’estat

Els estats són valors de FeatureStatusChoices a nivell de funcionalitat. Cada advertència activada s’associa a l’acció configurada per a aquesta al node del flux de treball; l’acció més estricta és la que preval.

Valor	Significat
`Not Finished`	El node d’anàlisi d’IP no ha finalitzat per a aquesta sessió (per defecte).
`Approved`	No s’ha activat cap advertència, o totes les advertències activades estan configurades com a Sense acció.
`In Review`	Com a mínim una advertència activada està configurada com a Revisió (consulta les advertències).
`Declined`	S’ha activat una advertència de llista de bloqueig (`IP_ADDRESS_IN_BLOCKLIST` o `DEVICE_FINGERPRINT_IN_BLOCKLIST`, que sempre rebutgen), o s’ha configurat una advertència com a Rebutjar per al teu flux de treball.
`Resub Requested`	Un revisor ha sol·licitat reenviar aquest pas.

Les regles d’estat personalitzades configurades al node d’anàlisi d’IP poden ajustar encara més l’estat resultant.

Detecció de VPN, proxy i Tor

is_vpn_or_tor i is_data_center són indicadors booleans independents que es retornen per a cada sessió. Quan is_vpn_or_tor és true, Didit també emet l’advertència PRIVATE_NETWORK_DETECTED perquè el teu equip pugui actuar en conseqüència mitjançant la configuració del flux de treball. El trànsit exclusiu de centres de dades (sense VPN/Tor) estableix is_data_center=true però no emet cap advertència automàtica; utilitza-ho com un senyal addicional en la teva pròpia puntuació.

Exemples

Aprovada

{
  "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": []
    }
  ]
}

Rebutjada — Coincidència amb la llista de bloqueig d’IP + VPN + dispositiu duplicat

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

Relacionat

Advertències d’anàlisi de dispositiu i IP — tots els codis d’advertència que pot emetre l’anàlisi d’IP
Visió general de l’anàlisi de dispositiu i IP — què mesura cada bloc
Models de dades — Anàlisi d’IP — esquema canònic
Webhooks — status.updated inclou el mateix payload d’anàlisi d’IP

Autenticació

Verificació

Monitoratge

Plataforma

Anàlisi de dispositiu i IP: informe, camps, coincidències

Visió general

On apareix a les respostes de l’API

Esquema

Semàntica de coincidències

Valors d’estat

Detecció de VPN, proxy i Tor

Exemples

Aprovada

Rebutjada — Coincidència amb la llista de bloqueig d’IP + VPN + dispositiu duplicat

Relacionat

​Visió general

​On apareix a les respostes de l’API

​Esquema

​Semàntica de coincidències

​Valors d’estat

​Detecció de VPN, proxy i Tor

​Exemples

​Aprovada

​Rebutjada — Coincidència amb la llista de bloqueig d’IP + VPN + dispositiu duplicat

​Relacionat

Visió general

On apareix a les respostes de l’API

Esquema

Semàntica de coincidències

Valors d’estat

Detecció de VPN, proxy i Tor

Exemples

Aprovada

Rebutjada — Coincidència amb la llista de bloqueig d’IP + VPN + dispositiu duplicat

Relacionat