诺正通身份核验 API

通过诺正通的 REST API 执行实名核验。适用于：用户注册实名、开户核身、支付绑卡校验等已获得用户本人授权的场景。

前置条件

环境变量（未配置时先引导用户注册）：

| 变量 | 说明 | |---|---| | NZT_MALL_ID | 商户 ID，官网提交试用申请，人工核验开通后发放（1 个工作日内完成） | | NZT_APP_KEY | 签名密钥，随账户开通一并发放，不可外泄 |

用户没有账号时，引导到 https://www.nztapi.com/trial 提交试用申请——平台在 1 个工作日内完成人工资质核验，通过后开通账户并发放 mall_id + appkey（含免费试用额度）。

无凭证时所有命令返回申请指引（不会报错）。零第三方依赖，仅需 Python 3.8+ 标准库。

使用

# 身份证二要素（姓名 + 身份证号）
python scripts/verify.py id2 --name "张三" --idcard "11010119900101123x"

# 手机号二要素（姓名 + 手机号）
python scripts/verify.py phone2 --name "张三" --phone "13800138000"

# 手机号三要素（姓名 + 身份证号 + 手机号）
python scripts/verify.py phone3 --name "张三" --idcard "..." --phone "13800138000"

# 银行卡二要素（姓名 + 卡号）
python scripts/verify.py bank2 --name "张三" --cardnum "6222021234567890123"

# 银行卡三要素（+身份证号）
python scripts/verify.py bank3 --name "张三" --idcard "..." --cardnum "622202..."

# 银行卡四要素（+预留手机号）
python scripts/verify.py bank4 --name "张三" --idcard "..." --cardnum "622202..." --mobile "13800138000"

# 下发短信验证码
python scripts/verify.py sms --phone "13800138000" --code "884800" [--title 诺正通]

# 检查凭证配置（不计费）
python scripts/verify.py check

MCP Server 版：如果已挂载 nuozhengtong-verify MCP，可直接对话式调用工具 verify_id_card / verify_phone_three_factor / verify_bank_card_four_factor / send_sms_code / check_account。

结果解读

| 返回 | 含义 | 建议 | |---|---|---| | ✅ 一致 (1000) | 核验通过 | 放行（该次已计费）| | ❌ 不一致 (1001) | 信息不匹配 | 拒绝或人工审核（已计费）| | ⚠️ 库中无此号 (1002) | 核验对象不存在 | 不计费，建议拒绝 | | code 11xx | 调用错误 | 见下方排错 |

排错速查

| 错误码 | 原因 | 修复 | |---|---|---| | 1101 | 商户 ID 不合法 | 检查 NZT_MALL_ID | | 1103 | 编码不合法 | 身份证末位 X 必须小写 | | 1104 | 签名不合法 | md5 按各接口文档字段顺序直接拼接（无分隔符），检查 appkey | | 1106 | 余额不足 | 控制台充值 | | 1107 | tm 不合法 | 须 13 位毫秒时间戳 | | 1108 | 参数异常 | 检查参数名与取值；若参数无误，确认该产品已在商户后台为本账户开通 | | 1109 | 账户被暂停 | 联系商务 |

注意：各接口签名拼接顺序不同（如银行卡三/四要素签名不含身份证号字段、短信签名不含 tm），以 API 文档为准，本脚本已内置正确规则。

红线（必须遵守）

仅限用户本人已授权的核验场景；禁止批量查询他人身份信息
不要在代码/日志中输出完整 NZT_APP_KEY
身份证号入参统一转小写 x、去首尾空格后再签名
结果属于个人敏感信息，不要在对话中长期保留原始身份证号