接口文档 - 星云税融API

数电票查验并获取版式

数电票查验+版式文件下载(与verify-ept-digital同URL,差异在必传bswjFplx触发版式下载任务)。响应返回bswjxzTaskId(30天有效,取结果后失效),通过版式下载结果查询接口获取PDF/OFD/XML文件。kprq格式:不登录用yyyy-MM-dd;登录(需购方税号托管+订购查验扩展版)可用yyyyMMdd

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/with-format

请求参数

参数名	类型	必填	说明
customReqId	String	是	请求ID
cyList	Array	是	查验列表
cyList[].fphm	String	是	发票号码
cyList[].kprq	String	是	开票日期:不登录用yyyy-MM-dd,登录可用yyyyMMdd(需购方税号托管)
cyList[].jshj	Number	是	价税合计
cyList[].bswjFplx	String	是	需获取版式文件的发票类型范围(多个逗号分隔,枚举0910/0920/61/83/0930)。仅当次查验fplx在此范围内才下载版式
cyList[].bswjLx	String	否	版式文件类型:XML,OFD,PDF(多个逗号分隔,默认全部)。bswjFplx为空时本字段无效
cyList[].ytbq	Boolean	否	是否获取入账状态及用途标签(默认true)

请求示例

JSON

{
    "customReqId": "",
    "cyList": [
        {
            "fphm": "23xxxxxxxxxxxxxxxxx27",
            "kprq": "2023-01-05",
            "jshj": "60000",
            "bswjFplx": "0910,0920,61,83",
            "bswjLx": "XML,OFD,PDF"
        }
    ]
}

响应参数

参数名	类型	说明
code	String	2000=成功
data	Array	查验结果
data[].success	Boolean	单张查验是否成功
data[].bswjxzTaskId	String	版式文件下载任务ID(30天有效)
data[].fplx	String	票种代码
data[].data	Object	全票面数据(含ytbqxx/mxzb/tspzxx/qdfphm/qdlx)

响应示例

JSON

{
    "reqId": "d8ca03b851eb4025833f15b93c035249",
    "code": "2000",
    "success": true,
    "data": [
        {
            "success": true,
            "bswjxzTaskId": "564549648156117900",
            "fplx": "0920",
            "fphm": "21xxxxxxxxxxxxxxxxx61",
            "kprq": "2021-12-01 00:00:00",
            "jshj": 1129.99
        }
    ]
}

查验并获取版式(电票平台)

电票平台数电票查验并获取版式文件(与verify-with-format/verify-ept-digital同URL)。必传bswjFplx触发版式下载任务,响应返回bswjxzTaskId,通过"查验版式下载任务结果"接口获取PDF/OFD/XML文件

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/ept-format

请求参数

参数名	类型	必填	说明
customReqId	String	是	请求ID
cyList	Array	是	查验列表
cyList[].fphm	String	是	发票号码
cyList[].kprq	String	是	开票日期
cyList[].jshj	Number	是	价税合计
cyList[].bswjFplx	String	是	需获取版式文件的发票类型范围(枚举0910/0920/61/83/0930,多个逗号分隔)
cyList[].bswjLx	String	否	版式文件类型:XML,OFD,PDF(默认全部)

请求示例

JSON

{
    "customReqId": "",
    "cyList": [
        {
            "fphm": "23xxxxxxxxxxxxxxxxx27",
            "kprq": "2023-01-05",
            "jshj": "60000",
            "bswjFplx": "0910,0920,61,83",
            "bswjLx": "XML,OFD,PDF"
        }
    ]
}

响应参数

参数名	类型	说明
code	String	2000=成功
data[].bswjxzTaskId	String	版式文件下载任务ID(30天有效,用于结果查询接口)
data[].data	Object	全票面数据

响应示例

JSON

{
    "reqId": "d8ca...",
    "code": "2000",
    "success": true,
    "data": [
        {
            "success": true,
            "bswjxzTaskId": "564549648156117900",
            "fplx": "0920",
            "fphm": "21xxxxx61",
            "jshj": 1129.99
        }
    ]
}

查验版式下载任务结果查询

数电发票查验版式文件下载结果查询。通过bswjxzTaskId或全电发票号码查询。⚠️taskId获取3次结果成功后失效;使用qdfphm/qdfphmList查询成功一次后对应最近一条任务记录的taskId也失效;失效后需重新发起查验+版式下载任务。返回pdfUrl/ofdUrl/xmlUrl下载地址

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/ept-format/result

请求参数

参数名	类型	必填	说明
taskId	String	否	bswjxzTaskId(单个)
taskIdList	Array	否	bswjxzTaskId列表
qdfphm	String	否	全电发票号码(单个)
qdfphmList	Array	否	全电发票号码列表。注:taskId/taskIdList/qdfphm/qdfphmList四选一,不可都为空

请求示例

JSON

{
    "taskId": "531928300933248"
}

响应参数

参数名	类型	说明
code	String	2000=成功;BusinessVerification=未查到/已过期/已取走;CheckBswjxzException=任务超时;CheckAuthorityVerification=未订购查验扩展版;CheckTaxLoginInfoError=登录信息有误;CheckTaxLoginFailed=登录失败
data	Array	下载结果
data[].qdfphm	String	数电发票号码
data[].zt	String	任务状态:1=申请处理中,2=申请处理失败,3=申请处理完成
data[].kprq	String	开票日期(仅zt=3精确到时分秒)
data[].jshj	Number	价税合计(仅zt=3返回)
data[].fplx	String	发票类型(仅zt=3返回)
data[].pdfUrl	String	PDF版式文件URL
data[].ofdUrl	String	OFD版式文件URL
data[].xmlUrl	String	XML版式文件URL
data[].code	String	失败错误码(仅zt=2返回)
data[].chargingNsrsbh	String	计费纳税人识别号(仅开通税号版发票查验版式文件下载产品时返回)

响应示例

JSON

{
    "reqId": "df46cccec9cb4b3db93c6f266d71c25d",
    "code": "2000",
    "success": true,
    "data": [
        {
            "qdfphm": "24xxxxxxxxxxxxxxxxx04",
            "zt": "3",
            "ofdUrl": "http:\/\/qxy-oss-robot-product.oss-cn-beijing.aliyuncs.com\/0708872f7d0892a86ac409f5380e0d24.ofd?...",
            "pdfUrl": "http:\/\/qxy-oss-robot-product.oss-cn-beijing.aliyuncs.com\/b8a3b049dedeea9e43d332add31a7b52.pdf?...",
            "xmlUrl": "http:\/\/qxy-oss-robot-product.oss-cn-beijing.aliyuncs.com\/dzfp_24332000000122959604_20240520171423.xml?..."
        }
    ]
}

版式下载结果回调(电票平台+总局门户接收端)

⚠️非代理接口,是本系统实现的统一回调接收端点 /api/v1/callback/qxy/invoice-format。配置给企享云作为版式下载任务回调URL,同时服务于"电票平台下载"和"总局门户下载"两种场景(企享云使用统一回调格式)。企享云推送{taskId,status(0初始化/1执行中/2失败/3成功),errorMsg},我方响应{code:2000,msg:成功}。本系统按taskId路由分发给对应客户的Webhook

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/callback/qxy/invoice-format

请求参数

参数名	类型	必填	说明
taskId	String	是	任务ID(对应bswjxzTaskId)
status	Integer	是	0=初始化/1=执行中/2=失败/3=成功
errorMsg	String	是	失败原因

请求示例

JSON

{
    "taskId": "12345abcde",
    "status": 3,
    "errorMsg": "成功"
}

响应参数

参数名	类型	说明
code	String	2000=成功,9999=失败
msg	String	具体原因

响应示例

JSON

{
    "code": "2000",
    "msg": "成功"
}

同步获取数电票版式文件

同步获取数电票版式文件(仅支持数电票0910/0920/61/83)。一次请求直接返回pdfUrl/ofdUrl/xmlUrl,无需轮询。三要素:fphm+kprq+jshj。数电纸质发票和非数电票不支持

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/format/sync

请求参数

参数名	类型	必填	说明
customReqId	String	是	请求ID
cyList	Array	是	查验列表
cyList[].fphm	String	是	数电发票号码
cyList[].kprq	String	是	开票日期,格式yyyy-MM-dd
cyList[].jshj	Number	是	价税合计
cyList[].bswjLx	String	否	版式文件类型:XML,OFD,PDF(多个逗号分隔,默认全部)

请求示例

JSON

{
    "customReqId": "",
    "cyList": [
        {
            "fphm": "23xxxxxxxxxxxxxxxxx27",
            "kprq": "2023-01-05",
            "jshj": "60000",
            "bswjLx": "XML,OFD,PDF"
        }
    ]
}

响应参数

参数名	类型	说明
code	String	2000=成功
data	Array	下载结果
data[].success	Boolean	版式文件下载是否成功
data[].qdfphm	String	数电发票号码
data[].kprq	String	开票日期(时分秒均为00)
data[].jshj	Number	价税合计
data[].fplx	String	发票类型(仅成功返回)
data[].pdfUrl	String	PDF版式文件URL
data[].ofdUrl	String	OFD版式文件URL
data[].xmlUrl	String	XML版式文件URL
data[].code	String	失败错误码(success=false时返回)
data[].chargingNsrsbh	String	计费纳税人识别号(仅开通税号版时返回)

响应示例

JSON

{
    "reqId": "05c3dbffdb7c4f378b919d8434050a84",
    "code": "2000",
    "success": true,
    "data": [
        {
            "success": true,
            "qdfphm": "24xxxxxxxxxxxxxxxxx04",
            "kprq": "2024-04-30 00:00:00",
            "jshj": 18200,
            "ofdUrl": "http:\/\/qxy-oss-robot-product.oss-cn-beijing.aliyuncs.com\/...ofd?...",
            "pdfUrl": "http:\/\/qxy-oss-robot-product.oss-cn-beijing.aliyuncs.com\/...pdf?...",
            "xmlUrl": "http:\/\/qxy-oss-robot-product.oss-cn-beijing.aliyuncs.com\/dzfp_24xxx_20240520171423.xml?..."
        }
    ]
}

异步获取数电票版式文件

异步获取数电票版式文件(仅支持数电票0910/0920/61/83)。请求体同bswjxz(同步版),但只返回bswjxzTaskId不直接返回URL。需再调08b(bsxzJgCx)结果查询接口获取pdfUrl/ofdUrl/xmlUrl。适合批量大量下载,对响应时间不敏感场景

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/format/async

请求参数

参数名	类型	必填	说明
customReqId	String	是	请求ID
cyList	Array	是	查验列表
cyList[].fphm	String	是	数电发票号码
cyList[].kprq	String	是	开票日期,格式yyyy-MM-dd
cyList[].jshj	Number	是	价税合计
cyList[].bswjLx	String	否	版式文件类型:XML,OFD,PDF(多个逗号分隔,默认全部)

请求示例

JSON

{
    "customReqId": "",
    "cyList": [
        {
            "fphm": "23xxxxxxxxxxxxxxxxx27",
            "kprq": "2023-01-05",
            "jshj": "60000",
            "bswjLx": "XML,OFD,PDF"
        }
    ]
}

响应参数

参数名	类型	说明
code	String	2000=成功
data	Array	任务创建结果
data[].success	Boolean	任务创建是否成功
data[].bswjxzTaskId	String	异步下载任务ID,用于后续调bsxzJgCx结果查询接口
data[].qdfphm	String	全电发票号码
data[].kprq	String	开票日期(时分秒均为00)
data[].jshj	Number	价税合计
data[].fplx	String	发票类型
data[].customReqId	String	请求ID
data[].chargingNsrsbh	String	计费纳税人识别号

响应示例

JSON

{
    "reqId": "caf8f68695524b93a948c822ec0b93a3",
    "code": "2000",
    "success": true,
    "data": [
        {
            "success": true,
            "bswjxzTaskId": "550156172890752",
            "fplx": "09",
            "qdfphm": "23xxxxxxxxxxxxxxx05",
            "kprq": "2023-07-05 00:00:00",
            "jshj": 1,
            "customReqId": "100019990c1eae53d7a04463832830c94a33ca35"
        }
    ]
}

星云税融API

票据查验 - 获取版式文件(电票平台)

查验扩展

获取版式文件(电票平台)

查验并获取版式

数电票查验并获取版式

请求参数

请求示例

响应参数

响应示例

查验并获取版式(电票平台)

请求参数

请求示例

响应参数

响应示例

版式下载结果查询

查验版式下载任务结果查询

请求参数

请求示例

响应参数

响应示例

版式下载结果回调(电票平台+总局门户接收端)

请求参数

请求示例

响应参数

响应示例

不查验获取版式

同步方式

同步获取数电票版式文件

请求参数

请求示例

响应参数

响应示例

异步方式

异步获取数电票版式文件

请求参数

请求示例

响应参数

响应示例

票据查验 - 获取版式文件(电票平台)

查验扩展

获取版式文件(电票平台)

查验并获取版式

数电票查验并获取版式

请求参数

请求示例

响应参数

响应示例

查验并获取版式(电票平台)

请求参数

请求示例

响应参数

响应示例

版式下载结果查询

查验版式下载任务结果查询

请求参数

请求示例

响应参数

响应示例

版式下载结果回调(电票平台+总局门户 接收端)

请求参数

请求示例

响应参数

响应示例

不查验获取版式

同步方式

同步获取数电票版式文件

请求参数

请求示例

响应参数

响应示例

异步方式

异步获取数电票版式文件

请求参数

请求示例

响应参数

响应示例

版式下载结果回调(电票平台+总局门户接收端)