接口参数怎么传：7 个端点的必填参数与签名字段对照
核验类与短信 7 个端点的必填参数、参与签名的字段、必填但不参与签名的字段一次列清。附参数名写错返回 1108 而非 1104、title 必填与 OpenAPI required 不一致等 5 个坑。
一句话结论
7 个接口的必填参数和参与签名的字段不是一回事:核验类 6 个端点里有 3 个、短信接口算 1 个,合计 4 个端点存在"必填但不参与签名"的字段——改这些字段,签名不变,服务端也不会报签名错,只会给你一个业务结论。参数传错要分三层看:参数名写错 → 1108 参数异常;值格式错 → 1103 编码不合法;只有参与签名的字段算错 → 1104 签名不合法。
7 个端点的必填参数和参与签名的字段分别是什么？
签名统一是 md5(按各接口文档固定顺序拼接业务字段 + tm + appkey),拼接不带分隔符。下面这张表把"必填"和"进签名"分开列——第 4 列是本文的重点。
| 端点 | 必填参数(除 sign) | 参与签名的业务字段 | 必填但不参与签名 |
|---|
| /v2/id-server | mall_id, realname, idcard, tm | realname, idcard | — |
|---|---|---|---|
| /phone/name | mall_id, realname, phone, tm | realname, phone | — |
| /phone/three-detail | mall_id, realname, idcard, phone, tm | realname, idcard | phone |
| /v3/card2-server | mall_id, realname, cardnum, tm | realname, cardnum | — |
| /v3/card3-server | mall_id, realname, idcard, cardnum, tm | realname, cardnum | idcard |
| /v3/card4-server | mall_id, realname, idcard, cardnum, bankPreMobile, tm | realname, cardnum | idcard、bankPreMobile |
| /sms.php | mall_id, phone, code, title | phone, code | title |
两点补充:
必填但不参与签名的字段,改错了会报签名错吗？
这是最容易被漏掉的一类。4 个端点里有 4 个字段必填却不进签名串。以银行卡四要素为例,idcard 与 bankPreMobile 都必填,但签名只算 5 个字段(mall_id + realname + cardnum + tm + appkey)。
后果是:把这两个参数的值改错,签名依然计算通过,服务端照常受理,然后返回一个业务结论——不会报 1104。联调时如果只看错误码,很容易误判成"接口没问题,是用户数据不对"。
同一组示例值本地复算(appkey 用示例值,换成你自己的即可复现):
银行卡四要素 正确签名(不含 idcard / bankPreMobile)
md5("100001"+"张三"+"6222021234567890123"+"1730000000000"+"test_appkey") = 59553c65d1e98cad3a1aa89cb51dc3c9
误把 idcard 拼进签名 md5("100001"+"张三"+"11010519491231002x"+"6222021234567890123"+"1730000000000"+"test_appkey") = e6a60ef8b04688ae1127b3aa7b38d3c2
误把 bankPreMobile 拼进签名 md5("100001"+"张三"+"6222021234567890123"+"13900139000"+"1730000000000"+"test_appkey") = 81093a54b7640ef94ed13932d02b9577
三个结果互不相同——这正是"多拼一个字段就 1104"的机制。反过来说,只要这两个字段的值和签名无关,改它们就不会触发 1104,所以参数值写错要靠"逐字核对请求参数"发现,不能等签名报错来提示你。
手机号三要素详版是同一个形状:phone 必填但不参与签名(签名 = mall_id + realname + idcard + tm + appkey)。
参数名写错了会返回 1108 还是 1104？
参数名的大小写和拼写属于参数层,不参与签名,所以写错不会报签名错。
银行卡四要素的预留手机号参数名固定是 bankPreMobile(大驼峰),写成 bankPremobile、mobile 或 phone,服务端会认为缺必填参数,返回 1108 参数异常。同样,证件号写成 idcard_no、卡号写成 card_no 也都落在 1108。
排查顺序上可以这样区分:
| 现象 | 落在哪一层 | 怎么改 |
|---|
| 1104 签名不合法 | 签名层 | 核对拼接顺序、是否多拼了不参与签名的字段 |
|---|---|---|
| 1108 参数异常 | 参数层 | 核对参数名拼写与大小写、必填项是否齐全 |
| 1103 编码不合法 | 值格式层 | 身份证末位 x、卡号空格与分隔符、手机号位数 |
短信的 title 参数到底要不要传？
短信接口的参数表把 title(模板固定内容)标为"是(必填)",同一行的说明却写着"可为空";而机器可读规格(openapi 的 SmsRequest)里,required 列表是 [mall_id, phone, code, sign],并不包含 title。
两份文档在同一处不一致,联调时先实测再下结论:直接按参数表把 title 传上去(传空串也可以),如果服务端报参数异常再按 required 列表去掉它。不要凭规格文件推断行为,也不要凭参数表推断——这类地方实测一次比读十遍文档快。
标题字段的定位要记住:它不参与签名(短信签名 = md5(mall_id + phone + code + appkey)),所以改 title 不用重算签名;真正参与签名的是 code(短信内容原文),改一个字都要重算。
身份证末位是 X 时要转成小写 x 吗？
证件号末位是 X 时必须转成小写 x,否则返回 1103。银行卡号要去掉空格与连字符,用纯数字;手机号用 11 位大陆号码,不带 +86 与空格。
这几个端点的值格式要求都能在各自接口文档的注意事项里找到。
短信接口可以直接发 JSON 请求体吗？
短信接口只接受 application/x-www-form-urlencoded 表单(或 GET 查询串);发 JSON 请求体不会被解析。核验类接口同样是表单编码。
另外短信签名不含 tm,核验类接口的 tm 是 13 位毫秒时间戳且必须与签名时用同一个值——这是两套签名规则最容易互串的地方。
上线检查单
相关阅读
关于诺正通
身份证、手机号、银行卡核验接口与短信验证码接口按量计费、面议,含 100 次免费试用用于联调,具体价格向商务询价。