5.1.02回调接口-按票回调(一次回调一张发票信息)

快速开始环境

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

POST

/：忽略该接口前缀，此为对接发票云方提供的回调地址（对接方必须按照成功响应示例报文返回 json ）

默认开票回调方式。每开一张发票就回调一次一个开票申请单如果拆分开具了N张发票，在发票开具成功后，根据发票张数，会回调N次。

请求参数

Header 参数

access_token

string

可选

默认值:

Body 参数application/json

interfaceCode

string

业务编码

必需

业务编码，开票回调是INVOICE.OPEN，作废回调是INVOICE.CANCEL，红冲回调是INVOICE.RED，发票回填回调是FILLIN

returnCode

string

返回编码

必需

0-成功 9999-失败

returnMsg

string

返回信息

必需

开票失败原因，成功返回 success

data

object

按票回调请求参数

必需

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

batch

string

批次号

必需

批次号

<= 50 字符

billNo

string

单据编号

必需

单据编号

<= 50 字符

invoiceProperty

number

开票类型

必需

开票类型，0蓝票，1红票【长度：1】

invoiceType

enum<string>

发票种类

必需

发票种类

枚举值:

02802600400702508xdp10xdp

buyerProperty

number

购买方性质

必需

[购方]购买方性质，0-企业，1-个人

buyerName

string

购买方名称

必需

[购方]购买方名称

<= 100 字符

buyerTaxpayerId

string

购买方税号

必需

[购方]购买方税号

<= 20 字符

buyerAddressAndTel

string

购买方地址和电话

必需

[购方]购买方地址和电话，GBK编码100字节，开专票时若未传入则用名称匹配系统维护的地址电话【长度：100】

buyerBankAndAccount

string

购买方银行和账号

必需

[购方]购买方银行和账号，GBK编码100字节，开专票时若未传入则用名称匹配系统维护的银行和账号【长度：100】

buyerRecipientMail

string

购买方邮箱

必需

[购方/交付]电子发票收票邮箱

<= 80 字符

buyerRecipientPhone

string

购买方手机号

必需

[购方/交付]电子发票收票手机号

deduction

number

差额征税差额

必需

[税]差额征税差额【长度：(14,2)】

includeTaxFlag

number

含税标识

必需

[税]含税标识，0-不含税，1-含税【长度：1】

totalTaxAmount

number

合计税额

必需

[税]合计税额

totalAmount

number

合计金额

必需

[税]合计金额

includeTaxAmount

number

价税合计

必需

[税]价税合计

taxedType

number

征税方式

必需

[税]征税方式，0-普通 2-差额

sellerName

string

销方名称

必需

[销方]销方名称

<= 100 字符

sellerTaxpayerId

string

销方税号

必需

[销方]销方税号

<= 20 字符

sellerAddressAndTel

string

销方地址和电话

必需

[销方]销方地址和电话

<= 120 字符

sellerBankAndAccount

string

销方银行和账号

必需

[销方]销方银行和账号

<= 120 字符

inventoryMark

string

清单标志

必需

[销方]清单标志，0-非清单发票，1-清单发票【长度：1】

drawer

string

开票人

必需

[销方]开票人【长度：10】

reviewer

string

复核人

必需

[销方]复核人【长度：10】

payee

string

收款人

必需

[销方]收款人【长度：10】

canceler

string

作废人

必需

[销方]作废人

<= 10 字符

abolishReason

string

作废原因

必需

[销方]作废原因

<= 50 字符

deviceNo

string

设备编号

必需

[销方]设备编号

remark

string

备注

必需

备注，GBK编码230字节【长度：230】

invoiceStatus

string

发票状态

必需

发票状态 0-正常 2-部分红冲 3-红冲 6-作废

invoiceCode

string

发票代码

必需

发票代码

<= 50 字符

invoiceNum

string

发票号码

必需

发票号码

<= 50 字符

invoiceDate

string

开票日期

必需

开票日期

invoiceDetail

array [object {18}]

发票明细

必需

发票明细

invoiceFileUrl

string

版式文件下载地址

必需

版式文件下载地址，航信百旺税盘开普通电票为PDF文件，开电子专票为ofd文件，ukey开电票都是ofd文件，数电票为ofd文件

<= 200 字符

invoiceImageUrl

string

PDF转图片预览地址

必需

PDF转图片预览地址

<= 200 字符

invoicePdfFileUrl

string

数电票PDF地址

必需

数电票pdf地址，星瀚版本5.0.022支持

<= 200 字符

invoiceXmlFileUrl

string

数电票XML地址

必需

数电票xml地址，星瀚版本5.0.022支持

<= 200 字符

orderNo

string

发票流水号

必需

发票流水号

<= 50 字符

originalInvoiceCode

string

原蓝票发票代码

可选

原蓝票发票代码，开红票必传【长度：12】

originalInvoiceNumber

string

原蓝票发票号码

可选

原蓝票发票号码，开红票必传【长度：8】

originalInvoiceStatus

string

原蓝票状态

可选

原蓝票状态，红冲、回调时存在，红冲回调为3、作废回调为6

originalIssueTime

string

原蓝票开票时间

可选

原蓝票开票时间，红冲、回调时存在，格式为"yyyyMMdd"

printFlag

string

纸票打印标识

必需

纸票打印标识，0-未打印 1-已打印

redInfoBillNo

string

红字信息表编号

必需

红字信息表编号，专用发票红冲必传【长度：16】

serialNo

string

序列号

必需

序列号【拆分合并后重新生成的编号】

<= 50 字符

systemSource

string

系统来源

必需

系统来源

<= 50 字符

terminalNo

string

终端号码

必需

终端号码

<= 50 字符

checkCode

string

校验码

必需

校验码

<= 50 字符

skm

string

密码区

必需

密码区

<= 500 字符

bizControl

object

开票业务管控额度预警

可选

开票业务管控额度预警

issueBizType

string

企业业务管控编码

必需

企业业务管控编码，企业在发票云旗舰版设置的企业开票业务管理编码

bizType

string

业务类型编码

必需

业务类型编码，企业在发票云旗舰版设置的开票业务类型编码

monthSurplusLimit

number

月剩余额度

必需

月剩余额度，企业每月电子税局可开票额度的剩余额度

daySurplusLimit

number

每日剩余额

必需

每日剩余额，企业某业务上设置每日可开票额度的剩余额度

isWarning

boolean

是否已超过月预警阈值

必需

是否已超过月预警阈值，当前开票额度达到企业设置的每月电子税局开票额度预警阈值

示例

{
    "interfaceCode": "string",
    "returnCode": "string",
    "returnMsg": "string",
    "data": {
        "batch": "string",
        "billNo": "string",
        "invoiceProperty": 0,
        "invoiceType": "028",
        "buyerProperty": 0,
        "buyerName": "string",
        "buyerTaxpayerId": "string",
        "buyerAddressAndTel": "string",
        "buyerBankAndAccount": "string",
        "buyerRecipientMail": "string",
        "buyerRecipientPhone": "string",
        "deduction": 0,
        "includeTaxFlag": 0,
        "totalTaxAmount": 0,
        "totalAmount": 0,
        "includeTaxAmount": 0,
        "taxedType": 0,
        "sellerName": "string",
        "sellerTaxpayerId": "string",
        "sellerAddressAndTel": "string",
        "sellerBankAndAccount": "string",
        "inventoryMark": "string",
        "drawer": "string",
        "reviewer": "string",
        "payee": "string",
        "canceler": "string",
        "abolishReason": "string",
        "deviceNo": "string",
        "remark": "string",
        "invoiceStatus": "string",
        "invoiceCode": "string",
        "invoiceNum": "string",
        "invoiceDate": "string",
        "invoiceDetail": [
            {
                "amount": 0,
                "billSourceId": "string",
                "goodsName": "string",
                "includeTaxAmount": 0,
                "includeTaxPrice": "string",
                "lineProperty": 0,
                "price": "string",
                "privilegeContent": "string",
                "privilegeFlag": 0,
                "quantity": "string",
                "revenueCode": "string",
                "revenueName": "string",
                "seq": 0,
                "specification": "string",
                "taxAmount": 0,
                "taxRate": "string",
                "units": "string",
                "zeroTaxRateFlag": "string"
            }
        ],
        "invoiceFileUrl": "string",
        "invoiceImageUrl": "string",
        "invoicePdfFileUrl": "string",
        "invoiceXmlFileUrl": "string",
        "orderNo": "string",
        "originalInvoiceCode": "string",
        "originalInvoiceNumber": "string",
        "originalInvoiceStatus": "string",
        "originalIssueTime": "string",
        "printFlag": "string",
        "redInfoBillNo": "string",
        "serialNo": "string",
        "systemSource": "string",
        "terminalNo": "string",
        "checkCode": "string",
        "skm": "string"
    },
    "bizControl": {
        "issueBizType": "string",
        "bizType": "string",
        "monthSurplusLimit": 0,
        "daySurplusLimit": 0,
        "isWarning": true
    }
}

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://cosmic-sandbox.piaozone.com/jdpjykjyxgs/：忽略该接口前缀，此为对接发票云方提供的回调地址（对接方必须按照成功响应示例报文返回 json ）' \
--header 'access_token: {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "interfaceCode": "string",
    "returnCode": "string",
    "returnMsg": "string",
    "data": {
        "batch": "string",
        "billNo": "string",
        "invoiceProperty": 0,
        "invoiceType": "028",
        "buyerProperty": 0,
        "buyerName": "string",
        "buyerTaxpayerId": "string",
        "buyerAddressAndTel": "string",
        "buyerBankAndAccount": "string",
        "buyerRecipientMail": "string",
        "buyerRecipientPhone": "string",
        "deduction": 0,
        "includeTaxFlag": 0,
        "totalTaxAmount": 0,
        "totalAmount": 0,
        "includeTaxAmount": 0,
        "taxedType": 0,
        "sellerName": "string",
        "sellerTaxpayerId": "string",
        "sellerAddressAndTel": "string",
        "sellerBankAndAccount": "string",
        "inventoryMark": "string",
        "drawer": "string",
        "reviewer": "string",
        "payee": "string",
        "canceler": "string",
        "abolishReason": "string",
        "deviceNo": "string",
        "remark": "string",
        "invoiceStatus": "string",
        "invoiceCode": "string",
        "invoiceNum": "string",
        "invoiceDate": "string",
        "invoiceDetail": [
            {
                "amount": 0,
                "billSourceId": "string",
                "goodsName": "string",
                "includeTaxAmount": 0,
                "includeTaxPrice": "string",
                "lineProperty": 0,
                "price": "string",
                "privilegeContent": "string",
                "privilegeFlag": 0,
                "quantity": "string",
                "revenueCode": "string",
                "revenueName": "string",
                "seq": 0,
                "specification": "string",
                "taxAmount": 0,
                "taxRate": "string",
                "units": "string",
                "zeroTaxRateFlag": "string"
            }
        ],
        "invoiceFileUrl": "string",
        "invoiceImageUrl": "string",
        "invoicePdfFileUrl": "string",
        "invoiceXmlFileUrl": "string",
        "orderNo": "string",
        "originalInvoiceCode": "string",
        "originalInvoiceNumber": "string",
        "originalInvoiceStatus": "string",
        "originalIssueTime": "string",
        "printFlag": "string",
        "redInfoBillNo": "string",
        "serialNo": "string",
        "systemSource": "string",
        "terminalNo": "string",
        "checkCode": "string",
        "skm": "string"
    },
    "bizControl": {
        "issueBizType": "string",
        "bizType": "string",
        "monthSurplusLimit": 0,
        "daySurplusLimit": 0,
        "isWarning": true
    }
}'

返回响应

🟢200成功

application/json

Body

message

string

描述信息

必需

errorCode

string

错误代码

必需

success

boolean

成功响应

必需

成功响应

示例

{
    "message": "string",
    "errorCode": "string",
    "success": true
}

修改于 2025-06-30 06:51:15

5.1.01开票申请单回退接口（星瀚发起退回开票申请单）

5.1.03回调接口-按单回调（单据对应的所有发票开票完毕后一起回调（包含开票成功和开票失败），不支持合并又拆分的场景）