③ 红冲

开错了、退货了，用它把原票冲掉。★这是一键接口——申请红字信息表、下载信息表、开红票三步已经合成在里面，你只调这一个就完事。★数电票开出即入库，没有「作废」这回事，只能红冲。

属「正向开票 · 腾讯联用」——开票通道的签名与加密全在开灵中台，你只调这一个。

接口

POST  https://openapi.kailingteck.com/api/v1/invoice/forward/red

鉴权：X-App-Key ＋ X-Timestamp（Unix 秒）＋ X-Sign（＝ sha256(appKey ＋时间戳＋报文原文＋ appSecret) 小写十六进制）。与开灵其它接口完全一致。

请求参数

字段	必填	大白话说明
`invoices[]`	必填	红冲发票信息列表，支持一次冲多张
`invoices[].seller_taxpayer_num`	必填	销方税号
`invoices[].order_id`	二选一	原蓝票的订单号（你开票时传的）
`invoices[].order_sn`	二选一	原蓝票的通道受理号。★两个都传时以 order_sn 为准
`invoices[].apply_reason`	必填	★申请原因，是代码不是文字：2 开票有误（购方拒收／尚未交付）／3 销货退回／4 服务中止／5 销售折让。传空默认 2。⚠ 实测写成「开票有误」这种自由文本会被拒：「全电发票红冲原因不合法」。全电发票只支持销方申请
`invoices[].callback_url`	必填	红冲结果回传地址，推送格式同②的开票结果回调（notify_type 为 invoice.red）
`invoices[].red_serial_no`	选填	红字信息表编码。★走一键红冲用不到；只有纸质专票红冲才需要自己先申请信息表再填这里
`invoices[].confirm_info_uuid`	选填	红字确认单 uuid。★同上，一键红冲不用填
`invoices[].confirm_info_state`	选填	红字确认信息状态代码，如 01。★一键红冲不用填
`invoices[].special_element_code`	选填	特定要素代码，如 08。★一键红冲不用填
`invoices[].tax_to_ele_channel`	选填	税控发票走数电通道红冲时填 1，默认 0。★一键红冲不用填

请求示例

{
  "invoices": [
    {
      "seller_taxpayer_num": "91110119MABQDU249D",
      "order_id": "REG1788017096448",
      "apply_reason": "2",
      "callback_url": "https://openapi.kailingteck.com/api/callback/gaodeng"
    }
  ]
}

统一信封 code／msg／requestId／timestamp／data，业务字段都在 data 里。code 为 CYT_00000 表示调用成功。

返回参数（data）

字段	大白话说明
`list`	★返回是数组，放在 data.list 下。一次冲多张时逐条对应，顺序与请求里的 invoices 一致
`list[].state`	★红冲状态：1 已提交成功（红票还没到手，要再查）/ 3 提交失败或已红冲过
`list[].message`	提交红冲的说明。state=3 时这里是原因
`list[].order_sn`	原蓝票的通道受理号
`list[].invoice_id`	红票的唯一标识

返回示例（成功）

{
  "code": "CYT_00000",
  "msg": "success",
  "data": {
    "list": [
      {
        "state": 1,
        "message": "success",
        "order_sn": "7499487274632001743",
        "invoice_id": "7499487521907153138"
      }
    ],
    "mock": false
  }
}

异常与报错

情形	含义与处理
原票不存在或未开成功	只有开票成功（status=3）的票才能红冲
已红冲过	查②看 is_red_washed 是否已为 1，不要重复冲
state=3「全电发票红冲原因不合法」	★apply_reason 传了自由文本。必须传代码 2／3／4／5，传空默认 2
调完红冲但没拿到红票	★正常。本接口只负责提交，红票要用 /api/v1/invoice/forward/red-query 再查一次，或等 callback_url 推送——和开票 ①→② 是一个道理
红票迟迟查不到，以为失败了	★红冲比开票慢得多。开灵实测：开票约 6 秒出票，红冲约 48 秒才出红票号。查红冲请按 8 秒一次、留 6~8 次余量；照开票的 3~5 秒节奏去等，会误判成失败进而重复提交红冲

前端怎么用

const r = await post('/api/v1/invoice/forward/red', {
  invoices: [{ seller_taxpayer_num, order_id, apply_reason: '2', callback_url }]
});
if (r.data.list[0].state !== 1) throw new Error(r.data.list[0].message);
// 一键完成申请信息表→下载→红冲三步；结果走回调，或用 red-query 查

★联调脚本：仓库 scripts/e2e-forward.js 跑一遍 ①→②→③→④ 全链路（APP_KEY=xxx APP_SECRET=xxx node scripts/e2e-forward.js）。★这是一键接口：上游把「申请红字信息表 + 自动下载信息表 + 红冲」三个动作合成了，你不用自己走三步。但★红冲和开票是同一个套路——本接口只是「提交」，返回 state=1 表示已受理，红票本身还没到手，要么等回调推送、要么用 /api/v1/invoice/forward/red-query 再查一次。红冲成功后原蓝票的 is_red_washed 会变成 1。

← ② 查开票结果④ 查红票 →