实名认证平台 API 文档

实名认证平台提供标准 RESTful API，支持二要素身份校验、人脸核身和企业三要素认证三大核心能力，以及邮件推送通信服务。本文档将帮助您快速完成 API 对接。

接口概述

基础信息

通用请求参数

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

通用响应格式

{
    "code": 0,
    "msg": "success",
    "data": { ... }
}

URL 格式

系统支持两种 URL 格式访问 API，效果完全一致：

伪静态模式（推荐）

需要 Nginx 配置 try_files 伪静态规则，路径更简洁美观。

原生参数模式

无需任何服务器配置即可使用，兼容性最佳。

签名认证

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

签名生成规则

1. 将 appid、timestamp、nonce、appsecret 四个值按顺序拼接为一个字符串
2. 对拼接后的字符串进行 MD5 哈希（32 位小写）

签名公式

sign = md5(appid + timestamp + nonce + appsecret)

示例

// 假设参数如下：
appid     = "app_abc123"
timestamp = "1700000000"
nonce     = "a1b2c3d4e5f6"
appsecret = "secret_xyz789"

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

// MD5 哈希：
sign = md5(raw) = "e10adc3949ba59abbe56e057f20f883e"

IP 白名单

可在控制台为应用配置 IP 白名单。配置后，仅白名单内的 IP 可调用该应用的 API。白名单为空时不做限制。

错误码

当请求失败时，响应中的 code 字段为非零值。以下是完整的错误码列表：

二要素身份校验

校验姓名与身份证号是否匹配，实时调用百度云二要素认证接口。

请求参数

成功响应

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

失败响应

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

企业三要素认证

校验企业名称、统一社会信用代码与法人姓名三要素是否一致，适用于企业入驻审核、供应商资质核验等 B 端场景。

请求参数

验证一致

{
    "code": 0,
    "msg": "企业三要素验证一致",
    "data": {
        "creditNo": true,
        "companyName": true,
        "legalPerson": true
    }
}

验证不一致

{
    "code": 3002,
    "msg": "企业三要素验证不一致",
    "data": {
        "creditNo": true,
        "companyName": true,
        "legalPerson": false
    }
}

响应字段说明

人脸核身 - 创建会话

创建一个人脸核身会话，返回人脸采集页面 URL。将该 URL 发送给终端用户，用户在页面上完成人脸采集后，通过查询结果接口获取核身结果。

请求参数

成功响应

{
    "code": 0,
    "msg": "人脸核身会话创建成功",
    "data": {
        "verify_url": "https://sms.sumingyun.cn/?route=api/face_capture&token=xxxx",
        "verify_id": "xxxx",
        "log_id": 123
    }
}

响应字段说明

人脸核身 - 查询结果

查询人脸核身会话的处理结果。建议在创建会话后轮询此接口（间隔 3-5 秒），直到获取到最终结果。

请求参数

核身通过

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

核身未通过

{
    "code": 3002,
    "msg": "人脸核身未通过",
    "data": null
}

等待用户操作

{
    "code": 3003,
    "msg": "用户尚未完成人脸核身",
    "data": null
}

人脸核身 - 对接时序

人脸核身采用异步模式，完整对接流程如下：

查询认证模式

查询当前应用配置的认证模式。可用于客户端动态判断应该调用二要素还是人脸核身接口。

请求参数

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

成功响应

{
    "code": 0,
    "msg": "ok",
    "data": {
        "mode": "2factor"
    }
}

mode 取值说明

签名示例 - PHP

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

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

    $ch = curl_init("https://sms.sumingyun.cn/api/{$action}");
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => http_build_query($data),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
    ]);
    $resp = curl_exec($ch);
    curl_close($ch);

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

// 二要素校验
$result = callApi('check2factor', [
    'real_name'    => '张三',
    'id_card'      => '110101199001011234',
    'out_order_no' => 'ORDER_001',
]);
print_r($result);

签名示例 - Java

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

public class ApiClient {
    private static final String APP_ID = "your_app_id";
    private static final String APP_SECRET = "your_app_secret";
    private static final String BASE_URL = "https://sms.sumingyun.cn/api/";

    public static 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();
    }

    public static String check2factor(String realName, String idCard, String orderNo) throws Exception {
        String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
        String nonce = UUID.randomUUID().toString().replace("-", "");
        String sign = md5(APP_ID + timestamp + nonce + APP_SECRET);

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

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "check2factor"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> resp = client.send(request, HttpResponse.BodyHandlers.ofString());
        return resp.body();
    }
}

签名示例 - Python

import hashlib, time, uuid, requests

APP_ID     = 'your_app_id'
APP_SECRET = 'your_app_secret'
BASE_URL   = 'https://sms.sumingyun.cn/api/'

def call_api(action: str, params: dict) -> dict:
    timestamp = str(int(time.time()))
    nonce = uuid.uuid4().hex
    sign = hashlib.md5(
        (APP_ID + timestamp + nonce + APP_SECRET).encode()
    ).hexdigest()

    data = {
        'appid': APP_ID,
        'timestamp': timestamp,
        'nonce': nonce,
        'sign': sign,
        **params,
    }
    resp = requests.post(BASE_URL + action, data=data, timeout=30)
    return resp.json()

# 二要素校验
result = call_api('check2factor', {
    'real_name': '张三',
    'id_card': '110101199001011234',
    'out_order_no': 'ORDER_001',
})
print(result)

签名示例 - Node.js

const crypto = require('crypto');
const { URLSearchParams } = require('url');

const APP_ID     = 'your_app_id';
const APP_SECRET = 'your_app_secret';
const BASE_URL   = 'https://sms.sumingyun.cn/api/';

async function callApi(action, params) {
    const timestamp = String(Math.floor(Date.now() / 1000));
    const nonce = crypto.randomBytes(16).toString('hex');
    const sign = crypto.createHash('md5')
        .update(APP_ID + timestamp + nonce + APP_SECRET)
        .digest('hex');

    const body = new URLSearchParams({
        appid: APP_ID,
        timestamp,
        nonce,
        sign,
        ...params,
    });

    const resp = await fetch(BASE_URL + action, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: body.toString(),
    });
    return resp.json();
}

// 二要素校验
callApi('check2factor', {
    real_name: '张三',
    id_card: '110101199001011234',
    out_order_no: 'ORDER_001',
}).then(console.log);

计费说明

计费模式

平台采用预付费 + 按次扣费模式：

1. 用户在控制台充值余额（支持在线支付和卡密充值）
2. 每次 API 调用时，系统先冻结对应费用
3. 调用成功后确认扣费，调用失败则回滚冻结金额

单价说明

邮件推送计费

SMTP 邮件推送服务采用独立计费模式，按发送邮件数量计费：

更新日志