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

Interpretar a resposta

  • status é In Review quando o país resolvido entra em conflito com claimed_country, ou quando o endereço está associado a infraestrutura de VPN, Tor ou centro de dados. Caso contrário, é Approved.
  • ip.ip_country_code contém o código do país resolvido. Compare os países através de ip.country_mismatch em vez de comparar diretamente as strings de país.
  • ip.latitude e ip.longitude são uma geolocalização aproximada da rede, não a localização precisa de um dispositivo.
  • ip.is_vpn_or_tor, ip.is_data_center, ip.proxy_type e ip.threat contêm dados de risco da rede.
  • ip.asn_number, ip.asn_organization, ip.connection_type e ip.carrier descrevem a rede a que o endereço pertence.
  • request_id é o ID da sessão da API. Guarde-o com vendor_data se precisar de correlacionar o resultado com webhooks posteriores ou com a atividade na consola.
O enriquecimento de IP é efetuado da melhor forma possível. Se nenhuma fonte de enriquecimento devolver dados utilizáveis, o endpoint devolve 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 dispositivos

A API de risco de IP é um endpoint puramente servidor a servidor. A criação de uma impressão digital do dispositivo não funciona dessa forma, porque um backend, por si só, não consegue observar sinais do navegador ou do dispositivo. Nas sessões do fluxo alojado e do SDK, a Didit expõe na resposta da sessão os campos do dispositivo já recolhidos, 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 o pedido e devolvem dados aprovados determinísticos. Não contactam serviços externos de inteligência, não consomem créditos, não criam uma sessão nem contribuem para as Networks.

Faturação

As chamadas à API de risco de IP custam $0.02 ao preço de tabela. Um pedido em produção é faturável assim que a pesquisa é iniciada.

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json
ip_address
string<ip>
obrigatório

Endereço IPv4 ou IPv6 a pontuar.

Exemplo:

"8.8.8.8"

claimed_country
string

País ISO 3166-1 alpha-2 ou alpha-3 opcional declarado pelo utilizador ou pela sessão. Utilizado para calcular country_mismatch.

Maximum string length: 3
Exemplo:

"ESP"

user_agent
string

Agente do utilizador observado pelo seu back-end. Armazenado como contexto do pedido; não fornece a impressão digital do dispositivo.

Maximum string length: 512
vendor_data
string

A sua referência estável para este pedido. Armazenada na sessão da API e refletida na resposta.

metadata
object | null

Os seus metadados JSON não sensíveis. Armazenados na sessão da API e devolvidos na resposta.

Resposta

A avaliação de risco foi concluída. Inspecione status para verificar a decisão; o código HTTP é sempre 200 para pesquisas concluídas.

request_id
string<uuid>
obrigatório

ID da sessão de API criada para este pedido. Guarde-o com vendor_data se precisar de correlacionar o resultado com webhooks posteriores ou atividade na consola.

status
enum<string>
obrigatório

Decisão para esta sessão de API: In Review em caso de risco de rede ou discrepância de país, caso contrário Approved.

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

Carimbo de data/hora desta resposta.

vendor_data
string | null

Eco do vendor_data que enviou, null se não tiver enviado nenhum.

metadata
object | null

Eco do objeto metadata que enviou, null se não tiver enviado nenhum.

ip
object

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

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