简介

诺正通身份证核验 API 支持二要素（姓名+身份证号）核验。本教程以二要素为例。

更正说明（2026-11-13）：本文早期版本用的是一套不存在的接口形态（路径 /v1/id/verify、Bearer 头、JSON body、参数名 name / id_card / timestamp）。现行接口的路径是 /v2/id-server，鉴权是 mall_id + appkey + md5 签名，传输是表单编码。下方代码已按官方接口文档改正。

准备工作

在 官网提交试用申请，审核通过后由商务发放 mall_id 与 appkey（新用户含 100 次免费调用）

安装 requests 库

pip install requests

完整代码

import requests
import hashlib import time
配置：mall_id 与 appkey 由诺正通商务发放（见 /developers/common）
MALL_ID = "your_mall_id" APP_KEY = "your_appkey"
核验类接口走 api2 网关（HTTPS）；短信接口是另一台主机 http://api.nztapi.com/sms.php
BASE_URL = "https://api2.nztapi.com"
def sign(mall_id: str, realname: str, idcard: str, tm: str, app_key: str) -> str:     """生成签名：md5(mall_id + realname + idcard + tm + appkey)，拼接不带分隔符"""     raw = mall_id + realname + idcard + tm + app_key     return hashlib.md5(raw.encode("utf-8")).hexdigest()
def verify_id_card(realname: str, idcard: str) -> dict:     """身份证二要素核验：/v2/id-server"""     tm = str(int(time.time() * 1000))          # 13 位毫秒时间戳，签名与请求必须用同一个值     idcard = idcard.strip().lower()              # 末位 X 统一转小写 x     params = {         "mall_id": MALL_ID,         "realname": realname.strip(),         "idcard": idcard,         "tm": tm,         "sign": sign(MALL_ID, realname.strip(), idcard, tm, APP_KEY),     }     res = requests.post(         f"{BASE_URL}/v2/id-server",         data=params,                            # 表单编码，不是 JSON body         headers={"Content-Type": "application/x-www-form-urlencoded; charset=utf-8"},         timeout=10,     )     res.raise_for_status()     return res.json()
使用
if __name__ == "__main__":     result = verify_id_card("张三", "11010119900101123x")     print(result)

响应示例

{
  "data": {     "code": "1000",     "message": "一致"   },   "status": "2001" }

注意返回结构是两层：data.code 是业务结果码（字符串），status 是服务状态码，两者正交——status=2002（第三方服务器异常）时即使 code=1000 也要复核，不能只看 code。

错误码

核验类接口返回 data.code，取值与处置如下（短信接口是另一套码表，不通用）：

code	含义	处理建议

1000	一致（计费）	放行
1001	不一致（计费）	视风控等级拦截或转人工；不要重试
1002	库中无此号（不计费）	拒绝
1101	商家 ID / IP 不合法	检查 mall_id 与出口 IP 白名单
1102	姓名不合法	检查编码与字符
1103	身份证号 / 手机号 / 银行卡号编码不合法	末位 X 转小写 x
1104	签名不合法	核对拼接顺序与 appkey
1105	第三方 / 银联中心超时	可退避重试
1106	账户余额不足	充值或联系商务
1107	tm 参数不合法	须 13 位毫秒时间戳
1108	参数异常	检查必填参数是否齐全
1109	帐号被暂停	联系商务

完整码表与短信侧码表见 通用接入规范。

下一步

接入成功后，可以查看 API 文档 了解更多接口

遇到问题可提交 工单