② 散户入驻(发起扫脸)

自然人(卖废品的散户)入驻第一步:发起工行刷脸实人认证,拿到扫脸链接给散户本人刷脸。页面类接口。

接口(页面类)

POST  https://openapi.kailingteck.com/api/v1/rinv/seller/onboard

鉴权:X-App-Key + X-Timestamp + X-Sign(= sha256(appKey + 时间戳 + 报文 + appSecret))。

请求参数

字段	必填	大白话说明
`userId`	必填	你侧散户唯一ID(后续所有接口都用它当钥匙)
`name`	必填	散户姓名
`idNo`	必填	身份证号
`phone`	选填	手机号(认证过程中发短信验证码)
`jumpUrl`	选填	刷脸完成后回跳地址

请求示例

{
  "userId": "U123",
  "name": "张三",
  "idNo": "110101199001011234",
  "phone": "13800000000",
  "jumpUrl": "https://你们的页面"
}

所有接口都用同一层信封:code／msg／requestId／timestamp／data。业务字段都在 data 里,下表列的就是 data 的内容。code 为 CYT_00000 表示调用成功。

返回参数(data)

字段	大白话说明
`pageUrl`	工行实人认证(刷脸)页地址,让散户本人打开
`transNo`	本次认证的流水号。务必存下来——查③散户状态时要用它取实名结果
`mock`	true=演示数据;false=真调了工行

返回示例(成功)

{
  "code": "CYT_00000",
  "msg": "success",
  "requestId": "cyt_xxx",
  "data": {
    "pageUrl": "https://openapi.kailingteck.com/api/v1/icbc/redirect/rxxx",
    "transNo": "T1786630352940",
    "mock": false
  }
}

异常与报错

情形	含义与处理
散户刷脸失败	常见原因:光线不足、动作不到位、本人信息与身份证不一致。可重新调本接口再发起一次
没存 transNo	查实名结果只能靠 transNo,丢了就得让散户重新刷一次脸

前端怎么用

location.href = res.data.pageUrl;   // 散户去工行页面刷脸
save(res.data.transNo);             // 存下 transNo,查③状态要用

扫脸是异步的:散户在工行页面刷完,你再用 transNo 调③查实名结果,不会自动推回来。

所有接口通用的报错(平台层)

HTTP / code	含义与处理
`400 · CYT_40001`	必填参数没传,data.hint 里写了缺哪个
`401 · CYT_40100 / 40102`	缺鉴权头,或签名算错。签名 = sha256(appKey + 时间戳 + 报文原文 + appSecret),参与签名的报文必须与实际发送的逐字节一致
`401 · CYT_40103`	时间戳与服务器相差超过 300 秒,校准本机时间后重试
`403 · CYT_40301`	这把密钥的产品或渠道不对(工行接口需要「反向开票」产品 + 「工商银行」渠道)
`429 · CYT_42901`	超过每分钟 120 次限流,稍后重试
`502 · CYT_50200`	工行侧暂时不可达。注意工行测试环境每晚 19:00 后关闭、次日恢复,联调请排在工作时间
`200 · data.mock=true`	尚未配置工行凭据,返回的是演示数据、并未真调工行