接口文档
快速入门
欢迎使用星云税融API。所有接口采用 HTTP RESTful 风格，使用 JSON 格式交换数据。
接入流程：
① 注册账号并登录控制台 →
② 创建 API Key →
③ 阅读文档并集成 →
④ 充值余额开始调用
鉴权方式
所有 API 请求必须在 Header 中携带您的 API Key：
| Header | 必填 | 说明 |
|---|---|---|
| X-API-Key | 是 | 登录控制台后在 API Keys 页面获取 |
| Content-Type | 是 | 固定为 application/json |
统一请求基础地址
https://shuiwu.xingyunv2.cn/api/v1/proxy
第一次调用示例
BASH
curl -X POST https://shuiwu.xingyunv2.cn/api/v1/proxy/invoice/verify/tax-control \ -H "Content-Type: application/json" \ -H "X-API-Key: sk-xxxxxxxxxxxx" \ -d '{ "fpdm": "011002200311", "fphm": "12345678", "kprq": "2026-04-01", "je": "1000.00", "jym": "123456" }'
成功响应
JSON
{
"code": 200,
"msg": "查验成功",
"data": {
"fpdm": "011002200311",
"fphm": "12345678",
"gfmc": "XXX科技有限公司",
"status": "1"
}
}
对接流程
税务登录类接口需按以下顺序调用：
1
订购产品
subscription/create — 传入企业税号和名称，获取 aggOrgId（首次订购自动创建企业）2
创建登录账号
login/account/create — 传入办税员手机号、RSA加密密码、身份类型，获取 accountId3
发送短信验证码
login/sms/send — 传入 aggOrgId + accountId，税局下发短信到办税员手机，获取 taskId4
上传短信验证码
login/sms/upload — 传入 taskId + smsCode，完成税局登录
注意：
- 广东、天津、浙江、湖北地区不需要短信验证码，第3步会直接返回登录成功
- 第2步
gryhm必须是办税员手机号，不是企业税号！ - 第2步
gryhmm必须经过RSA公钥加密，且需传encryptionType: 1 - 短信验证码2分钟内不可重复发送，5分钟内上传有效
RSA加密说明
登录接口中的密码字段 gryhmm 需使用RSA公钥加密后传输，加密后需传 "encryptionType": 1。
RSA 公钥
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+vuYMGtTU+42wwbaFX+PkCuSeoREKe5V4EJMi553Gc03ficUdpLHIFdEjAMHAxepwm3RAGLwyxYFK/S93k8GYMuV35L2Nj/cVeHS8scsdqXzqLUKaI4wj438OI6HDh7rWsw1M5EgMsoZvQqja53+SgD3mgIy3XyILbmA5jUp2IwIDAQAB
PHP 加密示例
PHP
function rsaEncrypt($plainText) { $publicKey = 'MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+vuYMGtTU...'; $pem = "-----BEGIN PUBLIC KEY-----\n" . chunk_split($publicKey, 64, "\n") . "-----END PUBLIC KEY-----"; $key = openssl_pkey_get_public($pem); openssl_public_encrypt($plainText, $encrypted, $key); return base64_encode($encrypted); }
Java 加密示例
Java
byte[] bytes = Base64.decode(publicKey); X509EncodedKeySpec spec = new X509EncodedKeySpec(bytes); KeyFactory factory = KeyFactory.getInstance("RSA"); PublicKey key = factory.generatePublic(spec); Cipher cipher = Cipher.getInstance("RSA"); cipher.init(Cipher.ENCRYPT_MODE, key); byte[] encrypted = cipher.doFinal(data.getBytes()); String result = Base64.encode(encrypted);
计费说明
本平台采用"按次计费"与"订阅制"两种扣费模式并存，登录控制台后可在【产品报价】页查看您的实时报价。
| 计费单位 | 说明 |
|---|---|
| 元/次 (per_call) | 每次成功调用即时从账户余额扣除对应售价 |
| 元/年 (per_year) | 订阅制产品，需先联系商务订阅；订阅期内调用不再扣费 |
| 元/人/月 (per_person_month) | 按人头月订阅，如个税申报、社保代扣；订阅期内调用不再扣费 |
| 元/税号/年 (per_taxid_year) | 按企业税号年订阅；订阅期内该税号的调用不再扣费，调用时必须携带税号以匹配订阅 |
扣费规则
- 每次调用按价格优先级取值：客户专属价 → 代理专属价 → 全局默认价
- 代理子用户调用时，扣费自动从其所属代理的账户余额扣除，子用户本人不扣
- 订阅制产品单次调用不扣余额，但需先订阅；未订阅调用将返回错误
- 调用失败不扣费：业务错误、参数校验失败或网络异常均不计费（已成功透传的业务错误除外）
- 账户余额不足时按次计费调用将被拒绝；若有信用额度 (
credit_limit) 可透支至该额度
代理开放接口 (Agent API)
适用对象：机构型接入方（如第三方记账/报税系统）。通过此套接口可在你自己的系统内自动创建企业子账号、拉取开通情况、统计消费、发放 API Key，实现一体化集成。
调用此接口的 API Key 必须属于代理账户 (is_agent=1)；普通账户调用将返回 403。
基础信息
| Base URL | https://shuiwu.xingyunv2.cn/api/v1/agent.php |
| 鉴权方式 | Header X-API-Key: <代理账户的API Key> |
| 请求方式 | GET (查询) / POST + JSON body (变更) |
| 路由 | ?action=xxx |
端点清单
| 方法 | action | 说明 |
|---|---|---|
| 查询 (GET) | ||
| GET | balance | 机构余额 + 信用额度 |
| GET | sub_users | 子用户列表（page, limit） |
| GET | sub_user | 单个子用户详情（id） |
| GET | sub_user_keys | 子用户 API Key 列表（sub_user_id） |
| GET | subscriptions | 订阅列表（customer_id?, product_code?, active_only=1） |
| GET | usage | 消费统计（from, to, customer_id?） |
| GET | logs | 调用日志（customer_id?, page, limit） |
| GET | transactions | 交易流水 |
| 变更 (POST) | ||
| POST | create_sub_user | 创建子用户 + 自动发放 API Keyphone*, password*, company, contact, email? |
| POST | toggle_sub_user | 启停子用户（id*） |
| POST | allocate_balance | 划拨余额（id*, amount*） |
| POST | create_api_key | 创建 API Key（sub_user_id?, name, env, rate_limit, daily_limit） |
| POST | revoke_api_key | 吊销 API Key（key_id*） |
| Webhook 管理 | ||
| GET | webhooks | 列出 webhook 配置 |
| POST | create_webhook | 创建 webhook（url*, events[]*），响应返回 secret |
| POST | toggle_webhook | 启用/暂停（id*） |
| POST | delete_webhook | 删除（id*） |
| GET | webhook_logs | 推送日志 |
Webhook 事件：call.completed
每次 API 调用完成后，平台会 POST JSON 到你的回调地址。若调用方是子用户，父代理也会同时收到（附加 sub_user_id / agent_id 字段）。Header 含 X-Webhook-Timestamp 和 X-Webhook-Signature: HMAC-SHA256(timestamp + "." + body, secret)。回调地址不允许为内网/保留 IP。
{
"event": "call.completed",
"customer_id": 88,
"data": {
"trace_id": "7f3d-a1b2-c3d4",
"sub_user_id": 1024,
"agent_id": 88,
"endpoint_name": "数电开票",
"product_code": "0004",
"nsrsbh": "91320100MA1K2XXXXX",
"success": true,
"price": 0.50,
"cost": 0.25,
"latency_ms": 823,
"created_at": "2026-04-18 22:30:15"
},
"timestamp": 1745000000
}
示例：创建企业子账号
curl -X POST "https://shuiwu.xingyunv2.cn/api/v1/agent.php?action=create_sub_user" \
-H "X-API-Key: sk-xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"phone":"13800001111","password":"StrongPass123","company":"某某有限公司"}'
{
"success": true,
"data": { "id": 1024, "phone": "13800001111", "company": "某某有限公司",
"api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
"message": "子用户创建成功"
}
安全提醒：代理 API Key 权限极高（可创建子用户、划拨余额），请妥善保管在后端服务器，切勿泄露到前端或客户端。建议启用 IP 白名单。
字段参考
| 字段名 | 类型 | 说明 |
|---|---|---|
| aggOrgId | String/Integer | 企业唯一标识，由订购产品接口返回，后续所有接口都需要用到 |
| accountId | String | 登录账号唯一标识，由创建账号接口返回 |
| nsrsbh | String | 纳税人识别号（企业税号），15/17/18/20位 |
| aggOrgName | String | 企业名称，需与税务局登记名称一致 |
| dq | String | 地区编码，见地区码附录 |
| gryhm | String | 办税员手机号或用户名（非企业税号！在税务局注册的个人登录名） |
| gryhmm | String | 税局登录密码，必须RSA公钥加密后传输（Base64编码） |
| encryptionType | Integer | 加密类型，使用RSA加密时固定传1 |
| sflx | String | 身份类型：AUTO=自动(默认第一个身份)、FDDBR=法定代表人、CWFZR=财务负责人、BSY=办税员、KPY=开票员、BSFWRY=涉税服务人员、GLY=管理员、CTKSRY=出口退税人员、LPR=领票人、SBJBR=社保经办人、XSRY=销售人员、QTRY=其他人员、XZBSY=行政办事员。不确定时传AUTO |
| sjhm | String | 办税员手机号（接收短信验证码的手机号） |
| dlfs | Integer | 登录方式：14=企业登录、15=代理登录 |
| taskId | String | 异步任务ID，由发送短信接口返回，上传验证码时使用 |
| smsCode | String | 短信验证码（6位数字） |
| productCodeList | String | 产品码列表，英文逗号分隔，见产品码附录 |
认证鉴权 (OAuth)
平台内部采用OAuth2.0对接税务服务，access_token的获取和签名由平台自动处理。您只需在请求Header中携带 X-API-Key 即可，无需关注OAuth细节。以下仅供了解：
- access_token默认有效时间15天，平台自动缓存和刷新；
- API签名采用 API-SV1 规范，平台自动计算，调用方无需处理；
注意：获取到的access_token需要存储到本地缓存中再使用，不可频繁请求；建议至少每7天更新一次，频繁请求login接口将会被限制。
获取 access_token
根据获取到的AppKey和AppSecret，通过调用OAuth系列接口来获取access_token。
请求地址
POST/v2/public/oauth2/login
Header 头信息
Content-Type: application/json;charset=UTF-8
Body 参数
Request Body 为 JSON 格式，说明如下：
| 参数名称 | 参数类型 | 说明 |
|---|---|---|
| grant_type | String | 固定 client_credentials |
| client_appkey | Long | 第一步获取的AppKey |
| client_secret | String | 第一步获取的appsecret的md5值（应为32位小写） |
示例参数
JSON
{
"grant_type": "client_credentials",
"client_appkey": "xxxxxx",
"client_secret": "xxxxxxxxxxxxxxxxxxxx"
}
返回值
返回的结果为JSON格式，遵循公共报文格式，示例如下：
JSON
{
"reqId": "0550e35a24014277ab056cf7246eb7db",
"code": "2000",
"success": true,
"message": null,
"data": {
"access_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOi..."
}
}
业务编码列表
| 业务编码 | 说明 |
|---|---|
| 40100 | 未登录 |
| 40101 | AppKey登录信息过期! |
| 40102 | 服务器版本已更新，请重新登录! |
| 40500 | 该客户端sdk已经不被支持，请更新版本! |
| 505017 | app级接口访问，请按照接口规范做签名验证! |
| 505018 | req_date字段与服务器时间存在过大时差! |
| 505019 | 验证签名失败! |
| 505069 | 当前产品已超使用期，请联系服务提供商！ |
| 505070 | 当前产品已超使用次数，请联系服务提供商！ |
错误码说明
| HTTP状态码 | 含义 | 说明 |
|---|---|---|
| 200 | 成功 | 请求处理成功 |
| 400 | 参数错误 | 请求参数缺失或格式不正确 |
| 401 | 未授权 | API Key 缺失、无效或已过期 |
| 402 | 余额不足 | 账户余额不足，请充值 |
| 403 | 禁止访问 | IP不在白名单，或接口无权限 |
| 404 | 接口不存在 | 请求路径不存在或接口已下线 |
| 429 | 请求频率超限 | 超出QPS限制或日调用上限 |
| 500 | 服务端错误 | 系统内部错误，请联系技术支持 |
| 503 | 服务不可用 | 远端服务维护或不可用 |
地区码附录
用于 dq 字段，传入企业税号所在地区的编码。
北京
11
天津
12
河北
13
山西
14
内蒙古
15
辽宁
21
吉林
22
黑龙江
23
上海
31
江苏
32
浙江
33
安徽
34
福建
35
江西
36
山东
37
河南
41
湖北
42
湖南
43
广东
44
广西
45
海南
46
重庆
50
四川
51
贵州
52
云南
53
西藏
54
陕西
61
甘肃
62
青海
63
宁夏
64
新疆
65
大连
2102
宁波
3302
厦门
3502
青岛
3702
深圳
4403
产品码附录
用于 productCodeList 字段，多个产品码用英文逗号分隔。具体可订购的产品码以账号权限为准。
票类产品
| 产品码 | 产品名称 |
|---|---|
| 0001 | 发票查验(标准版) |
| 0007 | 发票查验(扩展版) |
| 0041 | 票据识别 |
| 0004 | 数电开票 |
| 0003 | 发票认证(代账版) |
| 0015 | 发票认证(集团版) |
| 0070 | 发票入账 |
| 0017 | 发票归集(代账版) |
| 0009 | 发票归集(集团版) |
| 0018 | 数电票版式文件下载(代账版) |
| 0005 | 数电票版式文件下载(企业版) |
税类产品
| 产品码 | 产品名称 |
|---|---|
| 0020 | 智能税务申报(代账版) |
| 0022 | 智能税务申报(大企业版) |
| 0026 | 智能税务申报(增值包A) |
| 0028 | 智能税务申报(增值包B) |
| 0027 | 智能税务申报(增值包C) |
| 0025 | 个税申报(企业版) |
| 0029 | 个税申报(代账版) |
| 0035 | 办税人员管理 |
| 0050 | 企业数据采集(解析版) |
| 0051 | 企业数据采集(文件版) |
| 0053 | 社保(企业版) |
| 0054 | 社保(代账版) |
| 0033 | 办税助手 |
| 0019 | 出口退税申报 |
| 0016 | 海关进出口报关单 |
数据 & 其他辅助类
| 产品码 | 产品名称 |
|---|---|
| 0036 | 登录增强版(企业登录)/自持登录 |
| 0046 | 云抬头查询 |
| 0040 | 黑名单(企业信息查询)/企业精准查询 |
| 0067 | 企业联系人信息查询 |
| 0066 | 新增企业信息推送/新增企业名单 |
| 0068 | 企业360度洞察 |
| 0043 | 黑名单(风控明细) |
| 0044 | 黑名单(融合版A) |
| 0045 | 黑名单(融合版B) |
| 0052 | 法规库 |
| 0072 | 风控报告 |
| 0074 | 工商年报申报 |
提示：如遇到
"存在不能订购的产品码" 错误，说明该产品码未开通权限，需联系技术支持。
业务错误码
以下为税务服务返回的常见业务错误码，包含在响应体 code 字段中。
| 错误码 | 含义 | 解决方案 |
|---|---|---|
| 2000 | 成功 | 接口调用成功 |
| SUCCESS | 成功 | 订购产品等接口的成功码 |
| 4000 | 参数错误 | 检查请求参数是否完整正确 |
| 4036 | 用户未注册 | 该自然人未在税务局注册，或 gryhm 传了企业税号而非手机号 |
| PARAMETER_ERROR | 参数错误 | 检查必填参数（aggOrgId、nsrsbh等） |
| BUSINESS_ERROR | 业务错误 | 如"未查询到符合条件的登录数据"，检查账号状态 |
| 40100 | 未登录 | access_token无效或过期（平台自动处理） |
| 505017 | 签名验证失败 | 签名计算错误（平台自动处理） |
| 505069 | 产品已超使用期 | 联系技术支持续费 |
| 505070 | 产品已超使用次数 | 联系技术支持增加额度 |
发票业务
简介
应用场景
企业端发票流转应用全景展示
票据处理
- ●OCR 票据识别
- ●增值税发票查验
- ●区块链/通用电子发票查验
- ●财政电子票据查验
销项管理
- ●数电发票开具（蓝/红字）
- ●开票额度查询
- ●版式文件下载（XML/OFD/PDF）
- ●开票信息维护（商品/客户）
进项管理
- ●发票归集（进销项/已勾选/同步）
- ●发票勾选认证
- ●发票入账
- ●发票汇总统计
能力特点
1
增值税发票查验覆盖全国36个区域，支持报文入参和版式文件入参两种模式，可快速获得发票全票面信息。常用于费控报销领域的单据审核环节，帮助开发者实现发票真伪验证，并通过查验获得发票结构化数据后形成自动分类归档的能力。
2
除增值税发票外，支持区块链发票（深圳、云南、北京）和通用电子发票（浙江、广东）查验。江苏地区的通行费电子发票（人工收费）支持查验后返回结构化数据。
3
财政电子票据查验，常见的包括医疗收费票据，可获得票面项目信息、医保账户支付、自费支付等结构化数据，以及收费内容清单。
4
发票归集对财税系统十分重要，中小企业的自动记账、自动算税、企业间结算、经营能力评估等场景，都需要完整的进销项发票数据。
5
数电版式文件下载支持 XML、OFD、PDF 三种格式。其中 XML 格式包含税务局数字签名，属于电子发票原始凭证，支持电子化入账的企业可直接以此作为原始凭证处理，批量下载让获取更加便捷高效。
能力目录
© 2026 星云税融API. All rights reserved.
如需接入支持，请联系技术团队 | 注册账号