通用接入规范（签名 / 鉴权 / 错误码）

① 通用鉴权参数

所有 API 接口（身份证、手机号、银行卡、人脸、短信）都共享以下 3 个鉴权参数，缺一不可。

除上述 3 个公参外，每个接口还有专属的"业务参数"（如身份证接口需要 realname + idcard）。 请前往对应产品页查看：身份证核验手机号核验银行卡核验人脸识别短信验证码身份证 OCR

② 签名规则

// Java 示例（身份证核验 /v2/id-server）
String sign = DigestUtils.md5Hex(
  mall_id + realname + idcard + tm + appKey
);

⚠️ 各接口签名拼接顺序（照抄其他接口会返回 1104）

同一套 MD5 规则，但业务参数参与签名的字段各不相同。 下表为官方口径，请按对应接口的公式拼接。

③ 返回结构

所有接口返回 JSON，包含两层状态码： data.code（业务结果） + status（服务状态）。 判断调用是否成功要看 data.code == "1000"。注意：短信接口 /sms.php 是例外， 其返回为扁平结构（无 data / status 包装），code 为数字。

{
  "data": {
    "code": "1000",      // 业务结果码
    "message": "一致"    // 业务结果说明
  },
  "status": "2001"        // 服务状态码
}

返回 JSON 包含 data.code（业务结果）和 status（服务状态）；仅 code=1000/1001 计费。

④ 错误码速查表

核验类接口（身份证 / 手机号 / 银行卡）共享的错误码体系，共 21 个 code，按"业务 / 参数 / 鉴权 / 账户 / 服务"5 大类分组。短信接口使用另一套数字码，见本节末。

📩 短信接口错误码（/sms.php，与上表不通用）

短信接口为独立体系：报文字段扁平、code 为数字、签名不含 tm。

{
  "code": 1000,           // 数字码，非字符串
  "message": "发送成功"
}

短信接口为扁平结构，code 为数字；与核验类接口的错误码表不通用。

⑤ 多语言签名示例

下面以身份证核验接口为例， 展示 Java / PHP / Python / Go / Node.js 5 种语言的签名生成 + 请求示例。 其他接口（银行卡、手机号等）只需替换业务参数部分。

import org.apache.commons.codec.digest.DigestUtils;

String tm = String.valueOf(System.currentTimeMillis());
// mall_id + 业务参数 + tm + appkey（不含 + 号）顺序拼接
String sign = DigestUtils.md5Hex(
  mallId + realname + idcard + tm + appKey
);

// 请求示例
String url = "https://api.nztapi.com/v2/id-server"
  + "?mall_id=" + mallId
  + "&realname=" + URLEncoder.encode(realname, "UTF-8")
  + "&idcard=" + idcard
  + "&tm=" + tm
  + "&sign=" + sign;

$tm = (string)(int)(microtime(true) * 1000);
$sign = md5($mallId . $realname . $idcard . $tm . $appKey);

$url = "https://api.nztapi.com/v2/id-server?mall_id={$mallId}"
  . "&realname=" . urlencode($realname)
  . "&idcard={$idcard}&tm={$tm}&sign={$sign}";

$response = file_get_contents($url);
$result = json_decode($response, true);

import time, hashlib, requests

tm = str(int(time.time() * 1000))
raw = mall_id + realname + idcard + tm + app_key
sign = hashlib.md5(raw.encode("utf-8")).hexdigest()

params = {
    "mall_id": mall_id,
    "realname": realname,
    "idcard": idcard,
    "tm": tm,
    "sign": sign,
}
r = requests.get("https://api.nztapi.com/v2/id-server", params=params)
print(r.json())

package main

import (
    "crypto/md5"
    "encoding/hex"
    "fmt"
    "strconv"
    "time"
)

func sign(mallId, realname, idcard, appKey string) string {
    tm := strconv.FormatInt(time.Now().UnixMilli(), 10)
    raw := mallId + realname + idcard + tm + appKey
    h := md5.Sum([]byte(raw))
    return hex.EncodeToString(h[:])
}

const crypto = require("crypto");

const tm = Date.now().toString();
const raw = mallId + realname + idcard + tm + appKey;
const sign = crypto.createHash("md5").update(raw).digest("hex");

const url = `https://api.nztapi.com/v2/id-server?mall_id=${mallId}&realname=${encodeURIComponent(realname)}&idcard=${idcard}&tm=${tm}&sign=${sign}`;

fetch(url).then(r => r.json()).then(console.log);

⑥ 各产品业务参数

除了通用鉴权参数外，每个接口还有自己的业务参数。 点击下方产品卡片查看完整业务参数和接入说明。