天音实名认证 API 文档

天音实名认证平台提供标准 RESTful API，支持二要素身份校验和人脸核身两大核心能力。本文档将帮助您快速完成 API 对接。

接口概述

基础信息

通用请求参数

所有接口（除特殊说明外）均需携带以下公共参数：

通用响应格式

{
    "code": 0,          // 0 表示成功，非 0 为错误码
    "msg": "success",   // 结果描述
    "data": { ... }     // 业务数据，失败时可能为 null
}

签名认证

所有 API 请求必须携带签名参数，用于验证请求合法性。签名算法如下：

签名生成规则

签名步骤

1. 获取当前 Unix 时间戳（秒级）作为 timestamp
2. 生成一个随机字符串作为 nonce（建议 16-32 位字母数字）
3. 将 appid + timestamp + nonce + appsecret 拼接成一个字符串
4. 对拼接后的字符串计算 MD5，得到 32 位小写哈希值即为 sign

示例

// 假设参数如下：
appid     = "a1b2c3d4e5f6g7h8"
timestamp = "1700000000"
nonce     = "abcdef1234567890"
appsecret = "s3cr3tk3y1234567890abcdef12345678"

// 拼接字符串：
raw = "a1b2c3d4e5f6g7h81700000000abcdef1234567890s3cr3tk3y1234567890abcdef12345678"

// 计算 MD5：
sign = md5(raw) = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

错误码

二要素身份校验

通过姓名和身份证号实时比对权威数据库，验证身份信息是否一致。

请求参数

成功响应

{
    "code": 0,
    "msg": "认证成功",
    "data": {
        "score": 100
    }
}

失败响应

{
    "code": 3002,
    "msg": "认证失败",
    "data": null
}

人脸核身 - 创建会话

创建一个人脸核身会话，获取人脸采集页面 URL。将该 URL 提供给终端用户在浏览器中打开，完成活体检测和人脸比对。

请求参数

成功响应

{
    "code": 0,
    "msg": "人脸核身会话创建成功",
    "data": {
        "verify_url": "https://您的域名/?route=api/face_capture&token=xxx",
        "verify_id": "xxxxxxxxxxxxxxxx",
        "log_id": 123
    }
}

对接流程

1. 服务端调用本接口，获取 verify_url、verify_id 和 log_id
2. 将 verify_url 返回给前端，引导用户在浏览器中打开（支持 H5 / 微信内置浏览器）
3. 用户完成人脸采集后，服务端轮询「查询结果」接口获取核身结果

人脸核身 - 查询结果

查询人脸核身会话的处理结果。建议在创建会话后，以 2-3 秒间隔轮询本接口。

请求参数

响应状态

成功响应

{
    "code": 0,
    "msg": "人脸核身通过",
    "data": {
        "score": 80
    }
}

查询认证模式

查询当前应用配置的认证模式，用于前端动态展示对应的认证流程。

请求参数

仅需公共参数（appid, timestamp, nonce, sign），无额外业务参数。

成功响应

{
    "code": 0,
    "msg": "ok",
    "data": {
        "mode": "2factor"   // 可选值: 2factor | face | both
    }
}

签名示例代码

PHP

<?php
function callApi(string $url, string $appId, string $appSecret, array $params): array
{
    $timestamp = (string)time();
    $nonce = bin2hex(random_bytes(16));
    $sign = md5($appId . $timestamp . $nonce . $appSecret);

    $postData = array_merge($params, [
        'appid'     => $appId,
        'timestamp' => $timestamp,
        'nonce'     => $nonce,
        'sign'      => $sign,
    ]);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => http_build_query($postData),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_SSL_VERIFYPEER => true,
    ]);
    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true) ?: [];
}

// 调用二要素校验
$result = callApi(
    'https://您的域名/?route=api/check2factor',
    '您的AppID',
    '您的AppSecret',
    [
        'real_name'    => '张三',
        'id_card'      => '110101199001011234',
        'out_order_no' => 'ORDER_' . time(),
    ]
);
print_r($result);

Java

import java.net.http.*;
import java.security.MessageDigest;
import java.util.UUID;

public class TianyinClient {
    private final String appId;
    private final String appSecret;
    private final String baseUrl;

    public TianyinClient(String baseUrl, String appId, String appSecret) {
        this.baseUrl = baseUrl;
        this.appId = appId;
        this.appSecret = appSecret;
    }

    public String check2Factor(String realName, String idCard, String outOrderNo) throws Exception {
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
        String nonce = UUID.randomUUID().toString().replace("-", "");
        String sign = md5(appId + timestamp + nonce + appSecret);

        String body = "appid=" + appId
            + "×tamp=" + timestamp
            + "&nonce=" + nonce
            + "&sign=" + sign
            + "&real_name=" + URLEncoder.encode(realName, "UTF-8")
            + "&id_card=" + idCard
            + "&out_order_no=" + outOrderNo;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/?route=api/check2factor"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        return response.body();
    }

    private String md5(String input) throws Exception {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] digest = md.digest(input.getBytes("UTF-8"));
        StringBuilder sb = new StringBuilder();
        for (byte b : digest) sb.append(String.format("%02x", b));
        return sb.toString();
    }
}

Python

import hashlib, time, secrets, requests

class TianyinClient:
    def __init__(self, base_url, app_id, app_secret):
        self.base_url = base_url
        self.app_id = app_id
        self.app_secret = app_secret

    def _sign(self, timestamp, nonce):
        raw = self.app_id + timestamp + nonce + self.app_secret
        return hashlib.md5(raw.encode()).hexdigest()

    def check_2factor(self, real_name, id_card, out_order_no):
        timestamp = str(int(time.time()))
        nonce = secrets.token_hex(16)
        sign = self._sign(timestamp, nonce)

        resp = requests.post(
            f"{self.base_url}/?route=api/check2factor",
            data={
                "appid": self.app_id,
                "timestamp": timestamp,
                "nonce": nonce,
                "sign": sign,
                "real_name": real_name,
                "id_card": id_card,
                "out_order_no": out_order_no,
            },
            timeout=10
        )
        return resp.json()

# 使用示例
client = TianyinClient("https://您的域名", "您的AppID", "您的AppSecret")
result = client.check_2factor("张三", "110101199001011234", f"ORDER_{int(time.time())}")
print(result)

更新日志