2.1.04 数电票红冲（直接红冲或通过红字确认单）

快速开始环境

https://cosmic-sandbox.piaozone.com/jdpjykjyxgs

POST

/kapi/app/sim/openApi

接口说明

红冲先后顺序说明
1、流水号在待开发票列表存在，则直接匹配数据红冲
2、存在明细匹配组装明细红冲（发票云版本5.0.024支持）
3、乐企且存在红字确认单编号（发票云版本5.0.024支持）
4、根据红字确认单编号和UUID查找存量确认单数据红冲
5、根据原蓝票号码查询存量蓝票数据录入提交生成红字确认单全额红冲

本接口可自动申请红字确认单，当确认单状态为无需确认时，自动根据红字确认单红冲，开具红票，发票开具完成后，可通过2.1.02数电票回调接口回调发票数据；当确认单状态为待对方确认等异常状态，则将状态返回，不开具发票。
注意：本接口调用后，原蓝票将自动红冲，红字确认单无法关联至负数开票申请单。

部分红冲匹配原蓝票明细规则（2选1）：

明细直接传 originaldetailRowNo 匹配到原蓝票明细

明细发票云比对接口传值与蓝票明细自动匹配行序号，匹配字段包含：商品名称+税收分类编码+税率+不含税单价（红冲原因为销售折让时，可不根据单价匹配）

验证方法

验证接口返回编码91401
1、带明细行的数据验证，发票号码需要符合：066574780154360003开头，确认单状态结尾（状态值参考上面的参数）如：066574780154360003XXXX03
2、原蓝originaldetailRowNo需要修改数据库的发票号码。发票号码需要符合：066574780154360003开头，确认单状态结尾（状态值参考上面的参数）如：066574780154360003XXXX03

验证回推返回91401
1、确认单编号验证：需要先在系统生成对应的红字确认单，然后修改红字确认单编号为：066574780154360004开头，确认单状态结尾（状态值参考上面的参数）如：066574780154360004XXXX03
2、原蓝票红冲校验：需要先在系统生成对应的红字确认单，然后修改原蓝票号码为：066574780154360001开头，确认单状态结尾（状态值参考上面的参数）如：066574780154360001XXXX03

税局业务规则

备注

数电票红冲的规则较为复杂，建议对接者对接前先阅读底下文档：https://jdpiaozone.yuque.com/nbklz3/sszola/edhu9lhwt2kq46sv

部分红冲说明
金税四期数电发票全额红冲、部分红冲规则：红冲时，需要先申请红字确认单，且必须关联至原蓝票、原蓝票明细行序号才可以进行红冲。

税局规则：
1、~~数电票在购买方将蓝字发票勾选或入账后，销售方才可以发起部分红冲~~；当购买方未勾选未入账时，仅能由销售方发起全额红冲。
更新补充：税局最新规则，购方未勾选未入账等未使用蓝票的情形，支持进行部分红冲、全额红冲，红冲时，不需要对方确认。---更新时间：2024.9.20
2、税局的四种红冲原因，开票有误仅支持全额红冲，其他三种支持全额红冲、部分红冲，部分红冲时，原则上单价不允许变更。

请求参数

Query 参数

access_token

string

可选

{access_token}

示例值:

1107974180231447552_L3nqi9yB42ysU25QKA2Z6qgxT3blIVYsp9Nr1eLbP9B63o4Pjb3177JC7544rQ0dgNCgwLEfI92NHbAaM5Cdxz1rsQwF9u1ANbDI

Header 参数

access_token

string

可选

默认值:

Body 参数application/json

requestId

string

时间戳

必需

当前13位毫秒级时间戳加3位随机数字(总共16位)

businessSystemCode

string

对接业务系统来源编码

必需

对接业务系统来源编码

interfaceCode

enum<string>

接口业务编码

必需

固定值： ALLE.INVOICE.RED

枚举值:

ALLE.INVOICE.RED

data

object

必需

需要把data里面的base64字符串解密

serialNo

string

流水号

必需

由对接者定义及保障全局唯一性，【长度：50】

<= 50 字符

invoiceCode

string

原蓝票代码

可选

原蓝字发票代码【长度：20字节】，原蓝票为税控发票时必填

<= 20 字符

invoiceNum

string

原蓝票号码

必需

要红冲的蓝票号码，优先以这个为准；同时也支持旧字段invoiceNo【长度：20字节】

<= 100 字符

originalIssueTime

string

原蓝票时间

可选

格式：YYYY-MM-DD HH:MM:SS

originalInvoiceAmount

number

原蓝票金额(不含税)

可选

【长度：(14,2)】

originalTotalTaxAmount

number

原蓝票税额

可选

【长度：(14,2)】

redReason

enum<string>

红冲原因

必需

红冲原因, 申请时已经确定

枚举值:

01020304

默认值:

govRedConfirmBillUuid

string

税局确认单uuid

可选

1、当已申请红字确认单，绑定红字确认单开票时，govRedConfirmBillUuid 和 redInfoBillNo 二选一必填，填写后将根据红字确认单开具发票。
2、红字确认单必须在发票云存在，如不存在请先下载至发票云，发票云-基础资料-开票参数设置-自动化设置可以配置自动下载红字确认单任务。

<= 50 字符

redInfoBillNo

string

红字确认单编号

可选

<= 50 字符

account

string

数电账号

可选

数电票时可以传入，非数电传入会清空，如传入则使用传入的数电账号，未传入时，使用默认数电账号，发票云版本7.0可用

<= 50 字符

drawer

string

开票人

可选

1、使用乐企开票时，必传，可展示为传输的开票人。
2、使用数电账号开票时，不传，票面的开票人展示为数电账号绑定的开票人名称，不按传输开票人展示；
3、7.0版本以上支持

<= 16 字符

invoiceType

enum<string>

发票种类

必需

枚举值:

0102

orgCode

string

组织编码

可选

可以不传，会通过销方税号自动匹配，一个税号分配给多个组织使用的必须要传组织【长度：20】

<= 20 字符

sellerName

string

销方名称

可选

【GBK编码100字节】，如果在星瀚有配置企业信息可不填，

<= 100 字符

sellerTaxpayerId

string

销方税号

可选

组织和销方税号二选一

<= 20 字符

sellerBank

string

销方银行

可选

【销方银行+银行账号 GBK编码150字节】

<= 150 字符

sellerBankAccount

string

销方银账号

可选

【销方银行+银行账号 GBK编码150字节】

<= 150 字符

sellerAddress

string

销方地址

可选

【销方地址+销方电话 GBK编码120字节】

<= 120 字符

sellerTel

string

销方电话

可选

【销方地址+销方电话 GBK编码120字节】

<= 120 字符

buyerName

string

购买方名称

可选

【长度：GBK编码100字节】

<= 100 字符

buyerTaxpayerId

string

购买方税号

可选

（专票必填）【长度：20】

<= 20 字符

buyerBank

string

购买方银行

可选

【购买方银行+购买方银行账号 150字节】

<= 150 字符

buyerBankAccount

string

购买方银行账号

可选

【购买方银行+购买方银行账号 150字节】

<= 150 字符

buyerAddress

string

购买方地址

可选

【购买方地址+购买方电话 120字节】

<= 120 字符

buyerTel

string

购买方电话

可选

【购买方地址+购买方电话 120字节】

<= 120 字符

specialType

enum<string>

特定要素

可选

默认为空。空：非特定要素；01：成品油发票；02：稀土发票；03：建筑服务发票；04：货物运输服务发票；05：不动产销售服务发票；06：不动产租赁服务发票；07：代收车船税；08：通行费；09：旅客运输服务发票；10：医疗服务（住院）发票；11：医疗服务（门诊）发票；12：自产农产品销售发票；13：拖拉机和联合收割机发票；14：机动车；15：二手车；16：农产品收购发票；17：光伏收购发票；18：卷烟发票

枚举值:

null01E0203040506070809101112131415021718

默认值:

null

buyerRecipientPhone

string

电子发票收票手机号

可选

【长度：50；最多三个手机号】

<= 50 字符

buyerRecipientMail

string

电子发票收票邮箱

可选

【长度：GBK编码100字节】

<= 100 字符

naturalPersonFlag

enum<string>

自然人标识

可选

默认根据购方纳税人识别号取反，税号有值时自然人标识为N，税号无值时自然人标识为Y

枚举值:

invoiceDetail

array [object {14}]

明细

可选

明细,全额红冲时不传，将自动获取蓝票在发票云的明细信息，部分红冲时传输，部分红冲匹配原蓝票明细规则（2选1）：

明细直接传 originaldetailRowNo 匹配到原蓝票明细

明细发票云比对接口传值与蓝票明细自动匹配行序号，匹配字段包含：商品名称+税收分类编码+税率+不含税单价（红冲原因为销售折让时，根据单价未找到可匹配蓝票明细，可再不根据单价匹配，即商品名称+税收分类编码+税率匹配）

示例

{
    "requestId": "string",
    "businessSystemCode": "string",
    "interfaceCode": " ALLE.INVOICE.RED",
    "data": {
        "serialNo": "string",
        "invoiceCode": "string",
        "invoiceNum": "string",
        "originalIssueTime": "string",
        "originalInvoiceAmount": 0,
        "originalTotalTaxAmount": 0,
        "redReason": "01",
        "govRedConfirmBillUuid": "string",
        "redInfoBillNo": "string",
        "account": "string",
        "drawer": "string",
        "invoiceType": "01",
        "orgCode": "string",
        "sellerName": "string",
        "sellerTaxpayerId": "string",
        "sellerBank": "string",
        "sellerBankAccount": "string",
        "sellerAddress": "string",
        "sellerTel": "string",
        "buyerName": "string",
        "buyerTaxpayerId": "string",
        "buyerBank": "string",
        "buyerBankAccount": "string",
        "buyerAddress": "string",
        "buyerTel": "string",
        "specialType": "null",
        "buyerRecipientPhone": "string",
        "buyerRecipientMail": "string",
        "naturalPersonFlag": "Y",
        "invoiceDetail": [
            {
                "lineProperty": "0",
                "originalSeq": 0,
                "originaldetailRowNo": "string",
                "billSourceId": "string",
                "goodsCode": "string",
                "goodsName": "string",
                "revenueCode": "string",
                "specification": "string",
                "units": "string",
                "quantity": 0,
                "price": 0,
                "amount": 0,
                "taxRate": 0,
                "taxAmount": 0
            }
        ]
    }
}

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://cosmic-sandbox.piaozone.com/jdpjykjyxgs/kapi/app/sim/openApi?access_token=1107974180231447552_L3nqi9yB42ysU25QKA2Z6qgxT3blIVYsp9Nr1eLbP9B63o4Pjb3177JC7544rQ0dgNCgwLEfI92NHbAaM5Cdxz1rsQwF9u1ANbDI' \
--header 'access_token: {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "requestId": "string",
    "businessSystemCode": "string",
    "interfaceCode": " ALLE.INVOICE.RED",
    "data": {
        "serialNo": "string",
        "invoiceCode": "string",
        "invoiceNum": "string",
        "originalIssueTime": "string",
        "originalInvoiceAmount": 0,
        "originalTotalTaxAmount": 0,
        "redReason": "01",
        "govRedConfirmBillUuid": "string",
        "redInfoBillNo": "string",
        "account": "string",
        "drawer": "string",
        "invoiceType": "01",
        "orgCode": "string",
        "sellerName": "string",
        "sellerTaxpayerId": "string",
        "sellerBank": "string",
        "sellerBankAccount": "string",
        "sellerAddress": "string",
        "sellerTel": "string",
        "buyerName": "string",
        "buyerTaxpayerId": "string",
        "buyerBank": "string",
        "buyerBankAccount": "string",
        "buyerAddress": "string",
        "buyerTel": "string",
        "specialType": "null",
        "buyerRecipientPhone": "string",
        "buyerRecipientMail": "string",
        "naturalPersonFlag": "Y",
        "invoiceDetail": [
            {
                "lineProperty": "0",
                "originalSeq": 0,
                "originaldetailRowNo": "string",
                "billSourceId": "string",
                "goodsCode": "string",
                "goodsName": "string",
                "revenueCode": "string",
                "specification": "string",
                "units": "string",
                "quantity": 0,
                "price": 0,
                "amount": 0,
                "taxRate": 0,
                "taxAmount": 0
            }
        ]
    }
}'

返回响应

🟢200成功

application/json

Body

message

string

可选

errorCode

string

必需

返回状态码 0：成功 91401：红字确认单状态不支持红冲

data

object

必需

redInfoBillNo

string

可选

红字确认单编号。本字段在如下情况下才会返回：errorCode编码为：91401(表示确认单当前状态不支持直接红冲）

govRedConfirmBillUuid

string

可选

红字确认单UUID。本字段在如下情况下才会返回：errorCode编码为：91401(表示确认单当前状态不支持直接红冲）

redConfirmBillStatus

enum<string>

可选

红字确认单状态。本字段在如下情况下才会返回：errorCode编码为：91401(表示确认单当前状态不支持直接红冲）

枚举值:

01020304050607080910

riskInfo

array [object {2}]

可选

风控信息。当错误编码(errorCode)为30001时，存在当前节点数据。发票云版本6.0.6支持。如需解除风控，请调用6.0.01 风控解除接口。

示例

{
"message": "生成成功",
"errorCode": "0",
"success": true
}

🟢200失败

修改于 2025-07-08 06:50:23

2.1.03 红字确认单生成

2.1.05 授信额度查询

2.1.04 数电票红冲（直接红冲或通过红字确认单）

接口说明#

验证方法#

税局业务规则#

请求参数

示例代码

返回响应

接口说明

验证方法

税局业务规则