接口文档 - 星云税融API

企业基本信息(开票)

开票准备阶段:获取当前登录企业的基本信息,从局端实时获取(企享云未加工)。返回纳税人类型(Nsrlx:1一般/2小规模/3转登记/4辅导期/5自然人)/全电标志(Qdbz:Y/N)/新电票试点(Xdpsdqybz)/可开票种(Fpzldms)/特定业务类型(Tdys:建筑/货运/不动产/二手车/拖拉机/不动产租赁/旅客运输等)/默认开票人(Kpr)/办税人/财务负责人/对公账户(YhxxList)/当前税款所属期(Dqskssq)等。action=qyjbxxcx

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/company

请求参数

参数名	类型	必填	说明
action	String	否	操作类型,固定传qyjbxxcx(路径已含可省)
nsrsbh	String	是	税号
aggOrgId	String	是	企业ID
accountId	String	否	多账号下的账号唯一标识
async	Boolean	否	异步标志,默认false

请求示例

JSON

{
    "action": "qyjbxxcx",
    "nsrsbh": "91XXXXXXXXXXXXXXX"
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.Nsrmc	String	纳税人名称
data.Nsrsbh	String	纳税人识别号
data.Nsrlx	String	纳税人类型:1一般/2小规模/3转登记小规模/4辅导期一般/5自然人
data.Qdbz	String	全电标志:Y=全电试点/N=非全电
data.Xdpsdqybz	String	新电票试点企业标识:Y/N
data.Sfkkjzzfp	String	是否可开增值税发票:Y/N
data.Jzjtbz	String	即征即退标志:Y/N
data.Kpr	String	默认开票人
data.Bsrxm	String	办税人姓名
data.Cwfzrxm	String	财务负责人姓名
data.Fddbrxm	String	法定代表人姓名
data.Fpzldms	Array	可开发票种类:[{Fpzldm,Fpzlmc}]
data.Tdys	Array	特定业务类型:[{Tdyslxdm,Tdyslxmc}]如建筑服务/货运/不动产销售/二手车/不动产租赁/旅客运输
data.YhxxList	Array	对公账号信息:[{Yhzh,YhzhxzDm,Yhyywdmc,YhyywdDm}]
data.Dqskssq	String	当前税款所属期,如202403
data.Province	String	所在省市
data.Swjgmc	String	税务机关名称
data.Zcdz	String	注册地址
data.Scjydz	String	生产经营地址
data.Qysxed	Number	授信额度

响应示例

JSON

{
    "reqId": "1f349ace904b481182c494844a82f467",
    "code": "2000",
    "success": true,
    "data": {
        "Nsrmc": "XX信息有限公司",
        "Nsrsbh": "91XXXXXXXXX",
        "Nsrlx": "1",
        "Qdbz": "Y",
        "Sfkkjzzfp": "Y",
        "Kpr": "X鑫",
        "Bsrxm": "X磊",
        "Cwfzrxm": "X敏",
        "Fpzldms": [
            {
                "Fpzldm": "01",
                "Fpzlmc": "增值税专用发票"
            },
            {
                "Fpzldm": "02",
                "Fpzlmc": "普通发票"
            }
        ],
        "Tdys": [
            {
                "Tdyslxdm": "03",
                "Tdyslxmc": "建筑服务"
            },
            {
                "Tdyslxdm": "04",
                "Tdyslxmc": "货物运输服务"
            },
            {
                "Tdyslxdm": "05",
                "Tdyslxmc": "不动产销售"
            },
            {
                "Tdyslxdm": "09",
                "Tdyslxmc": "旅客运输服务"
            }
        ],
        "Dqskssq": "202403",
        "Province": "上海",
        "Swjgmc": "XX税务局第十八税务所",
        "YhxxList": [
            {
                "Yhzh": "XXX10301",
                "YhzhxzDm": "1110",
                "Yhyywdmc": "XX上海青浦支行"
            }
        ]
    }
}

开票额度查询

查询企业发票开票额度。返回当前可用单张最大开票金额、累计开票限额及已用额度。action=kped_cx

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/quota

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID
accountId	String	否	账号ID

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440"
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.dzLjKpxe	String	单张累计开票限额
data.ljKyKpje	String	累计可用开票金额
data.ljYyKpje	String	累计已用开票金额
data.qdbz	String	全电标志

响应示例

JSON

{
    "reqId": "issue001",
    "code": "2000",
    "success": true,
    "data": {
        "dzLjKpxe": "100000",
        "ljKyKpje": "85000",
        "ljYyKpje": "15000",
        "qdbz": "Y"
    }
}

办税开票人授信类别查询

扫脸时长查询(又称"办税开票人授信类别查询")。获取当前纳税人风险等级/预警等级/授信信息。⭐提升开票体验要点:返回参数scanTime是扫脸二维码可设置的最大时长,在"扫脸时长设置"接口里把phxxz设置为scanTime,即可最大限度延长扫脸有效期,减少重复扫脸。action=sxlb_cx

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/face/duration/query

请求参数

参数名	类型	必填	说明
action	String	否	操作类型,sxlb_cx
nsrsbh	String	是	税号
aggOrgId	String	是	企业ID
accountId	String	否	多账号下的账号唯一标识
async	Boolean	否	异步标志,默认false

请求示例

JSON

{
    "action": "sxlb_cx",
    "nsrsbh": "91XXXXXXXXXXXXXXX"
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.yjjb	String	预警级别:01无预警/02红色预警/03黄色预警/04蓝色预警
data.sxlb	String	授信类别:1高风险/2中风险/3低风险/4无风险纳税人
data.sfsl	String	开票前是否需要刷脸:Y/null=需要,N=无需。⭐非N值时需触发刷脸程序
data.scanTime	Integer	扫码能设置的最大时长(分钟)
data.phxxz	String	当前扫码设置的时长(分钟)

响应示例

JSON

{
    "reqId": "91c29e6cf1df4ddd9856019e0d1a634d",
    "code": "2000",
    "success": true,
    "data": {
        "yjjb": "01",
        "sxlb": "3",
        "sfsl": "Y",
        "itsScanFlag": "N"
    }
}

获取人脸识别二维码

获取人脸识别二维码。开票前需刷脸认证时调用，返回二维码内容及认证ID(rzid)。用户使用税务APP或国家网络身份认证APP扫码。action=ewm_sq

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/face/qrcode

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID
accountId	String	否	账号ID
data.slfs	String	否	刷脸方式：1=税务APP/2=国家网络身份认证APP

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440",
    "data": {
        "slfs": "1"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.rzid	String	认证ID，用于后续查询认证结果
data.ewmNr	String	二维码内容(URL)，展示给用户扫码
data.yxsj	Integer	有效时间(秒)

响应示例

JSON

{
    "reqId": "issue002",
    "code": "2000",
    "success": true,
    "data": {
        "rzid": "2e7cfe4c02f547ed8ee1d016f05",
        "ewmNr": "https:\/\/dppt.zj-l-tax.gov.cn\/...",
        "yxsj": 180
    }
}

获取人脸识别结果

获取人脸识别结果(税务APP/国家网络身份认证APP扫码后查询)。通过前一步获取到的rzid查询认证状态。建议按3-5s轮询直到slzt=2(扫脸成功)或slzt=3(二维码过期重新获取)。action=rzztcx

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/face/result

请求参数

参数名	类型	必填	说明
action	String	否	操作类型,rzztcx
nsrsbh	String	是	税号
aggOrgId	String	是	企业ID
accountId	String	否	多账号下的账号唯一标识
async	Boolean	否	异步标志,默认false
data.rzid	String	是	前一接口(获取人脸识别二维码)返回的认证二维码ID

请求示例

JSON

{
    "action": "rzztcx",
    "nsrsbh": "91XXXXXXXXXXXXXXX",
    "data": {
        "rzid": "2e7cfe4c02f547ed8ee1d016f05"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.nsrsbh	String	纳税人识别号
data.slzt	String	刷脸状态:1=已生成二维码未扫脸/2=扫脸成功/3=二维码已过期

响应示例

JSON

{
    "reqId": "bad3a46b47dc4c509717463cebc5f28e",
    "code": "2000",
    "success": true,
    "data": {
        "nsrsbh": "91XXXXXXXXX",
        "slzt": "1"
    }
}

税收分类编码查询

查询税收分类编码信息。开票时选择正确的税收分类编码。

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/tax-code

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID
data.keyword	String	否	关键词搜索
data.spbm	String	否	商品编码精确查询

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440",
    "data": {
        "keyword": "风扇"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.list	Array	编码列表
data.list[].spbm	String	商品编码
data.list[].spmc	String	商品名称
data.list[].sl	String	税率

响应示例

JSON

{
    "reqId": "issue018",
    "code": "2000",
    "success": true,
    "data": {
        "list": [
            {
                "spbm": "1090416010000000000",
                "spmc": "家用通风电器具",
                "sl": "0.13"
            }
        ]
    }
}

扫脸时长查询(legacy)

⚠️legacy端点,保留兼容。新接入请使用 issue-face-duration-query (/v2/invoice/qdfp/sxlbCx)

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/face/duration/legacy

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440"
}

响应参数

参数名	类型	说明
code	String	2000=成功
data	Object	同issue-face-duration-query返回结构

响应示例

JSON

{
    "code": "2000",
    "success": true,
    "data": {
        "sxlb": "3",
        "sfsl": "Y",
        "scanTime": 1440
    }
}

扫脸时长设置

扫脸时长设置(设置扫脸二维码有效时长)。⚠️登录人身份必须是"财务负责人"或"法定代表人",否则调用会失败。⭐最佳实践:先调sxlbCx拿scanTime,把其值带入本接口的phxxz,即可最大化扫脸有效期。单位分钟(原文"最小为1天,需要是天的倍数"=1440的倍数,但示例显示可为20,实际以局端校验为准)。action=smsc

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/face/duration/set

请求参数

参数名	类型	必填	说明
action	String	否	操作类型,smsc
nsrsbh	String	是	税号
aggOrgId	String	是	企业ID
accountId	String	否	多账号下的账号唯一标识
async	Boolean	否	异步标志,默认false
data.phxxz	String	是	扫码时长(分钟)。原文要求需为1440的倍数(1天=1440,2天=2880),示例却是20。建议取sxlbCx返回的scanTime值

请求示例

JSON

{
    "action": "smsc",
    "nsrsbh": "91XXXXXXXXXXXXXXX",
    "data": {
        "phxxz": "1440"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data	Object	成功时为空对象{}

响应示例

JSON

{
    "code": "2000",
    "data": [],
    "success": true,
    "reqId": "2f102e6303c244d69af3fabb61afbf1b"
}

个税APP获取人脸识别二维码

个税APP扫码获取人脸识别二维码。通过个税APP进行实名认证扫码。

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/pit-face/qrcode

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440"
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.rzid	String	认证ID
data.ewmNr	String	二维码内容

响应示例

JSON

{
    "reqId": "pit01",
    "code": "2000",
    "success": true,
    "data": {
        "rzid": "abc123def456",
        "ewmNr": "https:\/\/pit.tax.gov.cn\/..."
    }
}

个税APP获取人脸识别结果

个税APP扫码获取人脸识别结果。轮询查询用户通过个税APP扫码后的认证状态。

登录查看报价

POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/issue/pit-face/result

请求参数

参数名	类型	必填	说明
nsrsbh	String	是	纳税人识别号
aggOrgId	String	是	企业ID
data.rzid	String	是	认证ID

请求示例

JSON

{
    "nsrsbh": "91320100MA1K2XXXXX",
    "aggOrgId": "452681066557440",
    "data": {
        "rzid": "abc123def456"
    }
}

响应参数

参数名	类型	说明
code	String	2000=成功
data.slzt	String	刷脸状态：1=已生成/2=成功/3=过期

响应示例

JSON

{
    "reqId": "pit02",
    "code": "2000",
    "success": true,
    "data": {
        "slzt": "2"
    }
}

数电开票 - 开票准备

开票准备

企业基本信息(开票)

请求参数

请求示例

响应参数

响应示例

开票额度查询

请求参数

请求示例

响应参数

响应示例

办税开票人授信类别查询

请求参数

请求示例

响应参数

响应示例

获取人脸识别二维码

请求参数

请求示例

响应参数

响应示例

获取人脸识别结果

请求参数

请求示例

响应参数

响应示例

税收分类编码查询

请求参数

请求示例

响应参数

响应示例

扫脸时长查询(legacy)

请求参数

请求示例

响应参数

响应示例

扫脸时长设置

请求参数

请求示例

响应参数

响应示例

个税APP获取人脸识别二维码

请求参数

请求示例

响应参数

响应示例

个税APP获取人脸识别结果

请求参数

请求示例

响应参数

响应示例