17370845950

PHP调用顶象行为识别API需手动构造HTTP请求：严格按POST\n/v2/identify\n\n\n格式拼接签名字符串，使用毫秒级timestamp、正确计算content-md5与HMAC-SHA256签名，并确保touchPoints坐标归一化至0–1区间。

顶象 AI 反欺诈服务不提供公开的 PHP SDK，官方仅支持 Java、Python、Node.js 和 Android/iOS 原生接入；PHP 项目必须通过 HTTP POST 调用其行为数据识别 API，且需严格遵循签名规则，否则返回 401 Unauthorized 或 invalid signature 错误。

如何构造合法的 behaviorData 接口请求

顶象的「行为数据识别」接口地址为 https://api.dingxiang-inc.com/behavior/v2/identify，PHP 必须手动拼接 Authorization 头并计算 HMAC-SHA256 签名。关键点不是发不发得出去，而是签名字段顺序、编码方式、时间戳精度是否匹配服务端校验逻辑。

• appKey 和 appSecret 必须从顶象控制台获取，不能硬编码在代码中，建议从环境变量读取
• 签名字符串格式为：POST\n/v2/identify\n\n\n（注意全部小写、换行符为 \n，无空格）
• timestamp 必须是毫秒级 Unix 时间戳，与顶象服务器时间偏差不能超过 300 秒，PHP 中应使用 round(microtime(true) * 1000)
• content-md5 是原始 JSON 请求体的 MD5 值（不含换行、空格），不是 base64 编码后的 MD5
• 请求头 Content-Type 必须设为 application/json; charset=utf-8，少一个分号或字符集都会被拒

{
    "appKey": "your_app_key_here",
    "timestamp": 1717023456789,
    "nonce": "a1b2c3d4e5f67890",
    "signature": "hmac-sha256-hex-string",
    "data": {
        "sessionId": "sess_abc123",
        "userId": "u_789",
        "ip": "119.123.45.67",
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15",
        "screenWidth": 390,
        "screenHeight": 844,
        "touchPoints": [
            {"x": 120, "y": 340, "t": 1717023456780},
            {"x": 125, "y": 345, "t": 1717023456792}
        ]
    }
}

PHP 中计算 signature 的常见翻车点

PHP 的 hash_hmac() 默认输出二进制，但顶象要求的是十六进制小写字符串；同时，json_encode() 默认不转义中文、不移除空格，会导致 content-md5 计算错误。

• 务必用 JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES 选项编码请求体
• content-md5 应对 json_encode($body, ...) 的原始字节流计算，不是对格式化后的 JSON 字符串
• hash_hmac('sha256', $signStr, $appSecret, true) 第四个参数必须为 true，再用 bin2hex() 转成小写 hex
• 不要用 file_get_contents('php://input') 拼接签名字符串——那是接收端逻辑，PHP 发起方必须自己构造
• 测试时可用 curl -v 抓包，比对请求头中的 Authorization 是否与你本地计算的一致

返回结果解析与异常处理

顶象接口成功响应状态码为 200，但业务失败（如模型拒绝、参数缺失）仍返回 200，需检查响应体中的 code 字段。直接用 http_response_code() === 200 判定成功会漏掉大量业务异常。

• 正常识别成功："code": 0，"riskLevel" 为 "low"/"medium"/"high"
• 参数错误："code": 10001，常见于 touchPoints 时间戳乱序、userId 超长（最大 64 字符）
• 签名过期："code": 10004，说明 timestamp 偏差超限，需同步服务器时间或加 NTP 校准
• 模型未就绪："code": 20001，通常因新接入应用未完成模型训练，需联系锐法客户经理开通
• 务必用 json_last_error() 检查响应体是否为合法 JSON，顶象某些网关错误会返回 HTML 页面（如 502 Bad Gateway）

最易忽略的是 touchPoints 的时间戳单调递增约束和屏幕坐标归一化要求：x/y 必须在 0–1 区间内，不是像素值；如果前端传的是原始像素，PHP 层不做转换就直发，模型将无法理解行为轨迹。