星云税融API

API 文档
Base URL: https://shuiwu.xingyunv2.cn
接口文档
文档 / 票据查验 / 查验扩展

票据查验 - 查验扩展

增值税/数电票/财政票据/区块链发票查验

查验扩展

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

查验并获取版式

数电票查验并获取版式

数电票查验+版式文件下载(与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"
        }
    ]
}

上传文件查验

上传文件查验

上传文件查验(仅限增值税发票)。支持xml/ofd/pdf格式,文件大小<500KB。企享云先从文件识别四要素再查验,返回全票面+fileUrl。适合费控报销场景:客户只有PDF/OFD文件,无需手工录入fpdm/fphm/kprq等

登录查看报价
POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/upload

请求参数

参数名 类型 必填 说明
fileName String 是 文件名+后缀,目前支持pdf/ofd/xml。例:test.pdf
fileData String 是 文件内容base64编码,原始文件需<500KB

请求示例

JSON 
{
    "fileName": "test.pdf",
    "fileData": "JVBERi0xLjQKJaqr..."
}

响应参数

参数名 类型 说明
code String 2000=成功
data Array 查验结果
data[].success Boolean 查验是否成功
data[].fileUploadCy Boolean 是否文件上传查验=true
data[].fileUrl String 文件存储URL(企享云侧)
data[].fplx String 识别出的发票类型
data[].fpdm String 识别出的发票代码
data[].fphm String 识别出的发票号码
data[].kprq String 识别出的开票日期
data[].je Number 识别出的金额
data[].jym String 识别出的校验码
data[].dq String 地区码
data[].data Object 查验成功返回全票面(同zzsfpCy),失败返回识别结果

响应示例

JSON 
{
    "code": "2000",
    "reqId": "1f7d8d89b55641fe8f4075f2f01119d3",
    "success": true,
    "data": [
        {
            "success": true,
            "fileUploadCy": true,
            "fplx": "10",
            "dq": "11",
            "fpdm": "011002200811",
            "fphm": "95988841",
            "kprq": "2023-02-15 00:00:00",
            "je": 1960.26,
            "jym": "509791",
            "fileUrl": "http:\/\/qxy-oss...\/xxx.pdf",
            "times": 2,
            "data": {
                "xfmc": "北京XX科技有限公司",
                "xfsbh": "9111XXXXFB09",
                "gfmc": "XX有限公司",
                "gfsbh": "91XXXXXXXX90",
                "je": 1960.26,
                "se": 28.14,
                "jshj": 1988.4,
                "fpztDm": "0",
                "hwxx": [
                    {
                        "mc": "*运输服务*客运服务费",
                        "je": 1066.24,
                        "slv": 0
                    }
                ]
            }
        }
    ]
}

入账状态及用途标签

入账状态及用途标签查询

查询发票入账状态及用途标签。支持数电票(fphm+kprq+jshj三要素)和增值税税控票(含fpdm,普票必传jym)。返回发票状态(fpztDm/fpztMc)/风险等级(fpfxdj)/来源(fplyDm)/冲红作废标志/入账状态ytbqxx(fprzzt未入账/已入账,zzsytbq增值税用途标签:未使用/已抵扣/未抵扣/不抵扣)

登录查看报价
POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/entry-status

请求参数

参数名 类型 必填 说明
customReqId String 是 请求ID
cyList Array 是 查询列表
cyList[].fpdm String 否 发票代码(增值税专票/电子专票/机动车/二手车查询时必填,数电票无需)
cyList[].fphm String 是 发票号码
cyList[].kprq String 是 开票日期,yyyy-MM-dd 或 yyyyMMdd
cyList[].jshj Number 是 价税合计
cyList[].jym String 否 校验码(增值税普票/电子普票/卷票/电子普票通行费查询时必填)

请求示例

JSON 
{
    "customReqId": "",
    "cyList": [
        {
            "fphm": "23xxxxxxxxxxxxxxxxx27",
            "kprq": "2023-01-05",
            "jshj": "60000"
        }
    ]
}

响应参数

参数名 类型 说明
code String 2000=成功
data Array 查询结果
data[].fpdm String 发票代码(数电票为空)
data[].fphm String 发票号码(数电票为空)
data[].qdfphm String 全电发票号码
data[].lzfpqdhm String 蓝字发票全电号码
data[].kprq String 开票日期
data[].fpztDm String 发票状态:0正常/2已作废/3已红冲/7已红冲-部分/8已红冲-全额
data[].fpztMc String 发票状态名称
data[].fppzDm String 发票票种代码:01增值税专票/02普票/03机动车/04二手车/05铁路/06航空
data[].fpfxdj String 发票风险等级:正常/异常/疑点
data[].sfch String 是否冲红:未冲红/已冲红
data[].sfzf String 是否作废:未作废/已作废
data[].sffxbz String 是否风险标志:Y/N
data[].fplyDm String 发票来源:1增值税发票管理系统,2电子发票服务平台
data[].gfsbh String 购方识别号
data[].dsffpbz String 第三方发票标志Y/N
data[].cyjg String 查验结果
data[].ytbqxx Object 用途标签信息:fprzzt入账状态/zzsytbq增值税用途标签(未使用/已抵扣/未抵扣/不抵扣)/xfsytbq消费税用途标签/zzsgxsq增值税勾选所属期

响应示例

JSON 
{
    "reqId": "a1621b0da26f403e8f76ae496f98dd0d",
    "code": "2000",
    "success": true,
    "data": [
        {
            "qdfphm": "21xxxxxxxxxxxxxxxxx61",
            "cyjg": "第三方发票,经查验,发票信息一致",
            "dsffpbz": "Y",
            "fpfxdj": "正常",
            "fplyDm": "2",
            "fplymc": "电子发票服务平台",
            "fpztDm": "0",
            "gfsbh": "91XXXXXXXXX2G",
            "kprq": "2021-12-01 00:00:00",
            "sfch": "未冲红",
            "sfchDm": "N",
            "sffxbz": "N",
            "sfzf": "未作废",
            "ytbqxx": {
                "qdfphm": "21xxxxxxxxxxxxxxxxx61",
                "fplymc": "电子发票服务平台",
                "fprzzt": "未入账",
                "xfsytbq": "未使用",
                "zzsytbq": "未使用"
            }
        }
    ]
}

查验并获取版式(总局门户)

查验并获取版式(总局门户)

总局门户数电票查验+版式文件下载(查验结果与国家税务总局全国增值税查验平台一致,版式文件下载结果与电票平台版式文件一致)。与税控/数电/数电纸质查验共用同一URL zzsfpCy,企享云按bswjFplx是否存在+请求体字段自动识别为"查验+版式"模式。必传fphm+kprq+jshj+bswjFplx。响应可直接返回pdfUrl/ofdUrl/xmlUrl(同步模式)或bswjxzTaskId(异步模式,需08b查询)

登录查看报价
POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/portal-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为空时无效)

请求示例

JSON 
{
    "customReqId": "48",
    "cyList": [
        {
            "fphm": "24xxxxxxxxxxxxxxxxx58",
            "kprq": "2024-05-24",
            "jshj": 55000,
            "bswjFplx": "0910,0920,61,83",
            "bswjLx": "PDF,OFD,XML"
        }
    ]
}

响应参数

参数名 类型 说明
code String 2000=成功
data Array 查验+版式结果
data[].success Boolean 单张处理是否成功
data[].code String 失败编码(如IllegalParameter=bswjLx类型不支持)
data[].bswjxzTaskId String 版式文件下载任务ID(异步时返回,同步时为null)
data[].fplx String 票种代码
data[].pdfUrl String PDF下载URL(同步返回时直接返回)
data[].ofdUrl String OFD下载URL
data[].xmlUrl String XML下载URL(含税局数字签名)
data[].data Object 全票面数据(xfmc/gfmc/je/jshj/hwxx/qdfphm/qdlx)

响应示例

JSON 
{
    "reqId": "a9855c9280e343eca1e67e1fecdbf213",
    "code": "2000",
    "success": true,
    "data": [
        {
            "success": true,
            "bswjxzTaskId": null,
            "fplx": "0910",
            "fphm": "24332000000122959604",
            "jshj": 18200,
            "kprq": "2024-04-30 00:00:00",
            "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?...",
            "data": {
                "xfmc": "东XX公司",
                "gfmc": "东XX公司",
                "je": 17333.33,
                "se": 866.67,
                "jshj": 18200,
                "qdfphm": "24xxxxxxxxxxxxxxxxx04",
                "qdlx": "10"
            }
        }
    ]
}

查验版式下载结果(总局)

总局门户查验版式下载任务结果查询(与08b verify-ept-fmt-result共用同一URL /v2/invoice/cy/bsxzJgCx)。bsxzJgCx是统一的版式下载结果查询入口,无论是电票平台(dpptCy)还是总局门户(zzsfpCy)异步产生的bswjxzTaskId都走此查询。Body与失效规则详见08b

登录查看报价
POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/portal-format/result

请求参数

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

请求示例

JSON 
{
    "taskId": "531928300933248"
}

响应参数

参数名 类型 说明
code String 2000=成功;BusinessVerification=未查到/已过期/已取走;CheckBswjxzException=任务超时;CheckAuthorityVerification=未订购查验扩展版
data[].qdfphm String 数电发票号码
data[].zt String 任务状态:1=处理中,2=失败,3=完成
data[].pdfUrl String PDF下载URL
data[].ofdUrl String OFD下载URL
data[].xmlUrl String XML下载URL
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\/...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_...xml?..."
        }
    ]
}

© 2026 星云税融API. All rights reserved.

如需接入支持，请联系技术团队 | 注册账号