> ## 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 de verificação de localização: geofencing e IP > A Didit confirma onde a pessoa está na verificação: posição do dispositivo, geofencing, distância de IP e documento, spoofing. $0.05 por checagem. A etapa de verificação de localização da Didit confirma onde a pessoa está enquanto faz a verificação. Ela obtém uma vez a posição do dispositivo (navegador ou SDK nativo) ou a localização do IP da conexão e a compara com as áreas permitidas e bloqueadas, com a localização do IP e com o endereço nos documentos da pessoa. Nos fluxos de verificação (workflows) e na API, ela é o recurso `GEOLOCATION`, suas configurações são as chaves `geolocation_*` e seu resultado é `geolocation_checks[]` na decisão da sessão. ## Quando usar * Você tem licença apenas para algumas jurisdições (jogos de azar, corretagem, crédito) e precisa provar que a pessoa estava dentro de uma delas quando fez a solicitação. * Você precisa impedir o acesso de pessoas em locais bloqueados, como uma região sancionada ou um estado que você não atende. * Você quer mais um sinal de fraude: uma posição do dispositivo distante da localização do IP ou do endereço no documento de identidade, uma localização simulada, uma VPN ou um emulador. * Você não precisa dos deslocamentos nem do histórico da pessoa, apenas de uma leitura feita durante a sessão. ## Como funciona **1. Aviso e permissão** A pessoa vê por que a localização dela é necessária e que ela é lida uma única vez, para esta verificação. Em seguida, o navegador ou o celular pede a permissão. A Didit registra o aviso que ela aceitou (versão, idioma e horário) como `consent` no resultado. **2. Uma posição por tentativa** O cliente mantém a melhor leitura até que ela seja precisa o suficiente ou até que o tempo limite por tentativa (padrão de 20 segundos) se esgote. Cada tentativa leva um desafio de uso único, válido por 5 minutos e vinculado à sessão, para que um envio capturado não possa ser reutilizado. **3. Verificações** A Didit avalia a precisão, a atualidade da leitura, as permissões de localização aproximada, os sinais de spoofing, as áreas, a distância até a localização do IP e até um endereço no documento, as constatações de VPN, proxy, Tor e emulador e as verificações anteriores da pessoa. **4. Resultado** Cada constatação gera um [aviso](https://docs.didit.me/pt-br/core-technology/location-verification/warnings-location-verification.md) cuja ação configurada (`NO_ACTION`, `REVIEW` ou `DECLINE`) define o status da etapa. Prevalece a ação mais rigorosa. ## Fontes de posição Você escolhe de onde vem a posição com `geolocation_position_source`. | Valor | O que acontece | | - | - | | `device_and_ip` | A posição do dispositivo é comparada com a localização do IP da conexão pela qual foi enviada. | | `device_only` | Apenas a posição do dispositivo. Ela nunca é comparada com a localização do IP. | | `ip_only` | A pessoa nunca recebe um pedido de permissão. Em vez disso, é avaliada a localização do IP da conexão (em nível de cidade, raio de 50 km), sem nenhuma regra de precisão, de atualidade ou de permissão aproximada. | | não definido | O dispositivo recebe o pedido, e a posição é comparada com a localização do IP observada pela etapa de Análise de dispositivo e IP da sessão. Um nó que age sobre uma constatação de VPN, proxy ou Tor consulta a conexão e se comporta como `device_and_ip`. | Em um nó que solicita a posição ao dispositivo, uma tentativa sem posição é avaliada como a recusa ou falha que representa: a localização do IP nunca a substitui. ## Padrões e limites de configuração Todas as chaves são opcionais. A lista completa está na [referência de configurações de recursos do fluxo](https://docs.didit.me/pt-br/management-api/workflows/feature-configs.md#verificação-de-localização). | Configuração | Padrão | Limites | | - | - | - | | `geolocation_max_accuracy_radius_m` | 250 m | 10 a 50.000 m | | `geolocation_max_age_seconds` | 120 s | 5 a 3.600 s | | `geolocation_timeout_seconds` | 20 s | 5 a 120 s | | `geolocation_max_attempts` | 3 | 1 a 5 | | `geolocation_accuracy_mode` | `precise` | `precise` ou `approximate_allowed` | | `geolocation_low_accuracy_behavior` | `ask_again` | `ask_again` ou `fail` | | `geolocation_allow_qr_handoff` | ativado | ativado ou desativado | | `geolocation_allow_skip` | desativado | ativado ou desativado | | `geolocation_refusal_path` | `retry_then_handoff` | `retry_then_handoff`, `continue_without_location`, `end_session` | | `is_geolocation_geofencing_enabled` | desativado | ativado ou desativado | | `geolocation_ip_distance_km` | 200 km | 0 ou mais; `null` desativa a comparação | | `geolocation_document_distance_km` | desativado | 0 ou mais | | `geolocation_travel_tolerance_enabled` | desativado | área habitual de 10 a 500 km (padrão 100), de 1 a 90 dias (padrão 14) | | `geolocation_consecutive_mismatch_count` | desativado | 2 a 10 | ### Predefinições `geolocation_preset` define o padrão de todas as ações que você não definir. `licensing` recusa uma posição fora das áreas permitidas, dentro de uma área bloqueada, com uma VPN ou Tor, ou em um emulador, e envia para revisão uma posição atrás de um proxy. `fraud_screening` aplica os mesmos critérios, mas envia para revisão tudo o que `licensing` recusaria. Uma ação que você define explicitamente sempre prevalece. ## Geocercas Ative `is_geolocation_geofencing_enabled` e liste as `geolocation_areas`. Uma área pode ser um país inteiro, regiões (ISO 3166-2) de um país, um círculo (de 1 a 500 km) ou um polígono (de 3 a 200 pontos). Só uma posição dentro de uma área permitida é aprovada, e uma área bloqueada sempre prevalece sobre uma permitida. Uma lista comporta até 50 áreas e precisa de pelo menos uma área permitida. A Didit avalia todo o círculo de precisão da posição, não apenas o seu centro: * Um círculo totalmente fora de todas as áreas permitidas gera `LOCATION_OUTSIDE_GEOFENCE`. * Um círculo que cruza uma borda decisiva para a resposta gera `LOCATION_GEOFENCE_UNDETERMINED`, nunca "fora". * Um círculo totalmente dentro de uma área bloqueada gera `LOCATION_IN_BLOCKED_AREA`, além do veredito sobre a área permitida. Um país ou região termina onde começa outra porção de terra, não no seu litoral. A pessoa vê onde o serviço está disponível, mas nunca quais áreas estão bloqueadas. As regras de área também funcionam em uma etapa `ip_only`, avaliadas com base na localização do IP. A configuração mais antiga `geolocation_geofencing_by_country` ainda funciona, mas não pode ser combinada com `geolocation_areas`. ## Verificações de distância | Verificação | Medida entre | Configuração | | - | - | - | | Distância do IP | A posição do dispositivo e a localização do IP, após subtrair os dois raios de incerteza (0 significa que eles se sobrepõem). | `geolocation_ip_distance_km`, `geolocation_ip_distance_action` | | Distância do documento | A posição e um endereço geocodificado de forma aproximada, por isso é um sinal fraco. | `geolocation_document_distance_km`, `geolocation_document_distance_basis`, `geolocation_document_distance_action` | | Sequência | As verificações anteriores da pessoa (mesmo `vendor_data`) que ficaram fora de uma área permitida, em uma área bloqueada ou longe demais do endereço. | `geolocation_consecutive_mismatch_count` | `geolocation_document_distance_basis` define o endereço usado: `document` (o documento de identidade ou, na falta deste, o comprovante de endereço), `proof_of_address` ou `declared` (`expected_details.address` informado na criação da sessão). Com `geolocation_travel_tolerance_enabled`, uma pessoa vista perto do seu endereço nos últimos `geolocation_travel_max_days` dias não é sinalizada por estar longe dele agora. A tolerância a viagens nunca se aplica a uma VPN, uma posição falsificada, uma área bloqueada ou uma posição fora das áreas permitidas. ## Sinais de spoofing e integridade * **Provedores simulados**: o Android e o iOS informam quando uma posição é simulada em vez de medida. * **Atestação do dispositivo**: os SDKs nativos podem anexar um atestado do dispositivo. Uma atestação com falha sempre resulta em recusa. A ausência de atestação é registrada e, por padrão, não gera nenhuma ação. Os navegadores não conseguem fazer a atestação e são registrados como `unsupported`, não como falha. * **VPN, proxy e Tor**: detectados na conexão que compartilhou a localização. Quando a sua ação para um deles não é `NO_ACTION`, a pessoa é solicitada a desativá-lo e verificar novamente enquanto restarem tentativas. * **Emuladores**: informados apenas por aplicativos nativos. Um emulador encerra a etapa nessa tentativa, porque tentar novamente não muda o dispositivo. * **Replay**: um desafio apresentado em outra sessão sempre resulta em recusa. ## Resultados A tentativa aceita da etapa tem um único `outcome`: | Resultado | Significado | | - | - | | `verified` | Uma posição que atendeu a todas as regras. | | `low_accuracy` / `accuracy_undetermined` | O raio era maior que o limite, ou o dispositivo não informou nenhum raio. | | `stale` | A posição era mais antiga que `geolocation_max_age_seconds`. | | `approximate` | Apenas uma posição aproximada foi concedida quando uma posição precisa era exigida. | | `denied` / `restricted` | A pessoa recusou, ou o sistema bloqueia a localização. | | `unavailable` / `timeout` | O dispositivo não encontrou nenhuma posição, ou não a encontrou a tempo. | | `mock_detected` | O sistema informou que a posição é simulada. | | `outside_geofence` / `in_blocked_area` | A posição está fora de todas as áreas permitidas, ou em uma área bloqueada. | | `anonymizer_detected` | Foi detectada uma VPN, um proxy, um nó de saída Tor ou um emulador, e seu fluxo toma medidas com base nisso. | | `skipped` | A pessoa continuou sem compartilhar a localização. | | `replay_rejected` | O desafio pertencia a outra sessão. | | `unsupported_client` | O aplicativo ou o SDK é antigo demais para exibir a etapa. | Enquanto restarem tentativas, um raio maior que o limite, uma posição desatualizada ou aproximada, uma recusa ou uma área bloqueada ou não permitida pede que a pessoa tente novamente, e apenas a última tentativa gera avisos. Uma posição simulada, ou um emulador sobre o qual o seu fluxo age, encerra a etapa na tentativa em que isso foi informado. ## Experiência da pessoa ### Consentimento e permissão Nada é lido antes de a pessoa aceitar o aviso e responder à solicitação do sistema. O aviso informa que a localização é lida uma única vez, para esta verificação, e que não é um registro dos seus deslocamentos. Uma pessoa que recusa é tratada de acordo com `geolocation_refusal_path`: * `retry_then_handoff` pede novamente enquanto restarem tentativas e depois oferece continuar em um celular. * `continue_without_location` oferece seguir sem localização e registra a recusa como resultado. * `end_session` encerra a etapa e a sessão na primeira recusa. Exige que `geolocation_permission_denied_action` seja `REVIEW` ou `DECLINE`, e a sessão nunca é aprovada. Com `geolocation_allow_skip` ativado, a pessoa pode continuar sem localização a qualquer momento, e a etapa é avaliada por `geolocation_unavailable_action`. ### Navegador O fluxo hospedado solicita a posição ao navegador e mostra ajuda passo a passo para Chrome e Safari quando a localização está desativada para o site. Um navegador não consegue distinguir uma permissão precisa de uma aproximada, por isso os resultados na web nunca geram `LOCATION_APPROXIMATE_ONLY`, e ele nunca informa um provedor simulado, um emulador ou um atestado. Um computador não consegue compartilhar uma posição precisa, por isso o fluxo oferece um QR code que continua a mesma verificação no celular da pessoa (`geolocation_allow_qr_handoff`, ativado por padrão), e o computador avança sozinho quando o celular termina. Ao incorporar o fluxo em um iframe, inclua `geolocation` no atributo `allow`; consulte [iframe no contexto](https://docs.didit.me/pt-br/integration/web-sdks/incontext-iframe.md). Uma página que bloqueia a política de permissão de geolocalização é tratada como uma decisão do site, não como uma recusa da pessoa. ### SDKs nativos Os SDKs para iOS e Android fazem a solicitação ao sistema operacional e podem anexar a atestação do dispositivo e indicadores de localização simulada. No iOS, adicione `NSLocationWhenInUseUsageDescription` ao `Info.plist`; no Android, o SDK declara `ACCESS_FINE_LOCATION` e `ACCESS_COARSE_LOCATION` e só faz a solicitação em tempo de execução quando um fluxo tem esta etapa. Consulte os [SDKs nativos](https://docs.didit.me/pt-br/integration/native-sdks/overview.md). Uma permissão aproximada no iOS ou no Android gera `LOCATION_APPROXIMATE_ONLY`, a menos que `geolocation_accuracy_mode` seja `approximate_allowed`. Uma versão do aplicativo ou do SDK anterior à etapa recebe `unsupported_client`, em vez de deixar a sessão travada. ## O que a decisão retorna A [decisão da sessão](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md) e o webhook `status.updated` trazem duas listas: * `geolocation_checks[]`: um item por etapa de localização, com a tentativa aceita dessa etapa e seus `warnings`. * `geolocation_attempts[]`: todas as tentativas de todas as etapas de localização, da mais antiga para a mais recente. Consulte o [relatório de verificação de localização](https://docs.didit.me/pt-br/core-technology/location-verification/report-location-verification.md) para ver todos os campos. As coordenadas, a precisão, a cidade e o país são dados pessoais do usuário final, por isso os atributos de resposta de um fluxo podem restringir quais campos de `geolocation_checks` a sua decisão retorna. ## Preços A verificação de localização custa **\$0.05 por verificação** e não faz parte do plano gratuito. A Didit cobra uma vez por etapa de localização em uma sessão, qualquer que seja o resultado, porque a verificação foi executada e retornou uma resposta. Novas tentativas dentro da mesma etapa são gratuitas. Um reenvio que conclui a etapa novamente é cobrado novamente. ## Sandbox As sessões de sandbox executam a mesma etapa no mesmo fluxo hospedado, e o dispositivo ou o navegador continua informando uma localização real. As sessões de sandbox nunca acessam o serviço de consulta de IP, por isso a comparação de IP usa apenas o que a sessão já contém. O uso é registrado com preço 0, então uma sessão de sandbox nunca é cobrada. Não há entradas mágicas para esta etapa. ## Relacionados * [Relatório de verificação de localização](https://docs.didit.me/pt-br/core-technology/location-verification/report-location-verification.md) - todos os campos de `geolocation_checks[]` e `geolocation_attempts[]`. * [Avisos da verificação de localização](https://docs.didit.me/pt-br/core-technology/location-verification/warnings-location-verification.md) - todos os códigos `LOCATION_*` e a respectiva ação. * [Configurações de recursos do fluxo](https://docs.didit.me/pt-br/management-api/workflows/feature-configs.md#verificação-de-localização) - todas as chaves `geolocation_*`. * [Análise de dispositivo e IP](https://docs.didit.me/pt-br/core-technology/ip-analysis/overview.md) - geolocalização por IP e verificações de VPN da sessão. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.