> ## 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, centro de dados e operadora. 1,000 por mês incluídas, depois $0.001 cada.

Todas as transações que incluam um endereço IP de dispositivo são enriquecidas no lado do servidor, em tempo real, antes de as regras as avaliarem. O enriquecimento acrescenta o país, a cidade, os sinalizadores de VPN/Tor/centro de dados, o ASN e a operadora, todos disponíveis como condições de regras.

## Quando o enriquecimento é executado

Em linha, durante a criação da transação:

1. Submete `POST /v3/transactions/` com `subject.device_context.network_context.ip_address` (ou o endereço IP do dispositivo de qualquer parte).
2. A Didit procura o IP numa cache em memória (TTL de 24 horas).
3. Se não estiver em cache, verifica a tabela partilhada de enriquecimento de IPs (atualidade de cerca de 30 dias).
4. Se estiver desatualizado ou em falta, resolve o IP através do pipeline de enriquecimento da Didit, com failover entre vários fornecedores.
5. Os campos enriquecidos são gravados de volta no registo da transação e ficam disponíveis para as regras.

O enriquecimento é **em linha**: fica concluído 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 prossegue na mesma e o IP surge 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 que submeteu é mantido tal como enviado); as condições das regras normalizam ambas as formas |
| `ip_state` | Subdivisão (estado, região) |
| `ip_city` | Nome da cidade |
| `latitude`, `longitude` | Coordenadas geográficas |
| `isp` | Nome do fornecedor de serviços de Internet |
| `organization` | Nome da organização registada |
| `is_vpn_or_tor` | Booleano: o IP é uma saída conhecida de VPN ou Tor |
| `is_data_center` | Booleano: o IP pertence a um intervalo de alojamento ou centro de dados |
| `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 registada do ASN |
| `connection_type` | `mobile`, `broadband`, `dialup`, `corporate`, ... |
| `carrier` | Operadora móvel (para IPs móveis) |
| `proxy_type` | `VPN`, `TOR`, `PUBLIC_PROXY`, ou null |

## Utilizar campos enriquecidos nas regras

Qualquer um dos campos enriquecidos pode ser uma [condição de regra](https://docs.didit.me/pt/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'])
```

**Utilização de VPN / Tor**

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

**Centro de dados / origem 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 partilhada de enriquecimento de IPs | \~30 dias | Partilhada entre instâncias; mais barata do que voltar a resolver |
| Pipeline de enriquecimento | n/a | Dados atualizados quando nenhuma das outras camadas os tem |

As consultas às duas primeiras camadas não geram custos adicionais. As resoluções novas podem ser cobradas por utilização; consulte a sua consola de faturação.

## Comportamento em caso de falha

* A criação de transações **nunca falha** por o enriquecimento ter falhado.
* Os campos de enriquecimento em falta simplesmente não correspondem a nenhuma condição de regra que os referencie.
* Os alertas sobre enriquecimento parado são comunicados à sua equipa de operações através da monitorização interna, sem impacto para o cliente.

## Filtragem de validade

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

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

Esta filtragem poupa quota dos fornecedores e evita dados de enriquecimento sem sentido.

## Inspecionar o enriquecimento de uma transação

**Via API.** Não existe um bloco de enriquecimento separado. Os campos enriquecidos são gravados no próprio objeto `device.network_context` da parte, junto ao `ip_address` que submeteu, 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 forneceu no pedido são preservados. O enriquecimento preenche apenas as chaves que deixou de fora, e as chaves que o resolvedor devolveu vazias são omitidas. Consulte o [esquema de resposta](https://docs.didit.me/pt/transaction-monitoring/response-schema.md#device) para a estrutura completa de `device`.

**Na consola.** A página de detalhe da transação mostra o enriquecimento de IP no separador **IP e dispositivo**, com um marcador no mapa.

## Considerações de privacidade

* Os IPs em bruto são armazenados com a transação.
* Os dados de enriquecimento residem numa tabela partilhada indexada por IP, e não por utilizador.
* A eliminação ao abrigo do direito ao esquecimento remove os IPs da transação; a entrada partilhada da cache permanece, uma vez que não identifica pessoas.

## Próximos passos

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

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

> [card] [Esquema de resposta](https://docs.didit.me/pt/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.