跳到正文
开灵科技 - 北京开灵科技有限公司API百宝箱

⑨ 开票通知(结果回调)

老板付款成功后,工行会自动开票、缴税、上传,并把结果异步推送过来。开灵回调口收下后原样全字段存起来;你们前端轮询下面这个接口就能拿到,不用自己开回调口。

机制(一张图看懂)

老板付款成功
   └─(工行自动:开票+缴税+上传)
        └─(异步推送)─▶ 开灵回调口  https://openapi.kailingteck.com/api/callback/icbc
                          └─ 验签 + 原样全字段存下
你们前端 ──轮询──▶ /api/v1/icbc/invoice/notify-status  { outOrderId }  ──▶ 拿到工行通知全字段

回调口地址交给工行侧配置;你们只管轮询下面的查询接口。也可以用 ⑩ 查开票状态 主动去工行查(两条路都行)。

查开票通知接口

POST  https://openapi.kailingteck.com/api/v1/icbc/invoice/notify-status

鉴权:X-App-Key + X-Sign + X-Timestamp。请求参数:outOrderId(订单号,和下单/付款一致)。

返回(工行通知全字段 · 原样返回)

工行通知字段很多、且随 notifyType 不同而不同,开灵原样全字段返回(不挑不改)。常用字段:

字段大白话说明
received开灵加的:是否已收到工行通知(false=还没收到)
notifyType通知类型:02-支付 / 03-开票 / 04-缴税 / 05-发票上传 / 06-发票取消 / 07~09-红票 / 11-货款到期 …
outOrderId订单号
outVendorId收方(散户)编号
outUserId付方(企业)编号
invoiceCode发票号码
payAmount合计金额(票面含税)
taxAmount合计税额
confirmStatus自然人确认状态:00-未确认 / 01-已确认
payStatus支付状态:02-成功 …(工行字典)
invoiceStatus开票状态:02-开票成功 …
uploadStatus发票上传状态:04-上传成功 …
taxStatus缴税状态:04-缴税成功 …

完整字典以工行《银税协同通知报文说明》为准;返回里的字段以工行实际推送为准。未收到通知时返回 { received: false }。

前端用法(轮询)

const r = await klPost('/api/v1/icbc/invoice/notify-status', { outOrderId });
if (!r.data.received) { /* 还没收到,稍后再查 */ }
else if (r.data.invoiceStatus === '02') { /* 开票成功 */ }