跳转到主要内容
POST
curl
使用 POST /v3/ip/risk/,当您的后端已经拿到 IP 地址并需要进行服务器到服务器的风险判定时使用。 响应包括地理位置、网络归属、VPN/Tor 与数据中心标记、威胁数据,以及在您提交声明国家时返回的 country_mismatch。

解读响应

  • 当解析出的国家与 claimed_country 冲突,或该地址与 VPN、Tor 或数据中心基础设施相关联时,status 为 In Review。否则为 Approved。
  • ip.ip_country_code 包含解析出的国家代码。请通过 ip.country_mismatch 比较国家,而不是自行比较原始国家字符串。
  • ip.latitude 和 ip.longitude 是近似的网络地理位置,而非精确的设备位置。
  • ip.is_vpn_or_tor、ip.is_data_center、ip.proxy_type 和 ip.threat 承载网络风险证据。
  • ip.asn_number、ip.asn_organization、ip.connection_type 和 ip.carrier 描述该地址所属的网络。
  • request_id 是 API 会话 ID。如果您需要将结果与后续 Webhook 或控制台活动关联,请将其与 vendor_data 一起存储。
IP 信息富化采用尽力而为的方式。如果没有任何富化数据源返回可用数据,该 endpoint 将返回已通过的响应,其中 ip.ip_address: null、ip.country_mismatch: null,且 ip.threat 为空对象。单个富化字段在不可用时也可能为 null。

设备情报

IP Risk API 是纯服务器到服务器的 endpoint。设备指纹识别不属于此类,因为后端本身无法观察浏览器或设备信号。对于托管流程和 SDK 会话,Didit 会在会话响应中提供已收集的设备字段,包括 device_fingerprint、设备和浏览器详情、user_agent、原始设备数据以及跨会话匹配结果。

沙盒行为

沙盒密钥会校验请求,并确定性地返回已通过的数据。它们不会调用外部情报服务、不消耗额度、不创建会话,也不会向 Networks 提供数据。

计费

IP Risk API 调用的标准价格为每次 $0.02。一旦查询开始,每次生产环境请求即计费。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json
ip_address
string<ip>
必填

要评分的 IPv4 或 IPv6 地址。

示例:

"8.8.8.8"

claimed_country
string

用户或会话声明的可选 ISO 3166-1 alpha-2 或 alpha-3 国家/地区。用于计算 country_mismatch。

Maximum string length: 3
示例:

"ESP"

user_agent
string

后端检测到的 User-Agent。作为请求上下文存储;不提供设备指纹功能。

Maximum string length: 512
vendor_data
string

您为此请求提供的稳定引用。存储在 API 会话中并在响应中返回。

metadata
object | null

您的非敏感 JSON 元数据。存储在 API 会话中并在响应中原样返回。

响应

风险评估已完成。检查 status 获取决策;对于已完成的查询,HTTP 状态码始终为 200。

request_id
string<uuid>
必填

为此请求创建的 API 会话 ID。如果您需要将结果与后续的 Webhook 或控制台活动关联,请将其与 vendor_data 一同存储。

status
enum<string>
必填

此 API 会话的决策:存在网络或国家/地区不匹配风险时为 In Review,否则为 Approved。

可用选项:
Approved,
In Review
created_at
string<date-time>
必填

此响应的时间戳。

vendor_data
string | null

您发送的 vendor_data 回显,若未发送则为 null。

metadata
object | null

您发送的 metadata 回显,若未发送则为 null。

ip
object

IP 风险结果。如果查询未返回可用数据,各个丰富信息字段可为 null。

最后修改于 2026年11月7日