Vai al contenuto principale
POST
curl
Usa POST /v3/ip/risk/ quando il tuo backend dispone già di un indirizzo IP e ha bisogno di una decisione sul rischio server-to-server. La risposta include geolocalizzazione, proprietà della rete, indicatori VPN/Tor e data center, dati sulle minacce e country_mismatch quando invii un paese dichiarato.

Interpreta la risposta

  • status è In Review quando il paese risolto è in conflitto con claimed_country, oppure quando l’indirizzo è associato a infrastrutture VPN, Tor o data center. Altrimenti è Approved.
  • ip.ip_country_code contiene il codice del paese risolto. Per confrontare i paesi usa ip.country_mismatch invece di confrontare tu stesso le stringhe dei paesi.
  • ip.latitude e ip.longitude sono una geolocalizzazione di rete approssimativa, non la posizione precisa del dispositivo.
  • ip.is_vpn_or_tor, ip.is_data_center, ip.proxy_type e ip.threat contengono gli elementi di rischio della rete.
  • ip.asn_number, ip.asn_organization, ip.connection_type e ip.carrier descrivono la rete a cui appartiene l’indirizzo.
  • request_id è l’ID della sessione API. Salvalo in vendor_data se ti serve correlare il risultato con webhook successivi o con l’attività nella console.
L’arricchimento IP è di tipo best effort. 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. Anche i singoli campi di arricchimento possono essere null quando non sono disponibili.

Informazioni sul dispositivo

L’API IP Risk è un endpoint puramente server-to-server. Il fingerprinting del dispositivo non lo è, perché un backend da solo non può osservare i segnali del browser o del dispositivo. Per le sessioni dei flussi ospitati e degli SDK, Didit espone sulla risposta della sessione i campi del dispositivo già raccolti, tra cui device_fingerprint, i dettagli del dispositivo e del browser, user_agent, i dati grezzi del dispositivo e le corrispondenze tra sessioni diverse.

Comportamento in sandbox

Le chiavi sandbox convalidano la richiesta e restituiscono dati approvati deterministici. Non contattano servizi esterni di analisi, non consumano crediti, non creano una sessione e non contribuiscono a Networks.

Fatturazione

Ogni chiamata all’API IP Risk costa $0.02 al prezzo di listino. Una richiesta in ambiente di produzione è fatturabile nel momento in cui inizia la ricerca.

Autorizzazioni

x-api-key
string
header
obbligatorio

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.

Corpo

application/json
ip_address
string<ip>
obbligatorio

Indirizzo IPv4 o IPv6 a cui assegnare un punteggio.

Esempio:

"8.8.8.8"

claimed_country
string

Paese opzionale ISO 3166-1 alpha-2 o alpha-3 dichiarato dall'utente o dalla sessione. Utilizzato per calcolare country_mismatch.

Maximum string length: 3
Esempio:

"ESP"

user_agent
string

User agent rilevato dal tuo backend. Memorizzato come contesto della richiesta; non fornisce il fingerprinting del dispositivo.

Maximum string length: 512
vendor_data
string

Il tuo riferimento stabile per questa richiesta. Memorizzato nella sessione API e restituito nella risposta.

metadata
object | null

I tuoi metadati JSON non sensibili. Memorizzati nella sessione API e restituiti nella risposta.

Risposta

La valutazione del rischio è completata. Ispeziona status per la decisione; il codice HTTP è sempre 200 per le ricerche completate.

request_id
string<uuid>
obbligatorio

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
enum<string>
obbligatorio

Decisione per questa sessione API: In Review in caso di rischio di rete o mancata corrispondenza del paese, altrimenti Approved.

Opzioni disponibili:
Approved,
In Review
created_at
string<date-time>
obbligatorio

Timestamp di questa risposta.

vendor_data
string | null

Eco del vendor_data inviato, null se non ne hai inviato alcuno.

metadata
object | null

Eco del metadata inviato, null se non ne hai inviato alcuno.

ip
object

Risultato del rischio IP. I singoli campi di arricchimento possono essere null quando la ricerca non ha restituito dati utilizzabili.

Ultima modifica il 7 novembre 2026