开放API接入文档 - 聚合实名认证

接入指南

登录控制台，在 API 密钥管理页面创建密钥，获取 api_key 和 api_secret。
在对接产品页面查看可用产品编码，请求体中的 product_code 必须填写实际产品编码。
所有开放接口请求必须携带签名请求头。
所有认证产品统一调用 POST /common/openapi/verify，通过 product_code 区分产品。

禁止传入 package_id。系统会根据 product_code 自动匹配套餐，或在 use_package=false 时按余额扣费。

签名鉴权

公共请求头

Header	说明	示例
X-Api-Key	API密钥	ak_xxxxxxxxxxxxxxxx
X-Timestamp	Unix时间戳，单位秒	1700000000
X-Nonce	随机字符串，建议16-32位	a1b2c3d4e5f6g7h8
X-Signature	HMAC-SHA256签名	e3b0c44298fc1c14...

签名算法

signature = HMAC-SHA256(api_key + timestamp + nonce, api_secret)

签名有效期默认 300 秒。服务端会校验时间戳、随机串和签名，避免重放请求。

认证接口

POST /common/openapi/verify

公共请求参数

参数	必填	类型	说明
product_code	是	string	认证产品编码，在控制台对接产品页面查看
use_package	否	boolean	是否使用套餐自动扣减，默认 true；false 则按余额扣费
name	条件	string	真实姓名，身份证相关认证必填
idcard	条件	string	身份证号码，身份证相关认证必填
mobile	条件	string	手机号三要素认证必填
return_url	否	string	人脸认证完成后的回跳地址
base64_image	条件	string	仅腾讯云增强人脸认证必填，Base64 人脸图片，建议不超过 500KB

身份证二要素

验证姓名和身份证号码是否一致。

手机号三要素

验证姓名、身份证号码和手机号是否一致。

人脸认证

发起人脸流程，返回 certify_id 和 certify_url。

身份证二要素请求示例

{
  "product_code": "YOUR_PRODUCT_CODE",
  "use_package": true,
  "name": "张三",
  "idcard": "110101199001011234"
}

手机号三要素请求示例

{
  "product_code": "YOUR_PRODUCT_CODE",
  "use_package": true,
  "name": "张三",
  "idcard": "110101199001011234",
  "mobile": "13800138000"
}

人脸认证请求示例

{
  "product_code": "YOUR_PRODUCT_CODE",
  "use_package": true,
  "name": "张三",
  "idcard": "110101199001011234",
  "return_url": "https://your-site.com/callback"
}

通用响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true,
    "message": "一致",
    "cost_time": 245,
    "charge_amount": 0,
    "is_charged": true,
    "package_used": true,
    "package_id_used": 10,
    "use_package": true
  }
}

人脸结果查询

POST /common/openapi/faceQuery

参数	必填	类型	说明
certify_id	是	string	人脸认证初始化接口返回的认证会话ID
product_code	否	string	可选，用于与初始化记录校验一致性

人脸查询扣费方式沿用初始化时传入的 use_package 值，不可重复扣费，重复查询不收费。

{
  "certify_id": "8a8b5a3c7d9e4f2a1b6c8d0e4f6a8b2c",
  "product_code": "YOUR_PRODUCT_CODE"
}

余额查询

GET /common/openapi/getBalance

{
  "code": 0,
  "message": "success",
  "data": {
    "balance": 1000.50,
    "frozen_amount": 0,
    "total_recharge": 5000,
    "total_consume": 3999.50
  }
}

产品列表

GET /common/openapi/getProducts

获取当前账号可用的认证产品列表和价格信息。实际可用产品以控制台配置为准。

代码示例

cURL

api_key="ak_your_api_key"
api_secret="sk_your_api_secret"
timestamp=$(date +%s)
nonce=$(openssl rand -hex 8)
message="${api_key}${timestamp}${nonce}"
signature=$(echo -n "$message" | openssl dgst -sha256 -hmac "$api_secret" -hex | awk '{print $2}')

curl -X POST "https://your-domain.com/common/openapi/verify" \
  -H "X-Api-Key: $api_key" \
  -H "X-Timestamp: $timestamp" \
  -H "X-Nonce: $nonce" \
  -H "X-Signature: $signature" \
  -H "Content-Type: application/json" \
  -d '{"product_code":"YOUR_PRODUCT_CODE","use_package":true,"name":"张三","idcard":"110101199001011234"}'

Python

import hmac, hashlib, time, uuid, requests

api_key = "ak_your_api_key"
api_secret = "sk_your_api_secret"
base_url = "https://your-domain.com/common/openapi"

timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex[:16]
signature = hmac.new(api_secret.encode(), (api_key + timestamp + nonce).encode(), hashlib.sha256).hexdigest()

headers = {
    "X-Api-Key": api_key,
    "X-Timestamp": timestamp,
    "X-Nonce": nonce,
    "X-Signature": signature,
    "Content-Type": "application/json",
}

resp = requests.post(base_url + "/verify", json={
    "product_code": "YOUR_PRODUCT_CODE",
    "use_package": True,
    "name": "张三",
    "idcard": "110101199001011234"
}, headers=headers)
print(resp.json())

错误码

错误码	说明	解决方案
AUTH_FAILED	签名验证失败	检查 API Key/Secret、时间戳和 nonce
INSUFFICIENT_BALANCE	余额不足	充值后重试
INSUFFICIENT_PACKAGE	无可用套餐或套餐不包含该产品	购买对应套餐或使用余额扣费
CHARGE_FAILED	扣费失败或并发冲突	稍后重试
PRODUCT_MISMATCH	product_code 与认证记录不一致	传入正确的 product_code
RECORD_NOT_FOUND	未找到开放 API 认证记录	检查 certify_id 是否正确
INVALID_PARAM	参数无效	检查请求参数，不要传 package_id
PRODUCT_NOT_FOUND	产品不存在或已禁用	检查 product_code 或联系管理员

SDK下载

可下载 SDK 或参考上方示例自行接入。

Python SDK · Go SDK · Java SDK · PHP SDK