> ## 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. # API di verifica della posizione: geofencing e distanza IP > Conferma dove si trova l'utente con Didit: geofencing, distanza IP e documento, posizione del dispositivo e anti-spoofing. $0.05 per controllo. Il passaggio di verifica della posizione di Didit conferma dove si trova una persona mentre si verifica, leggendo la posizione del dispositivo una sola volta (tramite browser o SDK nativo) o la posizione IP della connessione, e confrontandola con le aree consentite e bloccate, con la posizione IP e con l'indirizzo presente sui suoi documenti. Nei workflow e nell'API corrisponde alla funzionalità `GEOLOCATION`, le sue impostazioni sono le chiavi `geolocation_*`, e il suo risultato è `geolocation_checks[]` nella decisione della sessione. ## Quando utilizzarla * Sei in possesso di una licenza valida solo per determinate giurisdizioni (gioco d'azzardo, intermediazione finanziaria, prestiti) e devi dimostrare che la persona si trovava all'interno di una di esse al momento della richiesta. * Devi impedire alle persone di accedere da luoghi bloccati, come una regione soggetta a sanzioni o uno stato non servito. * Vuoi un segnale di frode aggiuntivo: una posizione del dispositivo distante dalla posizione IP o dall'indirizzo sul documento d'identità, una posizione simulata, una VPN o un emulatore. * Non hai bisogno degli spostamenti o della cronologia della persona, ma solo di una singola rilevazione effettuata durante la sessione. ## Come funziona **1. Informativa e autorizzazione** La persona visualizza il motivo per cui la sua posizione è necessaria e apprende che verrà rilevata una sola volta, per questa specifica verifica. Il browser o lo smartphone richiede quindi l'autorizzazione. Didit registra l'informativa accettata (versione, lingua e data/ora) come `consent` nel risultato. **2. Una posizione per tentativo** Il client conserva la lettura migliore finché non risulta sufficientemente accurata o fino allo scadere del timeout per tentativo (il valore predefinito è 20 secondi). Ciascun tentativo include un challenge monouso valido per 5 minuti e associato alla sessione, in modo che un invio intercettato non possa essere riprodotto. **3. Controlli** Didit valuta accuratezza, aggiornamento del dato, autorizzazioni alla posizione approssimativa, segnali di spoofing, aree, distanza dalla posizione IP e dall'indirizzo su un documento, rilevamenti di VPN, proxy, Tor ed emulatori, nonché i controlli precedenti della persona. **4. Esito** Ogni riscontro genera un [avviso](https://docs.didit.me/it/core-technology/location-verification/warnings-location-verification.md) la cui azione configurata (`NO_ACTION`, `REVIEW` o `DECLINE`) imposta lo stato del passaggio. L'azione più restrittiva prevale. ## Origini della posizione Puoi scegliere da dove proviene la posizione con `geolocation_position_source`. | Valore | Cosa accade | | - | - | | `device_and_ip` | La posizione del dispositivo viene confrontata con la posizione IP della connessione da cui è stata inviata. | | `device_only` | Solo la posizione del dispositivo. Non viene mai confrontata con la posizione IP. | | `ip_only` | Alla persona non viene mai richiesta un'autorizzazione. Viene invece valutata la posizione IP della connessione (a livello di città, raggio di 50 km), senza regole di accuratezza, aggiornamento o autorizzazione alla posizione approssimativa. | | non impostato | Viene interrogato il dispositivo e la posizione viene confrontata con la posizione IP rilevata dal passaggio di Analisi dispositivo e IP della sessione. Un nodo che interviene su un rilevamento di VPN, proxy o Tor esegue una ricerca sulla connessione e si comporta come `device_and_ip`. | Su un nodo che interroga il dispositivo, un tentativo senza posizione viene valutato come l'effettivo rifiuto o errore che rappresenta: la posizione IP non la sostituisce mai. ## Valori predefiniti e limiti di configurazione Tutte le chiavi sono facoltative. L'elenco completo è disponibile nel [riferimento alle configurazioni delle funzionalità dei workflow](https://docs.didit.me/it/management-api/workflows/feature-configs.md#verifica-della-posizione). | Impostazione | Predefinito | Limiti | | - | - | - | | `geolocation_max_accuracy_radius_m` | 250 m | Da 10 a 50.000 m | | `geolocation_max_age_seconds` | 120 s | Da 5 a 3.600 s | | `geolocation_timeout_seconds` | 20 s | Da 5 a 120 s | | `geolocation_max_attempts` | 3 | Da 1 a 5 | | `geolocation_accuracy_mode` | `precise` | `precise` o `approximate_allowed` | | `geolocation_low_accuracy_behavior` | `ask_again` | `ask_again` o `fail` | | `geolocation_allow_qr_handoff` | attivo | attivo o disattivo | | `geolocation_allow_skip` | disattivo | attivo o disattivo | | `geolocation_refusal_path` | `retry_then_handoff` | `retry_then_handoff`, `continue_without_location`, `end_session` | | `is_geolocation_geofencing_enabled` | disattivo | attivo o disattivo | | `geolocation_ip_distance_km` | 200 km | 0 o superiore, `null` disattiva il confronto | | `geolocation_document_distance_km` | disattivo | 0 o superiore | | `geolocation_travel_tolerance_enabled` | disattivo | area abituale da 10 a 500 km (predefinito 100), da 1 a 90 giorni (predefinito 14) | | `geolocation_consecutive_mismatch_count` | disattivo | Da 2 a 10 | ### Preset `geolocation_preset` imposta il valore predefinito di ogni azione lasciata non configurata. `licensing` rifiuta una posizione al di fuori delle aree consentite, all'interno di un'area bloccata, dietro una VPN o Tor, oppure su un emulatore, e invia a revisione un proxy. `fraud_screening` applica gli stessi rilevamenti, ma invia a revisione tutto ciò che `licensing` rifiuterebbe. Un'azione impostata esplicitamente prevale sempre. ## Geofencing Attiva `is_geolocation_geofencing_enabled` ed elenca le `geolocation_areas`. Un'area può essere un intero paese, regioni (ISO 3166-2) di un paese, un cerchio (da 1 a 500 km) o un poligono (da 3 a 200 punti). Solo una posizione all'interno di un'area consentita supera il controllo, e un'area bloccata prevale sempre su una consentita. Un elenco può contenere fino a 50 aree e richiede almeno un'area consentita. Didit valuta l'intero cerchio di accuratezza della posizione, non solo il suo centro: * Un cerchio completamente esterno a qualsiasi area consentita restituisce `LOCATION_OUTSIDE_GEOFENCE`. * Un cerchio che attraversa un confine determinante per la risposta restituisce `LOCATION_GEOFENCE_UNDETERMINED`, mai "esterno". * Un cerchio completamente interno a un'area bloccata restituisce `LOCATION_IN_BLOCKED_AREA`, che viene generato in aggiunta al verdetto sull'area consentita. Un paese o una regione termina dove inizia un'altra terraferma, non lungo la linea costiera. Alla persona viene mostrato dove il servizio è disponibile, ma mai quali aree sono bloccate. Le regole di area funzionano anche su un passaggio `ip_only`, valutate a partire dalla posizione IP. La precedente impostazione `geolocation_geofencing_by_country` continua a funzionare, ma non può essere combinata con `geolocation_areas`. ## Controlli della distanza | Controllo | Misurato tra | Impostazione | | - | - | - | | Distanza IP | La posizione del dispositivo e la posizione IP, dopo aver sottratto entrambi i raggi di incertezza (0 indica che si sovrappongono). | `geolocation_ip_distance_km`, `geolocation_ip_distance_action` | | Distanza dal documento | La posizione e un indirizzo, geocodificato in modo approssimativo, quindi si tratta di un segnale debole. | `geolocation_document_distance_km`, `geolocation_document_distance_basis`, `geolocation_document_distance_action` | | Sequenza | I controlli precedenti della persona (con lo stesso `vendor_data`) che risultavano al di fuori di un'area consentita, in un'area bloccata o troppo distanti dall'indirizzo. | `geolocation_consecutive_mismatch_count` | `geolocation_document_distance_basis` seleziona l'indirizzo: `document` (il documento d'identità, poi la prova di residenza), `proof_of_address` o `declared` (`expected_details.address` dalla creazione della sessione). Con `geolocation_travel_tolerance_enabled`, una persona rilevata vicino al proprio indirizzo negli ultimi `geolocation_travel_max_days` giorni non viene segnalata se ora ne è distante. La tolleranza per i viaggi non giustifica mai una VPN, una posizione contraffatta, un'area bloccata o una posizione al di fuori delle aree consentite. ## Segnali di spoofing e integrità * **Provider simulati**: Android e iOS segnalano quando una posizione è simulata anziché misurata. * **Attestazione del dispositivo**: gli SDK nativi possono allegare un'attestazione del dispositivo. Un'attestazione non riuscita comporta sempre un rifiuto. Un'attestazione mancante viene registrata e per impostazione predefinita non comporta alcuna azione. I browser non possono eseguire l'attestazione e vengono registrati come `unsupported`, non come fallimento. * **VPN, proxy e Tor**: rilevati sulla connessione che ha condiviso la posizione. Quando la tua azione per uno di essi non è `NO_ACTION`, alla persona viene chiesto di disattivarlo e riprovare finché rimangono tentativi disponibili. * **Emulatori**: segnalati solo dalle app native. Un emulatore termina il passaggio in quel tentativo poiché nessun nuovo tentativo cambierebbe il dispositivo. * **Replay**: una challenge presentata su un'altra sessione viene sempre rifiutata. ## Risultati Il tentativo accettato del passaggio ha un `outcome`: | Risultato | Significato | | - | - | | `verified` | Una posizione che ha soddisfatto ogni regola. | | `low_accuracy` / `accuracy_undetermined` | Il raggio era superiore al limite, oppure il dispositivo non ne ha segnalato alcuno. | | `stale` | La posizione era più vecchia di `geolocation_max_age_seconds`. | | `approximate` | È stata concessa solo una posizione approssimativa mentre ne era richiesta una precisa. | | `denied` / `restricted` | La persona ha rifiutato, oppure il sistema blocca la posizione. | | `unavailable` / `timeout` | Il dispositivo non ha rilevato alcuna posizione, oppure non l'ha rilevata in tempo. | | `mock_detected` | Il sistema ha segnalato la posizione come simulata. | | `outside_geofence` / `in_blocked_area` | La posizione è al di fuori di ogni area consentita, o all'interno di un'area bloccata. | | `anonymizer_detected` | È stato rilevato un servizio VPN, proxy, nodo di uscita Tor o emulatore e il tuo workflow interviene di conseguenza. | | `skipped` | La persona ha continuato senza condividere la posizione. | | `replay_rejected` | La challenge apparteneva a un'altra sessione. | | `unsupported_client` | L'app o l'SDK è troppo obsoleto per mostrare il passaggio. | Finché rimangono tentativi disponibili, un esito relativo a un raggio eccessivo, una posizione non aggiornata, approssimativa, rifiutata o un problema di area richiede alla persona di riprovare, e solo l'ultimo tentativo genera avvisi. Una posizione simulata, o un emulatore su cui interviene il tuo workflow, termina il passaggio nel tentativo che lo ha segnalato. ## Esperienza dell'utente ### Consenso e autorizzazione Non viene letto nulla prima che la persona accetti l'informativa e risponda alla richiesta del sistema. L'informativa indica che la posizione viene letta una sola volta, per questa verifica, e non costituisce una registrazione dei suoi spostamenti. Una persona che rifiuta viene gestita in base a `geolocation_refusal_path`: * `retry_then_handoff` chiede nuovamente finché rimangono tentativi disponibili e poi propone di continuare su uno smartphone. * `continue_without_location` propone di proseguire senza una posizione e registra il rifiuto come risultato. * `end_session` termina il passaggio e la sessione al primo rifiuto. Richiede che `geolocation_permission_denied_action` sia impostato su `REVIEW` o `DECLINE`, e la sessione non viene mai approvata. Con `geolocation_allow_skip` abilitato, la persona può proseguire senza una posizione in qualsiasi momento, e il passaggio viene valutato in base a `geolocation_unavailable_action`. ### Browser Il flusso ospitato richiede la posizione al browser e mostra una guida passo passo per Chrome e Safari quando la geolocalizzazione è disattivata per il sito. Un browser non è in grado di distinguere un'autorizzazione precisa da una approssimativa, pertanto i risultati web non generano mai `LOCATION_APPROXIMATE_ONLY` e non segnalano mai un provider simulato, un emulatore o un'attestazione. Un computer non può condividere una posizione precisa, quindi il flusso propone un codice QR per continuare la stessa verifica sullo smartphone della persona (`geolocation_allow_qr_handoff`, attivo per impostazione predefinita), e il computer prosegue autonomamente quando lo smartphone termina. Quando incorpori il flusso in un iframe, includi `geolocation` nell'attributo `allow`; vedi [iframe nel contesto](https://docs.didit.me/it/integration/web-sdks/incontext-iframe.md). Una pagina che blocca la policy dei permessi di geolocalizzazione viene considerata come una decisione del sito, non come un rifiuto della persona. ### SDK nativi Gli SDK per iOS e Android richiedono la posizione al sistema operativo e possono allegare l'attestazione del dispositivo e i flag di posizione simulata. Su iOS aggiungi `NSLocationWhenInUseUsageDescription` a `Info.plist`, mentre su Android l'SDK dichiara `ACCESS_FINE_LOCATION` e `ACCESS_COARSE_LOCATION` e richiede l'autorizzazione a runtime solo quando un workflow include questo passaggio. Vedi gli [SDK nativi](https://docs.didit.me/it/integration/native-sdks/overview.md). Un'autorizzazione approssimativa su iOS o Android genera `LOCATION_APPROXIMATE_ONLY` a meno che `geolocation_accuracy_mode` non sia impostato su `approximate_allowed`. Una build dell'app o dell'SDK precedente all'introduzione del passaggio viene chiusa con `unsupported_client` invece di lasciare la sessione bloccata. ## Cosa restituisce la decisione La [decisione della sessione](https://docs.didit.me/it/sessions-api/retrieve-session.md) e il webhook `status.updated` contengono due elenchi: * `geolocation_checks[]`: un elemento per ciascun passaggio Location, contenente il tentativo accettato di tale passaggio, con i relativi `warnings`. * `geolocation_attempts[]`: ogni tentativo di ciascun passaggio Location, dal più vecchio al più recente. Consulta il [report di verifica della posizione](https://docs.didit.me/it/core-technology/location-verification/report-location-verification.md) per ogni campo. Le coordinate, l'accuratezza, la città e il paese sono dati personali dell'utente finale, pertanto gli attributi di risposta di un workflow possono limitare quali campi di `geolocation_checks` vengono restituiti dalla decisione. ## Prezzi La verifica della posizione costa **\$0.05 per verifica** e non fa parte del piano gratuito. Didit addebita il costo una sola volta per ciascun passaggio Location in una sessione, qualunque sia il suo esito, poiché la verifica è stata eseguita e ha restituito una risposta. I nuovi tentativi all'interno dello stesso passaggio sono gratuiti. Un nuovo invio che completa nuovamente il passaggio viene addebitato nuovamente. ## Sandbox Le sessioni sandbox eseguono lo stesso passaggio nello stesso flusso ospitato e il dispositivo o il browser segnala comunque una posizione reale. Le sessioni sandbox non contattano mai il servizio di ricerca IP, pertanto il confronto dell'IP utilizza solo ciò che la sessione già contiene. L'utilizzo viene registrato a un prezzo pari a 0, quindi una sessione sandbox non viene mai addebitata. Non sono previsti input magici per questo passaggio. ## Correlati * [Report di verifica della posizione](https://docs.didit.me/it/core-technology/location-verification/report-location-verification.md) - ogni campo di `geolocation_checks[]` e `geolocation_attempts[]`. * [Avvisi di verifica della posizione](https://docs.didit.me/it/core-technology/location-verification/warnings-location-verification.md) - ogni codice `LOCATION_*` e la relativa azione. * [Configurazioni delle funzionalità del workflow](https://docs.didit.me/it/management-api/workflows/feature-configs.md#verifica-della-posizione) - ogni chiave `geolocation_*`. * [Analisi dispositivo e IP](https://docs.didit.me/it/core-technology/ip-analysis/overview.md) - geolocalizzazione IP e controlli VPN per la sessione. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.