接口文档 - 星云税融API

发起获取数电版式任务

发起获取数电票版式文件任务。异步接口，提交发票号码后返回taskId，通过结果查询接口获取版式文件下载链接。

登录查看报价

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

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID
accountId	String	否	账号ID
data.fphm	String	是	发票号码
data.fpdm	String	否	发票代码(税控票必填)
data.bswjLx	String	否	版式文件类型：PDF/OFD/XML，多个逗号分隔，默认全部

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440",
    "data": {
        "fphm": "23312000000043000001",
        "bswjLx": "PDF,OFD"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.taskId	String	版式下载任务ID

响应示例

JSON

{
    "reqId": "fmt001",
    "code": "2000",
    "success": true,
    "data": {
        "taskId": "731928300933248"
    }
}

获取数电票版式文件

获取数电票版式文件。查询版式下载任务结果，成功后返回文件下载链接(PDF/OFD/XML)。

登录查看报价

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

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID
data.taskId	String	是	版式下载任务ID

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440",
    "data": {
        "taskId": "731928300933248"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.status	Integer	0=初始化/1=执行中/2=失败/3=成功
data.fileList	Array	文件列表(status=3时返回)
data.fileList[].fileType	String	文件类型：PDF/OFD/XML
data.fileList[].fileUrl	String	文件下载URL(有效期约24小时)

响应示例

JSON

{
    "reqId": "fmt002",
    "code": "2000",
    "success": true,
    "data": {
        "status": 3,
        "fileList": [
            {
                "fileType": "PDF",
                "fileUrl": "https:\/\/oss.example.com\/invoice\/xxx.pdf"
            },
            {
                "fileType": "OFD",
                "fileUrl": "https:\/\/oss.example.com\/invoice\/xxx.ofd"
            }
        ]
    }
}

单张数电版式下载

单张数电票版式文件下载。直接返回单张发票的版式文件信息，无需异步轮询。

登录查看报价

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

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID
data.fphm	String	是	发票号码
data.bswjLx	String	否	版式文件类型：PDF/OFD/XML

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440",
    "data": {
        "fphm": "23312000000043000001",
        "bswjLx": "PDF"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.fileList	Array	文件列表
data.fileList[].fileType	String	文件类型
data.fileList[].fileUrl	String	下载URL

响应示例

JSON

{
    "reqId": "fmt003",
    "code": "2000",
    "success": true,
    "data": {
        "fileList": [
            {
                "fileType": "PDF",
                "fileUrl": "https:\/\/oss.example.com\/invoice\/xxx.pdf"
            }
        ]
    }
}

同步获取数电票版式

同步方式获取版式文件。直接返回版式文件下载链接，适合单张实时场景。

登录查看报价

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

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID
data.fphm	String	是	发票号码
data.fpdm	String	否	发票代码(税控票必填)
data.bswjLx	String	否	版式文件类型：PDF/OFD/XML

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440",
    "data": {
        "fphm": "23312000000043000001",
        "bswjLx": "PDF"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.fileList	Array	文件列表
data.fileList[].fileType	String	文件类型
data.fileList[].fileUrl	String	下载URL
data.fileList[].fileBase64	String	文件base64内容(部分接口返回)

响应示例

JSON

{
    "reqId": "fmt004",
    "code": "2000",
    "success": true,
    "data": {
        "fileList": [
            {
                "fileType": "PDF",
                "fileUrl": "https:\/\/oss.example.com\/invoice\/xxx.pdf"
            }
        ]
    }
}

异步获取数电票版式

异步方式获取版式文件。适合批量场景，提交后通过回调或查询获取结果。

登录查看报价

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

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID
data.fpList	Array	是	发票列表
data.fpList[].fphm	String	是	发票号码
data.fpList[].fpdm	String	否	发票代码
data.bswjLx	String	否	版式文件类型：PDF/OFD/XML

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440",
    "data": {
        "fpList": [
            {
                "fphm": "23312000000043000001"
            },
            {
                "fphm": "23312000000043000002"
            }
        ],
        "bswjLx": "PDF,OFD"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.taskId	String	任务ID

响应示例

JSON

{
    "reqId": "fmt005",
    "code": "2000",
    "success": true,
    "data": {
        "taskId": "731928300933249"
    }
}

异步任务执行结果回调(版式)

版式文件下载异步任务执行结果回调。任务完成后系统推送到配置的回调地址。

登录查看报价

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

请求参数

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

请求示例

JSON

{
    "taskId": "731928300933249",
    "status": 3,
    "errorMsg": ""
}

响应参数

参数名	类型	说明
code	String	返回2000表示已接收
msg	String	处理结果

响应示例

JSON

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