接入文档 /红冲与作废/红冲 / 作废发票

红冲 / 作废发票

对已开具的蓝票发起红冲（电子发票、数电发票）或作废（纸质发票，由系统根据开票时间判断红冲还是作废）。接口同步受理，实际红冲异步完成，结果通过回调通知（红冲成功 / 作废成功 / 作废失败）推送，或用 color=red 查询红票。

POST/invoice/red

兼容路径：POST /invoice/nullify、POST /invoice-api/nullify。

请求参数

请求体为 JSON。

参数	类型	必填	说明
appKey	string	条件必填	服务密钥 Key，与 appSecret 成对使用；传了 accessToken 时可不传
appSecret	string	条件必填	服务密钥 Secret
accessToken	string	条件必填	访问令牌，通过获取访问令牌接口获取；传了 accessToken 则无需 appKey / appSecret
taxNumber	string	必填	企业纳税人识别号，指定本次操作的开票企业；必须是该密钥已关联的企业
invoices	array	必填	要红冲的发票列表，字段见下表
reason	string	选填	红冲 / 作废原因，数电发票可选：`开票有误`、`销货退回`、`服务中止`、`销售折让`
name	string	选填	操作人员名称
callbackUrl	string	选填	红冲结果回调地址，不传使用原蓝票的回调地址
outOrderNos	array	选填	旧版参数：外部订单号数组，整张红冲。与 `invoices` 二选一，建议使用 `invoices`
redSerialNo	string	选填	旧版参数：红字信息表编号，已废弃

invoices 元素字段

参数	类型	必填	说明
outOrderNo	string	条件必填	蓝票外部订单号，与 `invoiceId` 二选一
invoiceId	int	条件必填	蓝票发票 ID，与 `outOrderNo` 二选一
items	array	选填	部分红冲的明细行，不传则整张红冲；字段见下表
redSerialNo	string	选填	红字信息表编号（税控专票红冲时填写，数电发票无需）

items 元素字段（部分红冲）

参数	类型	必填	说明
origLineNumber	int	必填	对应蓝票明细的行号
name	string	必填	商品名称，与蓝票一致
no	string	选填	税收分类编码
model	string	选填	规格型号
unit	string	选填	单位
number	double	选填	本次红冲数量
price	decimal	选填	含税单价
sum	decimal	必填	本次红冲含税金额（正数，系统按红票取负）
taxRate	double	选填	税率
discount	decimal	选填	折扣金额
zeroRateFlag / preferentialPolicyFlag / preferentialPolicyName	-	选填	同开票明细

请求示例

整张红冲：

json

{
  "appKey": "你的appKey",
  "appSecret": "你的appSecret",
  "taxNumber": "91320211MA1WML8X6T",
  "reason": "销货退回",
  "name": "张三",
  "callbackUrl": "https://www.example.com/invoice/callback",
  "invoices": [
    { "outOrderNo": "ORDER20260101001" }
  ]
}

部分红冲：

json

{
  "appKey": "你的appKey",
  "appSecret": "你的appSecret",
  "taxNumber": "91320211MA1WML8X6T",
  "reason": "销售折让",
  "invoices": [
    {
      "outOrderNo": "ORDER20260101001",
      "items": [
        { "origLineNumber": 1, "name": "技术服务费", "number": 1, "price": 200, "sum": 200, "taxRate": 0.06 }
      ]
    }
  ]
}

响应示例

json

{
  "code": 1,
  "message": "提交成功"
}

业务规则

蓝票必须处于已开票状态（state == 1），否则返回 订单号 : xxx 关联发票记录不处于已开票状态。
电子 / 数电发票红冲中（redState == 1）或已红冲（redState == 2）的蓝票不能再次红冲；部分红冲后 redState 为 4。
红冲成功后蓝票 redState 变为 2，statements 为 已红冲，同一外部订单号可重新开具蓝票。
红票的外部订单号与蓝票相同，查询时传 color=red；红票对象的 parentInvoice 为原蓝票。
企业开启「是否测试环境」时，红冲走模拟流程。

错误信息

message	说明
请输入有效发票商户订单号（数组）	`invoices` 与 `outOrderNos` 都为空
订单号 : xxx 未找到关联发票记录	外部订单号不存在
订单号 : xxx 关联发票记录不处于已开票状态	蓝票未开票成功
订单号 : xxx正在红冲中 / 已红冲了	重复红冲
非法参数	`invoiceId` 不属于当前企业，或传入的是红票 ID