> ## 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.

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

> A Didit enriquece cada transação com contexto de IP: país, ASN, VPN, Tor, data center e operadora. 1,000 por mês inclusos, depois $0.001 cada.

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:

1. Você envia `POST /v3/transactions/` com `subject.device_context.network_context.ip_address` (ou o IP do dispositivo de qualquer parte).
2. A Didit consulta o IP em um cache em memória (TTL de 24 horas).
3. Se o IP não estiver em cache, consulta a tabela compartilhada de enriquecimento de IP (atualização de cerca de 30 dias).
4. Se os dados estiverem desatualizados ou ausentes, resolve o IP pelo pipeline de enriquecimento da Didit, com failover entre vários provedores.
5. 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](https://docs.didit.me/pt-br/transaction-monitoring/rules.md). 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`:

```json theme={null}
"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](https://docs.didit.me/pt-br/transaction-monitoring/response-schema.md#device) 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

> [card] [Regras](https://docs.didit.me/pt-br/transaction-monitoring/rules.md)
>
> Use campos enriquecidos em condições.

> [card] [Biblioteca de regras](https://docs.didit.me/pt-br/transaction-monitoring/rules-library.md)
>
> Regras predefinidas baseadas em IP.

> [card] [Esquema de resposta](https://docs.didit.me/pt-br/transaction-monitoring/response-schema.md)
>
> Onde o enriquecimento de IP aparece.


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