⑥ 散户改卡 / 注销
散户入驻后的维护:换收款银行卡、或注销(解绑收款人)。两个数据类接口。
属「工商银行 · 业务型接口」——底层编排 乐企直联原子接口,你只调这一个。
改卡
接口 · 改卡(数据类)
POST https://openapi.kailingteck.com/api/v1/rinv/seller/update-card
鉴权:X-App-Key + X-Timestamp + X-Sign(= sha256(appKey + 时间戳 + 报文 + appSecret))。
请求参数
| 字段 | 必填 | 大白话说明 |
|---|---|---|
userId | 必填 | 散户ID |
vendorId | 必填 | 服务商ID |
bankCard | 必填 | 新的收款卡号 |
bankName | 选填 | 开户行名称(非工行卡时填) |
bankCode | 选填 | 开户行联行号(非工行卡时填) |
请求示例
{
"userId": "U123",
"vendorId": "V1",
"bankCard": "6222000000000000",
"bankName": "中国银行苏州分行",
"bankCode": "104305000000"
}返回
所有接口都用同一层信封:code／msg／requestId／timestamp／data。业务字段都在 data 里,下表列的就是 data 的内容。code 为 CYT_00000 表示调用成功。
返回参数(data)
| 字段 | 大白话说明 |
|---|---|
userId | 回显散户ID |
result | 工行给的处理结果说明 |
raw | 工行原始全字段 |
返回示例(成功)
{
"code": "CYT_00000",
"data": {
"userId": "U123",
"result": "成功",
"mock": false,
"raw": { }
}
}异常与报错
| 情形 | 含义与处理 |
|---|---|
| 提示该银行账号存在审批中记录 | 工行按银行卡号去重。同一张卡上一笔还在审批中,等审完再改 |
| 提示请确认是否有待审核记录 | 该散户有待审核的记录,先等分行审完 |
前端怎么用
// 直接调,拿 data.result
注销
接口 · 注销(数据类)
POST https://openapi.kailingteck.com/api/v1/rinv/seller/close
鉴权:X-App-Key + X-Timestamp + X-Sign(= sha256(appKey + 时间戳 + 报文 + appSecret))。
请求参数
| 字段 | 必填 | 大白话说明 |
|---|---|---|
userId | 必填 | 散户ID |
vendorId | 必填 | 服务商ID |
请求示例
{
"userId": "U123",
"vendorId": "V1"
}返回
所有接口都用同一层信封:code／msg／requestId／timestamp／data。业务字段都在 data 里,下表列的就是 data 的内容。code 为 CYT_00000 表示调用成功。
返回参数(data)
| 字段 | 大白话说明 |
|---|---|
userId | 回显散户ID |
result | 工行给的处理结果说明 |
raw | 工行原始全字段 |
返回示例(成功)
{
"code": "CYT_00000",
"data": {
"userId": "U123",
"result": "成功",
"mock": false,
"raw": { }
}
}前端怎么用
// 解绑该散户
注销后该散户不能再收款开票,如需恢复要重新走②入驻。
所有接口通用的报错(平台层)
| 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 | 尚未配置工行凭据,返回的是演示数据、并未真调工行 |