> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Arricchimento IP delle transazioni: paese, ASN, VPN

> Didit arricchisce ogni transazione con dati IP: paese, ASN, VPN, Tor, data center e operatore. 1,000 al mese inclusi, poi $0.001 ciascuna.

Ogni transazione che include un indirizzo IP del dispositivo viene arricchita lato server in tempo reale, prima che le regole la valutino. L'arricchimento aggiunge paese, città, flag VPN/Tor/data center, ASN e operatore, tutti disponibili come condizioni delle regole.

## Quando viene eseguito l'arricchimento

Inline durante la creazione della transazione:

1. Invii `POST /v3/transactions/` con `subject.device_context.network_context.ip_address` (o l'IP del dispositivo di qualsiasi parte).
2. Didit cerca l'IP in una cache in memoria (TTL di 24 ore).
3. Se non è in cache, controlla la tabella condivisa di arricchimento IP (freschezza di circa 30 giorni).
4. Se il dato è obsoleto o mancante, risolve l'IP tramite la pipeline di arricchimento di Didit, con failover su più provider.
5. I campi arricchiti vengono scritti nel record della transazione e resi disponibili alle regole.

L'arricchimento è **inline**: viene completato prima che le regole vengano eseguite, ma **non blocca la transazione in caso di errore**. Se l'arricchimento non può essere completato, la transazione procede comunque e l'IP compare semplicemente senza dati di arricchimento.

## Campi arricchiti

| Campo | Descrizione |
| - | - |
| `ip_country` | Nome del paese |
| `ip_country_code` | ISO 3166-1 alpha-2 quando risolto da Didit (un valore inviato da te viene mantenuto così come inviato); le condizioni delle regole normalizzano entrambe le forme |
| `ip_state` | Suddivisione amministrativa (stato, regione) |
| `ip_city` | Nome della città |
| `latitude`, `longitude` | Coordinate geografiche |
| `isp` | Nome del provider di servizi internet |
| `organization` | Nome dell'organizzazione registrante |
| `is_vpn_or_tor` | Booleano: l'IP è un nodo di uscita VPN o Tor noto |
| `is_data_center` | Booleano: l'IP appartiene a un intervallo di hosting/data center |
| `time_zone` | Fuso orario IANA (ad esempio `America/New_York`) |
| `time_zone_offset` | Scostamento rispetto a UTC |
| `asn_number` | Numero di sistema autonomo (ASN) |
| `asn_organization` | Organizzazione registrata dell'ASN |
| `connection_type` | `mobile`, `broadband`, `dialup`, `corporate`, ... |
| `carrier` | Operatore mobile (per gli IP mobili) |
| `proxy_type` | `VPN`, `TOR`, `PUBLIC_PROXY`, oppure null |

## Uso dei campi arricchiti nelle regole

Qualsiasi campo arricchito può essere una [condizione della regola](https://docs.didit.me/it/transaction-monitoring/rules.md). Schemi comuni:

**Giurisdizione ad alto rischio tramite IP**

```
condition: applicant.ip_country_code IN ['IRN', 'PRK', 'SYR']
action: add_score(35), add_tags(['high_risk_ip_country'])
```

**Uso di VPN / Tor**

```
condition: applicant.is_vpn_or_tor == true
action: change_status('IN_REVIEW'), add_tags(['anonymization'])
```

**Data center / origine non residenziale**

```
condition: applicant.is_data_center == true AND amount > 10000
action: add_score(30)
```

**Paese IP ≠ paese KYC**

```
condition: applicant.ip_country_code != applicant.country_code
action: add_score(15), add_tags(['geo_mismatch'])
```

## Livelli di cache

| Livello | TTL | Scopo |
| - | - | - |
| Cache in memoria | 24 ore | Ricerca in meno di un millisecondo per gli IP più richiesti |
| Tabella condivisa di arricchimento IP | circa 30 giorni | Condivisa tra le istanze; meno costosa di una nuova risoluzione |
| Pipeline di arricchimento | n/d | Dati aggiornati quando nessun altro livello li ha |

I riscontri nei primi due livelli non comportano alcun costo aggiuntivo. Le nuove risoluzioni possono essere a consumo: consulta la console di fatturazione.

## Comportamento in caso di errore

* La creazione della transazione **non fallisce mai** a causa del fallimento dell'arricchimento.
* I campi di arricchimento mancanti non corrispondono semplicemente a nessuna condizione delle regole che li referenzia.
* Gli avvisi su arricchimenti bloccati vengono segnalati al tuo team operativo tramite il monitoraggio interno; non hanno alcun impatto visibile ai clienti.

## Filtro di validità

Gli IP non instradabili vengono saltati prima dell'arricchimento:

* Privati (10/8, 172.16/12, 192.168/16)
* Loopback (127/8)
* Link-local (169.254/16)
* Multicast, non specificati

Questo riduce il consumo della quota dei provider ed evita dati di arricchimento privi di senso.

## Ispezione dell'arricchimento per una transazione

**Tramite API.** Non esiste un blocco di arricchimento separato. I campi arricchiti vengono scritti nell'oggetto `device.network_context` della parte, accanto all'`ip_address` che hai inviato, nella voce corrispondente dell'array `parties`:

```json theme={null}
"parties": [
  {
    "role": "APPLICANT",
    "vendor_data": "user-42",
    "device": {
      "network_context": {
        "ip_address": "203.0.113.5",
        "ip_country": "United States",
        "ip_country_code": "US",
        "ip_state": "California",
        "ip_city": "San Francisco",
        "is_vpn_or_tor": false,
        "is_data_center": false,
        "asn_number": 64496,
        "asn_organization": "Example ISP",
        "proxy_type": null
      }
    }
  }
]
```

I campi che hai fornito nella richiesta vengono preservati: l'arricchimento compila solo le chiavi che hai omesso, e le chiavi che il resolver restituisce vuote vengono escluse. Per la struttura completa dell'oggetto `device`, consulta lo [schema della risposta](https://docs.didit.me/it/transaction-monitoring/response-schema.md#device).

**Nella console.** La pagina di dettaglio della transazione mostra l'arricchimento IP nella scheda **IP e dispositivo**, con un marcatore sulla mappa.

## Considerazioni sulla privacy

* Gli IP grezzi vengono memorizzati insieme alla transazione.
* I dati di arricchimento risiedono in una tabella condivisa indicizzata per IP, non per utente.
* La cancellazione secondo il diritto all'oblio rimuove gli IP dalla transazione; la voce di cache condivisa resta, perché non identifica una persona.

## Passaggi successivi

> [card] [Regole](https://docs.didit.me/it/transaction-monitoring/rules.md)
>
> Usa i campi arricchiti nelle condizioni.

> [card] [Libreria di regole](https://docs.didit.me/it/transaction-monitoring/rules-library.md)
>
> Regole predefinite basate sull'IP.

> [card] [Schema della risposta](https://docs.didit.me/it/transaction-monitoring/response-schema.md)
>
> Dove compare l'arricchimento IP.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.