Pular para o conteúdo principal
POST
curl
Use POST /v3/ip/risk/ quando seu backend já tiver um endereço IP e precisar de uma decisão de risco de servidor para servidor. A resposta inclui geolocalização, propriedade da rede, indicadores de VPN/Tor e de data center, dados de ameaças e country_mismatch quando você envia um país declarado.

Interpretar a resposta

  • status é In Review quando o país identificado diverge de claimed_country ou quando o endereço está associado a infraestrutura de VPN, Tor ou data center. Caso contrário, é Approved.
  • ip.ip_country_code contém o código do país identificado. Compare países por meio de ip.country_mismatch em vez de comparar você mesmo as strings brutas de país.
  • ip.latitude e ip.longitude são uma geolocalização aproximada da rede, não uma localização precisa do dispositivo.
  • ip.is_vpn_or_tor, ip.is_data_center, ip.proxy_type e ip.threat trazem evidências de risco de rede.
  • ip.asn_number, ip.asn_organization, ip.connection_type e ip.carrier descrevem a rede à qual o endereço pertence.
  • request_id é o ID da sessão da API. Armazene-o junto com vendor_data se precisar correlacionar o resultado com webhooks posteriores ou com a atividade no console.
O enriquecimento de IP é realizado em regime de melhor esforço. Se nenhuma fonte de enriquecimento retornar dados utilizáveis, o endpoint retorna uma resposta aprovada com ip.ip_address: null, ip.country_mismatch: null e um objeto ip.threat vazio. Campos de enriquecimento individuais também podem ser null quando não estiverem disponíveis.

Inteligência de dispositivo

A API de risco de IP é um endpoint exclusivamente de servidor para servidor. A impressão digital do dispositivo não é um endpoint desse tipo, pois um backend não consegue observar sozinho os sinais do navegador ou do dispositivo. Para sessões do fluxo hospedado e do SDK, a Didit expõe na resposta da sessão os campos de dispositivo já coletados, incluindo device_fingerprint, detalhes do dispositivo e do navegador, user_agent, dados brutos do dispositivo e correspondências entre sessões.

Comportamento no sandbox

As chaves de sandbox validam a requisição e retornam dados determinísticos aprovados. Elas não acessam serviços externos de inteligência, não consomem créditos, não criam uma sessão nem contribuem para as Networks.

Faturamento

As chamadas à API de risco de IP custam $0.02 ao preço de tabela. Uma requisição no ambiente de produção é cobrada assim que a consulta começa.

Autorizações

x-api-key
string
header
obrigatório

Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json
ip_address
string<ip>
obrigatório

Endereço IPv4 ou IPv6 a ser pontuado.

Exemplo:

"8.8.8.8"

claimed_country
string

País opcional em ISO 3166-1 alfa-2 ou alfa-3 declarado pelo usuário ou pela sessão. Usado para calcular country_mismatch.

Maximum string length: 3
Exemplo:

"ESP"

user_agent
string

User agent observado pelo seu backend. Armazenado como contexto da requisição; não fornece fingerprinting de dispositivo.

Maximum string length: 512
vendor_data
string

Sua referência estável para esta requisição. Armazenada na sessão da API e devolvida na resposta.

metadata
object | null

Seus metadados JSON não sensíveis. Armazenados na sessão da API e retornados na resposta.

Resposta

A avaliação de risco foi concluída. Verifique status para ver a decisão; o HTTP é sempre 200 para consultas concluídas.

request_id
string<uuid>
obrigatório

Id da sessão de API criada para esta requisição. Armazene-o com vendor_data se precisar correlacionar o resultado com webhooks posteriores ou com a atividade no console.

status
enum<string>
obrigatório

Decisão desta sessão de API: In Review em caso de risco de rede ou de divergência de país; caso contrário, Approved.

Opções disponíveis:
Approved,
In Review
created_at
string<date-time>
obrigatório

Data e hora desta resposta.

vendor_data
string | null

Eco do vendor_data que você enviou, null quando você não enviou nenhum.

metadata
object | null

Eco do metadata que você enviou, null quando você não enviou nenhum.

ip
object

Resultado de risco do IP. Campos de enriquecimento individuais podem ser null quando a consulta não retornou dados utilizáveis.

Última modificação em 1 de novembro de 2026