服务端 API

使用 Geelab 设备指纹 v2 服务端 API 查询设备标识、设备信息与风险信号

概述

查询设备指纹：用客户端 SDK 拿到的 device_token，换取设备标识、设备信息与风险信号。

接口

Method	Path	用途
`POST`	`/api/v2/fp_query/{public_key}`	查询设备指纹

输入从哪里获取

字段	用在	从哪里获取
`public_key`	路径 `/api/v2/fp_query/{public_key}`	后台。应用公开标识，用于定位应用和地区。不是认证密钥。
`secret`	`Authorization: Bearer <secret>`	后台。服务端查询认证。
`device_token`	请求体	客户端 SDK 接口。

支持的客户端

iOS、Android、Web/H5。

地区限制

每个应用只属于一个地区，由后台配置。请求必须发到该应用所属地区的节点。

地区	说明
`GLB`	全球
`NA`	北美
`EU`	欧洲

发到其他地区的节点时，返回 404，message 为 integration not found。

响应信封

Content-Type: application/json。HTTP 状态码与 JSON code 相同。

成功：

{ "code": 200, "data": {}, "message": "Success" }

失败：

{ "code": 400, "data": {}, "message": "Invalid request" }

校验失败时 data 为：

{
  "errors": [
    { "field": "device_token", "reason": "Field required", "type": "missing" }
  ]
}

错误码

HTTP / `code`	`message`	含义
400	`Invalid request`	请求体不合法，或 `device_token` 无效
401	`Invalid bearer token`	认证失败，到后台核对 `secret`
403	`Forbidden`	应用不可用，或未通过 IP 白名单
404	`integration not found`	`public_key` 无效，或请求未打到应用所属地区的节点
500	`Internal server error`	服务端错误

POST `/api/v2/fp_query/{public_key}`

查询设备指纹。传入客户端 SDK 返回的 device_token，得到设备标识、设备信息与风险信号。


Method	`POST`
Path	`/api/v2/fp_query/{public_key}`
Auth	`Authorization: Bearer <secret>`
Content-Type	`application/json`
Success	HTTP 200，`code=200`，`message=Success`

请求

POST /api/v2/fp_query/{public_key}
Authorization: Bearer <secret>
Content-Type: application/json

Path

字段	类型	必填	含义	从哪里获取
`public_key`	string	是	应用公开标识	后台

Headers

字段	必填	含义	从哪里获取
`Authorization`	是	`Bearer <secret>`，服务端查询认证	`secret` 从后台获取
`Content-Type`	是	`application/json`	—

Body

{
  "device_token": "<from-client-sdk>",
  "metadata": {
    "account_id": "account-001",
    "phone_num": "+8613800000000",
    "phone_sha256": "opaque-hash-value",
    "email": "[email protected]"
  },
  "event_type": "login",
  "event_time": "2026-08-20T10:30:00+08:00"
}

字段	类型	必填	含义	从哪里获取
`device_token`	string	是	本次查询的设备凭证	客户端 SDK 接口
`metadata`	object	否	业务侧关联信息，见下表	调用方自行填写
`event_type`	string	否	业务事件类型，如 `login`	调用方自行填写
`event_time`	string	否	事件时间，RFC 3339（需带时区或 `Z`）	调用方自行填写

metadata

均为可选 string。

字段	含义
`account_id`	账户标识
`phone_num`	手机号明文
`phone_sha256`	手机号哈希
`phone_country_code`	国家/地区代码
`phone_prefix`	号码前缀
`email`	邮箱明文
`email_sha256`	邮箱哈希
`email_domain`	邮箱域名
`ip_addr_v4`	IPv4
`ip_addr_v6`	IPv6
`user_agent`	User-Agent
`ja3`	JA3
`ja4`	JA4
`mac_prefix`	MAC 前缀
`wifi_bssid_prefix`	Wi-Fi BSSID 前缀
`tls_cipher`	TLS cipher

最小请求体：

{ "device_token": "<from-client-sdk>" }

响应 `200`

{
  "code": 200,
  "data": {
    "request_id": "req_0198c7a1-5b2e-7c10-8d44-1234567890ab",
    "event_id": "evt_0198c7a1-5b2e-7c10-8d44-1234567890ab",
    "fp_detail": {
      "device_id": "GEE4-xxxxxx",
      "version": "1.0"
    },
    "signals": [
      {
        "signal": "CLOUD_PHONE",
        "level": "HIGH",
        "confidence": 0.8
      }
    ],
    "detail": {
      "client_type": "Android",
      "device_basic": {
        "os": "Android",
        "pla": "arm64-v8a",
        "mod": "Pixel 8",
        "osv": "14"
      },
      "ip_info": {
        "ip": "1.1.1.1"
      }
    }
  },
  "message": "Success"
}

data

字段	类型	含义
`request_id`	string	分析 ID。格式 `req_` + UUID v7。同一 `device_token` 多次查询值相同。
`event_id`	string	本次查询 ID。格式 `evt_` + UUID v7。每次查询值不同。
`fp_detail`	object	设备指纹
`signals`	array	命中的信号列表，未命中时为 `[]`
`detail`	object	客户端类型、设备信息、IP

fp_detail

字段	类型	含义
`device_id`	string	设备指纹
`version`	string	指纹版本，当前为 `"1.0"`

signals[]

字段	类型	含义
`signal`	string	信号标识，例如 `CLOUD_PHONE`
`level`	string	`LOW` / `MEDIUM` / `HIGH`
`confidence`	number	`0.0`–`1.0`

各信号的取值与说明见下文「信号」。

detail

字段	类型	含义
`client_type`	string	`Android` / `iOS` / `Web/H5`
`device_basic`	object	设备基础信息，结构随 `client_type` 变化
`ip_info`	object	`{ "ip": "<string>" }`

Android / iOS 的 device_basic：

{
  "os": "Android",
  "pla": "arm64-v8a",
  "mod": "Pixel 8",
  "osv": "14"
}

字段	含义
`os`	操作系统
`pla`	架构
`mod`	型号
`osv`	系统版本

Web/H5 的 device_basic：

{
  "browser": { "name": "Chrome", "version": "145.0.0.0", "major": "145" },
  "device": { "model": "Macintosh", "vendor": "Apple" },
  "os": { "name": "macOS", "version": "10.15.7" }
}

错误

HTTP 状态码等于 code。message 为下表中的精确字符串。

HTTP	`message`	`data`	含义
400	`Invalid request`	`{ "errors": [ { "field", "reason", "type" } ] }`	缺字段、类型错误或 `event_time` 非法
400	`Invalid request`	`{ "errors": [{ "field": "device_token", "reason": "Invalid token", "type": "value_error" }] }`	`device_token` 无效
401	`Invalid bearer token`	`{}`	认证失败
403	`Forbidden`	`{}`	应用不可用，或未通过 IP 白名单
404	`integration not found`	`{}`	`public_key` 无效，或请求未打到应用所属地区的节点
500	`Internal server error`	`{}`	服务端错误

{
  "code": 400,
  "data": {
    "errors": [
      { "field": "device_token", "reason": "Field required", "type": "missing" }
    ]
  },
  "message": "Invalid request"
}

{
  "code": 401,
  "data": {},
  "message": "Invalid bearer token"
}

示例

{public_key}、{secret} 从后台复制；{device_token} 用客户端 SDK 返回值；请求发到应用所属地区的节点。

curl -sS -X POST "https://{host}/api/v2/fp_query/{public_key}" \
  -H "Authorization: Bearer {secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "{device_token}",
    "metadata": { "account_id": "account-001" },
    "event_type": "login",
    "event_time": "2026-08-20T10:30:00+08:00"
  }'

信号

fp_query 成功响应里 data.signals[] 的取值。未命中时数组为 []。

字段	类型	含义
`signal`	string	信号标识，例如 `CLOUD_PHONE`
`level`	string	`LOW` / `MEDIUM` / `HIGH`
`confidence`	number	`0.0`–`1.0`

信号一览（51）

`signal`	`level`	`confidence`	说明
`BEING_DEBUGGED`	`HIGH`	1	设备存在被调试风险，可进行逆向分析、破解、群控自动化
`DEBUG_MODE_OR_TEST_APP`	`LOW`	1	设备开启了调试模式或使用 debug/ 破解版本非商店下载的应用包
`EMULATOR`	`HIGH`	0.95	检测到传统模拟器风险
`CLOUD_PHONE`	`HIGH`	0.8	检测到云手机（或 ARM 服务器）风险
`RUNNING_ON_MACOS`	`MEDIUM`	1	检测到 Mac 运行 App 风险
`VPN_ENABLED`	`LOW`	1	设备开启 VPN 中
`NETWORK_PROXY`	`MEDIUM`	1	设备开启网络代理中
`INVALID_PACKAGE`	`LOW`	1	检测到包名篡改或重打包
`TOKEN_EXPIRED`	`MEDIUM`	0.9	`device_token` 过期或重复使用
`LIMIT_EXCEED`	`MEDIUM`	1	超过限制
`SCREEN_SHARING`	`LOW`	1	设备正在进行屏幕分享
`VOICE_CONNECTED`	`LOW`	1	设备正在语音通话中
`WHITELIST_ACCOUNT_ID`	`HIGH`	1	用户账号黑名单
`WHITELIST_IP`	`HIGH`	1	IP 黑名单
`WHITELIST_DEVICE_FINGERPRINT`	`HIGH`	1	设备指纹黑名单
`IP_CRAWLER_OR_BOT`	`MEDIUM`	0.8	IP 存在恶意破解或爬虫行为
`IP_MALICIOUS_ATTACK`	`HIGH`	0.6	IP 存在恶意攻击行为
`IP_SUSPICIOUS_PROXY`	`MEDIUM`	0.8	IP 疑似代理IP
`BLACKLIST_ACCOUNT_ID`	`LOW`	1	用户账号白名单
`BLACKLIST_IP`	`LOW`	1	IP 白名单
`BLACKLIST_DEVICE_FINGERPRINT`	`LOW`	1	设备指纹白名单
`DEVICE_JAILBREAK`	`HIGH`	1	iOS 设备存在越狱行为
`DEVICE_ROOTED`	`HIGH`	1	Android 设备存在 Root 行为
`SUSPICIOUS_CUSTOM_ROM`	`HIGH`	0.8	Android 设备使用可疑定制 ROM
`SUSPICIOUS_OPEN_SOURCE_ROM`	`HIGH`	0.9	Android 设备 ROM 为安卓开源项目
`BROWSER_COOKIE_FEATURE_DISABLED`	`MEDIUM`	0.9	浏览器cookie不可用
`PSEUDO_BROWSER_ENV`	`HIGH`	0.9	伪造的浏览器环境
`BROWSER_INCOGNITO_MODE`	`LOW`	0.8	浏览器处于隐私模式
`DEVICE_BOOTLOADER_UNLOCKED`	`HIGH`	0.8	检测到设备 Bootloader 已解锁
`SUSPICIOUS_DEVICE_RESET`	`HIGH`	0.8	疑似设备重置
`SYSTEM_VERSION_TOO_LOW`	`MEDIUM`	0.6	设备系统版本过低
`DEVICE_WITHOUT_SIM`	`LOW`	0.4	检测到设备未插 SIM 卡
`HOOK_TAMPERING_LOW`	`MEDIUM`	1	设备有代码篡改低风险，使用该标签需要排除自身开发篡改的行为
`HOOK_TAMPERING_MEDIUM`	`HIGH`	1	设备有代码篡改中风险，可篡改代码逻辑
`HOOK_TAMPERING_HIGH`	`HIGH`	1	设备有代码篡改高风险
`SUSPICIOUS_DEVICE_INFO_TAMPERED`	`HIGH`	0.8	设备存在信息伪造风险，设备属性或指纹不匹配
`ANTIDETECT_BROWSER`	`HIGH`	0.8	设备运行在反检测浏览器中
`APP_CLONE_TOOL_INSTALLED`	`LOW`	1	设备存在安装多开工具风险
`TAMPER_TOOL_INSTALLED`	`LOW`	1	检测到设备安装了改机工具风险
`AUTOMATION_TOOL_INSTALLED`	`LOW`	1	检测到设备安装了群控/自动化工具风险，可规模化黑产操作
`REVERSE_ENGINEERING_TOOL_INSTALLED`	`LOW`	1	检测到设备安装逆向工具风险
`NETWORK_TAMPER_TOOL_INSTALLED`	`LOW`	1	设备存在使用网络篡改工具风险
`GAME_TAMPER_TOOL_INSTALLED`	`LOW`	1	设备存在使用游戏修改器工具风险
`VIRTUAL_LOCATION_TOOL_INSTALLED`	`LOW`	1	检测到设备安装了虚拟定位风险
`RUNNING_IN_VIRTUAL_MACHINE`	`HIGH`	1	当前设备处于虚拟机环境中
`RUNNING_IN_CLONED_APP`	`HIGH`	1	当前处于处于多开环境中
`USING_DEVICE_TAMPERING_TOOL`	`HIGH`	1	当前正使用改机或风险工具
`USING_AUTOMATION_TOOL`	`HIGH`	0.95	当前正使用群控或自动化工具
`USING_REVERSE_ENGINEERING_TOOL`	`HIGH`	1	当前正使用逆向篡改工具
`USING_VIRTUAL_LOCATION`	`HIGH`	1	当前正使用虚拟定位工具
`RUNNING_IN_SYSTEM_CLONED`	`LOW`	0.9	设备系统多开风险