Informe de dispositivo e IP: campos y coincidencias

Descripción general

El análisis de dispositivo e IP analiza cada sesión según la geolocalización de la IP, la huella digital del dispositivo, el navegador/sistema operativo y el tipo de red. La geolocalización, el enriquecimiento de información sobre riesgos de red, la comparación de dispositivos y las comprobaciones remotas de integridad del dispositivo se ejecutan de forma asíncrona mientras el usuario completa la verificación. Las observaciones de dispositivo e IP siguen disponibles mientras el análisis está pendiente; los campos de geolocalización pueden estar vacíos hasta que lleguen los resultados, o cuando la dirección no es pública. Si tu flujo de verificación (workflow) usa estas comprobaciones para determinar el resultado o elegir un paso posterior, la sesión permanece en In Progress hasta que los resultados necesarios estén disponibles. Si el análisis necesario sigue sin estar disponible tras un número limitado de reintentos, la sesión pasa a In Review para una decisión manual. Los fallos del enriquecimiento opcional no impiden que la sesión se complete, y las decisiones manuales siguen prevaleciendo. Genera:

Un bloque de geolocalización de la IP (país, estado, ciudad, latitud/longitud, zona horaria) derivado de la IP pública.
Indicadores de riesgo de red (is_vpn_or_tor e is_data_center) para detectar intentos de ocultación (VPN, nodos de salida de Tor, proveedores de hosting, anonimizadores).
Cálculos de distancia entre documentos: los km en línea recta entre la ubicación de la IP, la ubicación del documento de identidad y la ubicación del documento de prueba de domicilio.
Coincidencias entre sesiones: cuando la misma dirección IP o la misma identidad de dispositivo aparece en sesiones de distintos usuarios (agrupados por vendor_data).
Recuperación de la huella digital del dispositivo: una señal de recuperación de alta confianza que vincula sesiones incluso después de que el usuario borre el almacenamiento, cambie entre modos de incógnito o reinstale la aplicación.

Captura de pantalla del informe de análisis de dispositivo e IP de Didit con geolocalización, huella digital del dispositivo e indicadores de riesgo

Dónde aparece en las respuestas de la API

El endpoint de decisión devuelve el análisis de dispositivo e IP en el array plural ip_analyses[] en GET /v3/session/{sessionId}/decision/. Las entradas son observaciones Location sin duplicados, identificadas por (node_id, ip_address, device_fingerprint): un mismo nodo puede generar varias entradas cuando la IP o el dispositivo del usuario cambian a mitad de la sesión.

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

La estructura siguiente refleja el esquema canónico; consulta Modelos de datos.

Esquema

Consulta Análisis de dispositivo e IP en la referencia de modelos de datos para ver el esquema canónico.

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 las coincidencias

match_source indica cómo se obtuvo la coincidencia, y confidence puntúa la probabilidad de que sea errónea (confidence = 1 - P(false positive)):

`match_source`	Significado	`confidence`	`match_mode`
`ip_address`	IP compartida: coubicación en la red, nunca una afirmación sobre la identidad del dispositivo.	`0.0`	`co_occurrence`
`persistent_id`	Identificador persistente del dispositivo almacenado, coincidencia exacta.	`1.0`	`deterministic`
`legacy_fp`	Hash heredado de la huella digital del dispositivo `didit-fp-*`.	`0.5`	`probabilistic`
`recovered_high`	Coincidencia de alta confianza al recuperar de forma aproximada la huella digital tras superar filtros estrictos.	`1.0` cuando está basada en el hardware; en caso contrario `< 1.0`, y aumenta cuando TLS JA4 y el país de la IP coinciden de forma independiente	`deterministic` o `probabilistic`

Los candidatos de recuperación de menor confianza aparecen solo como advertencias de riesgo, nunca en matches[]. Las coincidencias por IP y las coincidencias por dispositivo están limitadas a 5 cada una, por lo que el array contiene como máximo 10 entradas.

Valores de estado

Los estados son valores FeatureStatusChoices a nivel de función. Cada advertencia activada se asigna a la acción configurada para ella en el nodo del flujo; prevalece la acción más estricta.

Valor	Significado
`Not Finished`	El nodo de análisis de IP no se ha completado para esta sesión (valor predeterminado).
`Approved`	No se activó ninguna advertencia, o todas las advertencias activadas están configuradas como Sin acción.
`In Review`	Al menos una advertencia activada está configurada como Revisión (consulta las advertencias).
`Declined`	Se activó una advertencia de lista de bloqueo (`IP_ADDRESS_IN_BLOCKLIST` o `DEVICE_FINGERPRINT_IN_BLOCKLIST`, que siempre provocan un rechazo), o una advertencia configurable está establecida como Rechazar en tu flujo.
`Resub Requested`	Un revisor solicitó que se vuelva a enviar este paso.

Las reglas de estado personalizadas configuradas en el nodo de análisis de IP pueden ajustar aún más el estado resultante.

Detección de VPN, proxy y Tor

is_vpn_or_tor e is_data_center son indicadores booleanos independientes que se devuelven en cada sesión. Cuando is_vpn_or_tor es true, Didit también emite la advertencia PRIVATE_NETWORK_DETECTED para que tu equipo pueda actuar en consecuencia mediante la configuración del flujo. El tráfico que solo procede de centros de datos (sin VPN/Tor) establece is_data_center=true, pero no genera una advertencia automática: úsalo como señal adicional en tu propia puntuación.

Ejemplos

Aprobado

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

Rechazado: coincidencia en la lista de bloqueo de IP + VPN + dispositivo duplicado

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

Relacionado

Advertencias del análisis de dispositivo e IP: todos los códigos de advertencia que puede emitir el análisis de IP
Descripción general del análisis de dispositivo e IP: qué mide cada bloque
Modelos de datos: análisis de IP: esquema canónico
Webhooks: status.updated incluye el mismo payload del análisis de IP

Autenticación

Verificación

Monitorización

Plataforma

Informe de dispositivo e IP: campos y coincidencias

Descripción general

Dónde aparece en las respuestas de la API

Esquema

Semántica de las coincidencias

Valores de estado

Detección de VPN, proxy y Tor

Ejemplos

Aprobado

Rechazado: coincidencia en la lista de bloqueo de IP + VPN + dispositivo duplicado

Relacionado

​Descripción general

​Dónde aparece en las respuestas de la API

​Esquema

​Semántica de las coincidencias

​Valores de estado

​Detección de VPN, proxy y Tor

​Ejemplos

​Aprobado

​Rechazado: coincidencia en la lista de bloqueo de IP + VPN + dispositivo duplicado

​Relacionado

Descripción general

Dónde aparece en las respuestas de la API

Esquema

Semántica de las coincidencias

Valores de estado

Detección de VPN, proxy y Tor

Ejemplos

Aprobado

Rechazado: coincidencia en la lista de bloqueo de IP + VPN + dispositivo duplicado

Relacionado