Enriquecimento de IP em transações: país, ASN, VPN

Toda transação que inclui o endereço IP de um dispositivo é enriquecida no servidor, em tempo real, antes que as regras a avaliem. O enriquecimento adiciona país, cidade, indicadores de VPN/Tor/data center, ASN e operadora, e todos esses dados ficam disponíveis como condições de regra.

Quando o enriquecimento é executado

Durante a criação da transação:

Você envia POST /v3/transactions/ com subject.device_context.network_context.ip_address (ou o IP do dispositivo de qualquer parte).
A Didit consulta o IP em um cache em memória (TTL de 24 horas).
Se o IP não estiver em cache, consulta a tabela compartilhada de enriquecimento de IP (atualização de cerca de 30 dias).
Se os dados estiverem desatualizados ou ausentes, resolve o IP pelo pipeline de enriquecimento da Didit, com failover entre vários provedores.
Os campos enriquecidos são gravados de volta no registro da transação e ficam disponíveis para as regras.

O enriquecimento é inline, ou seja, termina antes de as regras serem executadas, mas não bloqueia em caso de falha. Se o enriquecimento não puder ser concluído, a transação segue normalmente; o IP apenas aparece sem dados de enriquecimento.

Campos enriquecidos

Campo	Descrição
`ip_country`	Nome do país
`ip_country_code`	ISO 3166-1 alpha-2 quando resolvido pela Didit (um valor enviado por você é mantido como foi enviado); as condições de regra normalizam as duas formas
`ip_state`	Subdivisão (estado, região)
`ip_city`	Nome da cidade
`latitude`, `longitude`	Coordenadas geográficas
`isp`	Nome do provedor de serviços de internet
`organization`	Nome da organização que registrou o IP
`is_vpn_or_tor`	Booleano: o IP é uma VPN conhecida ou um nó de saída Tor conhecido
`is_data_center`	Booleano: o IP pertence a uma faixa de hospedagem/data center
`time_zone`	Fuso horário IANA (por exemplo, `America/New_York`)
`time_zone_offset`	Diferença em relação ao UTC
`asn_number`	Número do sistema autônomo (ASN)
`asn_organization`	Organização registrada do ASN
`connection_type`	`mobile`, `broadband`, `dialup`, `corporate`, …
`carrier`	Operadora móvel (para IPs móveis)
`proxy_type`	`VPN`, `TOR`, `PUBLIC_PROXY` ou nulo

Como usar campos enriquecidos em regras

Qualquer um dos campos enriquecidos pode ser uma condição de regra. Padrões comuns: Jurisdição de alto risco pelo IP

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

Uso de VPN / Tor

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

Origem em data center / não residencial

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

País do IP ≠ país do KYC

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

Camadas de cache

Camada	TTL	Finalidade
Cache em memória	24 horas	Consulta em menos de um milissegundo para IPs frequentes
Tabela compartilhada de enriquecimento de IP	~30 dias	Compartilhada entre instâncias; mais barata do que resolver novamente
Pipeline de enriquecimento	n/a	Dados atualizados quando nenhuma outra camada os tem

Acertos nas duas primeiras camadas não geram nenhum custo adicional. Novas resoluções podem ser tarifadas; consulte seu console de faturamento.

Comportamento em caso de falha

A criação da transação nunca falha por causa de uma falha no enriquecimento.
Campos de enriquecimento ausentes simplesmente não atendem a nenhuma condição de regra que faça referência a eles.
Alertas sobre enriquecimento travado são encaminhados à sua equipe de operações pelo monitoramento interno; não há impacto para o cliente.

Filtragem de validade

IPs não roteáveis são ignorados antes do enriquecimento:

Privados (10/8, 172.16/12, 192.168/16)
Loopback local (127/8)
Link-local local (169.254/16)
Multicast, não especificados

Isso economiza a cota dos provedores e evita dados de enriquecimento sem sentido.

Como inspecionar o enriquecimento de uma transação

Pela API. Não existe um bloco de enriquecimento separado. Os campos enriquecidos são gravados no próprio objeto device.network_context da parte, ao lado do ip_address que você enviou, na entrada correspondente do array parties:

"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
      }
    }
  }
]

Os campos que você forneceu na requisição são preservados; o enriquecimento só preenche as chaves que você deixou de fora, e as chaves que o resolvedor retornou vazias são omitidas. Consulte o esquema de resposta para ver a estrutura completa de device. No console. A página de detalhes da transação mostra o enriquecimento de IP na aba IP & Device, com um marcador no mapa.

Considerações de privacidade

Os IPs brutos são armazenados com a transação.
Os dados de enriquecimento ficam em uma tabela compartilhada indexada por IP, e não por usuário.
A exclusão por direito ao esquecimento remove os IPs da transação; a entrada no cache compartilhado permanece (não contém informações de identificação pessoal).

Próximos passos

Regras

Use campos enriquecidos em condições.

Biblioteca de regras

Regras predefinidas baseadas em IP.

Esquema de resposta

Onde o enriquecimento de IP aparece.

Primeiros passos

Recursos

Referência

Console

Enriquecimento de IP em transações: país, ASN, VPN

Quando o enriquecimento é executado

Campos enriquecidos

Como usar campos enriquecidos em regras

Camadas de cache

Comportamento em caso de falha

Filtragem de validade

Como inspecionar o enriquecimento de uma transação

Considerações de privacidade

Próximos passos

Regras

Biblioteca de regras

Esquema de resposta

​Quando o enriquecimento é executado

​Campos enriquecidos

​Como usar campos enriquecidos em regras

​Camadas de cache

​Comportamento em caso de falha

​Filtragem de validade

​Como inspecionar o enriquecimento de uma transação

​Considerações de privacidade

​Próximos passos

Regras

Biblioteca de regras

Esquema de resposta

Quando o enriquecimento é executado

Campos enriquecidos

Como usar campos enriquecidos em regras

Camadas de cache

Comportamento em caso de falha

Filtragem de validade

Como inspecionar o enriquecimento de uma transação

Considerações de privacidade

Próximos passos