> ## 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 fingerprint de dispositivo e risco de IP para KYC

> A análise de dispositivo e IP da Didit detecta dispositivos duplicados, redes de fraude, VPNs, proxies, Tor e divergências de localização no KYC.

A análise de dispositivo e IP da Didit combina fingerprint de dispositivo, recuperação de dispositivos duplicados, inteligência de IP e verificações de geolocalização no fluxo de verificação. Ela ajuda a detectar quando o mesmo dispositivo físico tenta acessar várias contas, mesmo que o usuário troque de sessão, limpe o armazenamento do navegador, abra uma janela anônima ou altere as informações de rede.

Prompt de integração da análise de dispositivo e IP
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Device & IP Analysis (device fingerprinting + IP intelligence + geolocation) into your app.

\# Delivery mode
IP Analysis is **session-only**. The Web/Mobile SDK collects the device fingerprint and IP during the hosted flow — there is no standalone /v3/ip-analysis/ endpoint. It runs automatically on every session and does not require a workflow feature toggle for the basic signal set.

\# Steps
1\. (Optional) In the Business Console enable strict-mode rules for IP / device — e.g. "decline on VPN", "review on duplicate device", "decline on country mismatch with document".
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user — the SDK collects fingerprint + IP in-band.
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

curl (create session):
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-123",
"callback": "https://yourapp.com/post-kyc"
}'
\```

\# Decision surface
The result lands under `ip_analyses[]` on the decision payload (one entry per IP/device collection point in the workflow). Each entry carries the resolved geo, ASN, VPN / proxy / Tor flags, device fingerprint id, duplicate-device matches, and the warnings array.

\# Status enum (per ip_analyses[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.LOCATION)
Heads-up: IP Analysis emits warnings under the **LOCATION** bucket (not "IP_ANALYSIS"). Risk codes include:
VPN_DETECTED, PROXY_DETECTED, TOR_DETECTED, DATACENTER_IP, HIGH_RISK_COUNTRY, LOCATION_MISMATCH_WITH_DOCUMENT, DUPLICATED_DEVICE, POSSIBLE_DUPLICATED_DEVICE, IMPOSSIBLE_TRAVEL, DEVICE_FINGERPRINT_BLOCKLISTED, DEVICE_LINKED_TO_LIVENESS_ATTACK, DEVICE_MODEL_INCONSISTENT.
Full catalogue: /core-technology/ip-analysis/warnings-ip-analysis.

\# Failure modes to handle
\- ip_analyses[] empty — the user blocked the SDK fingerprinting script (privacy extensions, content blockers). Decide whether to fail-closed or fall back to soft signals.
\- VPN_DETECTED / PROXY_DETECTED / TOR_DETECTED — treat per your fraud policy (decline, manual review, additional liveness step).
\- DUPLICATED_DEVICE — same device previously enrolled under a different vendor_data; merge accounts or block per policy.
\- LOCATION_MISMATCH_WITH_DOCUMENT — the IP country does not match the document's issuing country; route to review.

\# See also
\- Canonical schema: /reference/data-models#ip-analysis
\- Per-feature report: /core-technology/ip-analysis/report-ip-analysis
\- Risk catalogue: /core-technology/ip-analysis/warnings-ip-analysis
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

O recurso foi projetado para decisões de prevenção de fraude em que os falsos positivos são caros. As correspondências exatas de dispositivo duplicado usam identificadores persistentes estáveis. As correspondências de dispositivo recuperado usam o vetor de sinais do fingerprint v2 e critérios de alta confiança, de modo que a Didit consegue apontar reutilizações suspeitas sem agrupar usuários sem relação de forma agressiva demais.Na lição da Academy sobre como ler o resultado de uma verificação, o capítulo de 9:49 percorre os sinais de análise de dispositivo e IP.[Análise de dispositivo e IP — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=589\&rel=0\&playsinline=1)![Visão geral da análise de dispositivo e IP da Didit, com geolocalização, fingerprint de dispositivo, inteligência de dispositivo e detecção de VPN](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/ip-analysis.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=a2fbbbdd3d6fed3d759e54f362bf4762)![Diagrama da arquitetura da análise de dispositivo e IP da Didit, que cruza IP, fingerprint do dispositivo e localização declarada](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/ip-analysis-how-it-works.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=3519ad9ad50091a00db5e09d5197fdfe)## Como funcionaA análise de dispositivo e IP é executada automaticamente durante a sessão de verificação e reúne o contexto de dispositivo, rede e identidade em uma única superfície de risco.**1. Captura do fingerprint do dispositivo**O cliente de verificação envia um payload de fingerprint v2, seguro para a privacidade, com sinais do dispositivo web ou móvel:| Ponto de dados | Descrição |
| - | - |
| **ID persistente do dispositivo** | Identificador próprio usado para detectar com exatidão o mesmo dispositivo quando o armazenamento persiste. |
| **Hash composto** | Hash estável de sinais agrupados, usado em verificações determinísticas de duplicidade com proteção contra colisões. |
| **Vetor de sinais** | Atributos do dispositivo e do navegador/aplicativo vetorizados para recuperação de alta confiança. |
| **Contexto da plataforma** | Navegador, SO, aplicativo, hardware, WebGL/canvas, mídia, idioma, fuso horário e sinais de integridade móvel, quando disponíveis. |**2. Análise de IP e da conexão**A Didit enriquece os dados de conexão observados com informações de risco de rede:- Geolocalização do IP por país, região, cidade e coordenadas
- Detecção de VPN, proxy, Tor, data center e rede privada
- Verificações de IP esperado, quando você informa um IP permitido para a sessão
- Verificações da lista de bloqueio de IPs configurada na sua aplicação**3. Correspondência de duplicidade e recuperação**A Didit verifica se a sessão atual corresponde a sessões anteriores de outro `vendor_data`:| Verificação | Finalidade |
| - | - |
| **IP duplicado** | Detecta o mesmo endereço IP em usuários diferentes. |
| **Fingerprint de dispositivo duplicado** | Detecta a reutilização exata da mesma identidade persistente de dispositivo. |
| **Dispositivo recuperado** | Detecta uma recuperação de fingerprint v2 de alta confiança quando o ID persistente mudou. |
| **Proteção contra colisões** | Suprime hashes agrupados de baixa qualidade em vez de agrupar dispositivos sem relação. |**4. Verificações cruzadas de localização**A análise de dispositivo e IP compara o contexto de localização com pontos de referência confiáveis:- País do documento e coordenadas do endereço
- Endereço IP esperado da sessão
- País e cidade do IP
- Distância e direção entre o endereço e a localização do IP**5. Ação e relatórios**Você pode configurar cada categoria de risco de forma independente e consumir o resultado em todas as saídas da Didit:| Canal | Descrição |
| - | - |
| **Ações do fluxo** | Aprovar, revisar ou recusar em caso de VPN/proxy, divergência de localização, IP duplicado, dispositivo duplicado exato e dispositivo recuperado. |
| **Painel** | Revise avisos, sessões correspondentes, informações do dispositivo e detalhes de rede no console da Didit. |
| **Webhooks e APIs** | Receba avisos e correspondências estruturados nos payloads de decisão. |
| **Relatórios** | Exporte os detalhes da análise de dispositivo e IP nos PDFs de verificação. |## Modelo de correspondênciaA análise de dispositivo e IP separa as correspondências exatas das recuperadas para que você ajuste a resposta à fraude com segurança:| Camada | O que detecta | Postura quanto a falsos positivos |
| - | - | - |
| **ID persistente exato** | A mesma identidade de dispositivo própria aparece na sessão de outro usuário. | Sinal mais forte. Usado em `DUPLICATED_DEVICE_FINGERPRINT`. |
| **Hash composto** | O mesmo hash determinístico de dispositivo aparece na sessão de outro usuário. | Protegido por detecção de colisões, para que pools comuns de WebView/navegador sejam suprimidos. |
| **Dispositivo recuperado v2** | O ID persistente mudou, mas sinais ricos do dispositivo correspondem, com alta confiança, a um dispositivo anterior. | Conservadora. Usado em `DEVICE_RECOVERED_HIGH_CONFIDENCE` somente depois de passar por critérios rígidos. |
| **Reutilização de IP** | O mesmo endereço IP aparece em vários usuários. | Contextual. Útil para redes de fraude, mas escritórios, residências e operadoras móveis compartilhados podem ser legítimos. |A correspondência de dispositivos recuperados usa um índice vetorial de recuperação dedicado. Se esse índice não estiver disponível, a Didit continua com as verificações exatas de duplicidade e não emite candidatos de recuperação aproximada.Em **Redes**, a Didit também destaca a reutilização de proxy residencial quando a mesma inteligência de IP que não é de data center aparece em vários usuários ou empresas distintos. O grafo mostra o sinal de risco agregado, a quantidade de sujeitos, o tipo de conexão e o contexto de ISP e ASN; ele não expõe o endereço IP bruto nem os dados de perfil de outra organização.## Padrões de fraude detectadosA análise de dispositivo e IP ajuda a identificar e reduzir:- Múltiplas contas e criação de contas duplicadas
- Tentativas de burlar o KYC usando o mesmo dispositivo com identidades diferentes
- Redes de fraude que coordenam muitas contas a partir de dispositivos ou infraestrutura compartilhados
- Abuso de bônus, de indicações, de promoções e de períodos de teste gratuito
- Cadastro de identidades sintéticas a partir de dispositivos repetidos
- Padrões de cadastro de laranjas
- Risco de tomada de conta a partir de dispositivos desconhecidos ou de alto risco
- Credential stuffing e tentativas de cadastro automatizadas
- Teste de cartões, abuso de chargeback e abuso de reembolso sustentados por padrões repetidos de dispositivo/rede
- Evasão por VPN, proxy, Tor, data center e proxy residencial
- Adulteração de dispositivo, uso de emulador, risco de jailbreak/root e clonagem de aplicativos, quando há sinais móveis disponíveis
- Falsificação de localização e divergências entre documento, IP, fuso horário, operadora e contexto do dispositivo
- Tentativas de verificação conduzidas por bots, com navegadores headless ou clientes automatizados## Principais recursos#### Fingerprint e recuperação de dispositivos- **Detecção exata de dispositivo duplicado**: detecte a mesma identidade de dispositivo em sessões com valores de `vendor_data` diferentes.
- **Recuperação de alta confiança**: recupere relações prováveis de mesmo dispositivo quando mudanças no armazenamento ou a navegação anônima/privada alteram o ID persistente.
- **Proteção contra colisões**: evite agrupar usuários sem relação quando um hash de dispositivo parece comum demais entre muitos IDs persistentes distintos.
- **Cobertura móvel e web**: use sinais do navegador web e sinais nativos do celular, incluindo campos de integridade quando disponíveis.#### Inteligência de IP e de rede- **Detecção de VPN e proxy**: identifique conexões mascaradas ou anonimizadas.
- **Detecção de Tor e data center**: sinalize infraestrutura de alto risco.
- **Reutilização de proxy residencial**: detecte o uso repetido da mesma rede de aparência residencial entre sujeitos distintos, sem expor o valor bruto do IP no grafo de Redes.
- **Listas de bloqueio de IP**: recuse automaticamente quando o IP aparece na lista de bloqueio da sua aplicação.
- **Aplicação de IP esperado**: compare o IP observado com um IP esperado informado na criação da sessão.#### Geolocalização e comparação com o documento- **Detecção de divergência de país**: compare o país do documento com o país do IP.
- **Geofencing**: aceite sessões somente de países permitidos - com exceções por estado/região para países como os Estados Unidos - com base na geolocalização do IP.
- **Verificações de distância do endereço**: compare as coordenadas do endereço do documento com a geolocalização do IP.
- **Contexto de sessões correspondentes**: devolva as sessões correspondentes com detalhes de dispositivo e localização para revisão pela equipe.## Configurar açõesUse as configurações do fluxo para escolher a ação de cada risco. Clientes conservadores costumam definir `recovered_device_action` como `REVIEW` primeiro, inspecionar os avisos de dispositivo recuperado por algumas semanas e só passar para `DECLINE` depois de confirmar o perfil local de falsos positivos.| Configuração | Ação inicial recomendada | Por quê |
| - | - | - |
| `vpn_detection_action` | `REVIEW` ou `DECLINE` | Depende de o uso de VPN ser permitido no seu produto. |
| `ip_mismatch_action` | `REVIEW` | A divergência de localização é um contexto forte, mas pode ser legítima. |
| `duplicated_ip_action` | `REVIEW` | Redes compartilhadas podem gerar falsos positivos. |
| `duplicated_device_action` | `REVIEW` ou `DECLINE` | A reutilização exata do mesmo dispositivo entre usuários é um forte sinal de fraude. |
| `recovered_device_action` | `REVIEW` | A recuperação de alta confiança é intencionalmente conservadora, mas deve ser monitorada antes da recusa automática. |
| `ip_geofencing_action` | `DECLINE` | O geofencing normalmente expressa uma regra jurisdicional rígida; use `REVIEW` se preferir a triagem manual de localizações restritas. |Veja os [avisos da análise de dispositivo e IP](https://docs.didit.me/core-technology/ip-analysis/warnings-ip-analysis.md) para todas as tags de risco e as [configurações de recursos do fluxo](https://docs.didit.me/management-api/workflows/feature-configs.md#device-&-ip-analysis) para os campos da API.


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