① 企业开通

回收企业(付款开票方)首次开通:拿到工行税务授权的跳转链接,企业法人去电子税务局扫码授权。一次性、超低频。页面类接口。

接口(页面类)

POST  https://openapi.kailingteck.com/api/v1/rinv/enterprise/open

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

请求参数

字段	必填	大白话说明
`vendorId`	必填	服务商ID(合作机构编号)
`leqiId`	选填	乐企机构号
`authType`	选填	授权人类型:01 法定代表人 / 02 财务负责人
`authNo`	选填	授权人证件号
`jumpUrl`	选填	授权完成后回跳你们页面的地址

请求示例

{
  "vendorId": "V1",
  "leqiId": "L1",
  "authType": "01",
  "authNo": "110101199001011234",
  "jumpUrl": "https://你们的页面"
}

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

返回参数(data)

字段	大白话说明
`pageUrl`	工行税务授权页的地址。前端直接跳过去,页面上有二维码给法人扫
`mock`	true=尚未配置工行凭据、返回的是演示数据;false=真调了工行

返回示例(成功)

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

异常与报错

情形	含义与处理
跳转页打开显示 MOCK 字样	尚未配置工行凭据,联系开灵配置后即为真实工行页面
法人扫码后提示无权限	扫码的人不是法定代表人或财务负责人,或没在电子税务局 App 里登录本企业

前端怎么用

location.href = res.data.pageUrl;   // 把法人带到工行托管的授权页

法人必须用「电子税务局」App 扫码(微信、工商银行 App 都扫不了)、刷脸、设授权有效期。授权完还要在电子税务局里手动下载一次发票,自动开票额度才生效——这一步最容易漏,漏了后面开票会一直失败。

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

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`	尚未配置工行凭据,返回的是演示数据、并未真调工行