手机号三要素核验返回 1003/1004/1005：哪一项不一致怎么判、计费与处置

调用手机号三要素核验（详版）接口 /phone/three-detail 时，三项不是全对也不会只回一句“不一致”：接口用 1003 / 1004 / 1005 指明是哪一项对不上。1003 = 手机号和姓名一致、证件号不一致；1004 = 只有手机号一致（证件号和姓名都不一致）；1005 = 手机号和证件号一致、姓名不一致。这三个码都计费，1002（系统无记录）不计费。读返回永远是两步：先看 status（服务状态），再看 data.code（业务结果）。

一、三个码差在哪：对照表

code	手机号	姓名	证件号	含义	计费

1000	✅	✅	✅	一致	计费
1001	—	—	—	不一致（不细分到项）	计费
1002	—	—	—	系统无记录	不计费
1003	✅	✅	❌	姓名对、证件号错	计费
1004	✅	❌	❌	只有手机号对	计费
1005	✅	❌	✅	证件号对、姓名错	计费

1001 的处置口径是“三项均不匹配”，但返回本身不细分；要细分就用详版的 1003–1005。注意三个部分一致码照样扣费：它们是已出结果，不是中间态。

二、坑 1：1003 在两个接口上是两回事

同一个 1003，含义与计费都不同：

接口	1003 的含义	计费

身份证 /v2/id-server、银行卡 /v3/card*	第三方服务异常，稍后再试	不计费
手机号三要素详版 /phone/three-detail	手机号和姓名一致、证件号不一致	计费

写一个公共的 handleCode() 按 code 全局分支，在详版上会把“用户证件号填错了”当成“第三方异常，稍后重试”——重试一次再扣一次费，用户看到的还是系统繁忙。解析表要按接口（endpoint）建，不要按 code 建。

三、参数速览与签名坑

项	值

请求地址	POST / GET https://api2.nztapi.com/phone/three-detail
必填参数	mall_id、realname、idcard、phone、tm、sign
签名公式	md5(mall_id + realname + idcard + tm + appkey) —— 不含 phone
证件号	末位 X 转小写 x
tm	13 位毫秒时间戳，签名与请求用同一个值
返回结构	{"data":{"code":"...","message":"..."},"status":"2001"}

坑 2：签名串里没有 phone。 按“三个参数都参与签名”的直觉拼，必然 1104。同一组示例值实测（appkey 用示例值，换成你自己的即可复现）：

正确  md5("100001"+"张三"+"11010519491231002x"+"1730000000000"+"test_appkey")
      = b3b51b28b9368489d520b9af8b492c81 拼了 phone       md5("100001"+"张三"+"11010519491231002x"+"13800138000"+"1730000000000"+"test_appkey")       = 9ec7822754bf8e9b9427da0ffbb11a03

两次结果不同 = 服务端拿到的 sign 对不上 = 1104。注意手机号二要素 /phone/name 的签名反而含 phone、不含 idcard——两个接口的字段清单不能互抄。

坑 3：tm 的参数表中文名写的是“随机数字”，说明栏却是“当前毫秒数（13 位）”。 照字面真随机生成会返回 1107 tm 参数不合法；按 13 位毫秒时间戳传，并且签名时与发送时用同一个值。

坑 4：部分一致也计费，所以不要重试。 1003/1004/1005 是核验结论，重试不会改变事实，只会再扣一次。值得退避重试的只有 1105、1110 这类超时码。

坑 5：status 与 data.code 正交。 status=2002（第三方服务器异常）时，即使 code=1000 也可能需要复核；只判 code 会漏掉服务侧异常。

四、排查顺序

status ≠ 2001 → 服务侧问题，先别动业务数据

1104 → 查签名：拼接顺序、是否误拼 phone、末位 x 是否小写

1107 → 查 tm：13 位毫秒、签名与请求同值

1103 → 查姓名 / 证件号 / 手机号的格式与编码

1002 → 数据源无记录，不计费，可转人工核对

1003/1004/1005 → 已出结论且计费，按处置表走，不重试

1001 → 不一致，计费，拦截或转人工复核

五、风控处置表

返回	建议动作

1000	放行
1003	提示核对证件号后重试一次，或降级为二要素并转人工
1004	高风险：拦截并二次验证
1005	高风险：拦截
1001 / 1002	拦截

六、上线检查单

[ ] 签名函数按 endpoint 分开，不复用身份证接口的字段列表

[ ] 末位 x 小写后再参与签名与请求

[ ] tm 是 13 位毫秒，签名与请求用同一个值

[ ] 解析层按 endpoint 建表：1003 在两个接口上是两回事

[ ] 只有 status=2001 才读 data.code

[ ] 1003/1004/1005 不重试；1105/1110 才退避重试

[ ] 计费告警按码分类：1002 不计费，1003–1005 计费

七、合规

核验结果连同姓名、证件号、手机号都属于个人信息：按《个人信息保护法》（2021 年施行）的最小必要原则，业务侧只留结论与工单号，不落原始证件影像；留存期限按业务需要，按《数据安全法》（2021 年施行）的分类分级要求确定。

相关阅读

手机号实名认证怎么验：二要素与三要素的区别：什么时候用详版、什么时候用二要素

身份证核验显示不一致？五步排查顺序：格式全对仍不一致时的下一步

错误码详解：1000-1110 全码表：参数码、鉴权码、账户码的完整区分

API 签名机制一篇讲透：md5 拼接顺序与 1104 的通用排查

通用接入规范（签名 / 鉴权 / 错误码）：各接口签名顺序表

关于诺正通

手机号三要素核验按量计费、面议，含 100 次免费试用用于联调，具体价格向商务询价。