接入指南

EAS API 的公共接入与联调说明。首次接入按下方路线阅读；具体业务进入 EAS 接口目录。

阅读导航

当前任务	阅读入口
首次接入	01 快速开始 → 02 接入配置 → 03 公共报文 → 04 加签与加密
验证首条查询	05 明文与密文示例 → 查询退税率文库 → 06 业务结果与异常定位
接入业务流程	EAS 接口目录 → 所选接口定义 → 07 接入前待确认
查阅实现参考	08 代码参考与兼容说明、09 演示签名核对

首次联调目标：在已授权的测试环境完成一条查询请求，核对 HTTP 响应、外层响应码及解析后的业务内容。签名、加密组合与业务权限以实际部署为准。

01 · 快速开始

步骤	操作	完成标志
确认范围	确认企业、套餐、开放能力及测试环境	已获得可调用的接口清单
接入配置	配置服务地址、企业标识和双方交付的密钥	已区分测试与生产配置
验证查询	按接口明文样例组织业务参数，完成加签加密后调用	能读取有效响应和业务数据
对接业务	根据业务目录衔接查询、提交、报送或回调	已确认业务结果、超时核对和重试规则

如何查找接口：通用能力进入基础、凭证、进项、销项、退税、单证和电局目录；客户专属字段及 ERP 回调进入定制版接口目录，再查看所选接口。分享文档只展示已圈选的接口，文档“已发布”状态不代表已开通业务权限。

本指南的公共报文规则适用于采用企业公共协议的接口。单点登录、AI 问数、公有云、用友对接及其他客户专属协议，按当前部署和接口定义配置，先确认协议适用范围。

02 · 接入配置

测试与生产分别配置环境。服务地址、企业权限和密钥由对接双方交付。

配置项	用途与填写方式
服务地址	当前部署提供的访问地址；测试与生产分别确认
企业标识 / `socialCreditCode`	已授权企业的统一社会信用代码，按字符串处理
请求签名私钥	企业私钥，PKCS#8 Base64 或 PEM
响应验签公钥	服务端公钥，X.509 Base64 或 PEM
3DES 密码	双方交付的密码；采用第 04 节约定的编码和字节长度
签名类型 / `signType`	`RSA`；仅在部署明确允许时使用 `none`
加密类型 / `encryptType`	`3DES`；仅在部署明确允许时使用 `none`

路径中的 {{socialCreditCode}} 和 {socialCreditCode} 均表示企业标识占位符，调用时替换为已授权企业的实际值。固定企业编号的地址仅用于指定企业，不能直接用于其他企业。

03 · 公共报文

企业公共协议通常使用 POST、application/json 和 UTF-8。业务字段放入 content，具体业务类型与节点以接口参数表为准。

请求字段

顺序	字段	类型	含义
1	`sign`	string	请求签名，RSA 模式为 Base64 字符串
2	`signType`	string	签名类型：`RSA` / `none`
3	`encryptType`	string	加密类型：`3DES` / `none`
4	`timestamp`	string	请求时间，每次调用重新生成
5	`content`	object / array / string	明文业务对象或数组；加密时为 Base64 密文

公共时间格式为 yyyy-MM-dd HH:mm:ss；个别旧版接口已有 10 位秒级时间戳示例，按接口及部署约定处理。

响应字段

顺序	字段	类型	含义
1	`code`	string	外层响应码
2	`message`	string	外层响应描述，按实际返回值读取
3	`sign`	string	响应签名
4	`signType`	string	响应签名类型
5	`content`	object / array / string	业务数据或原始业务报文

参数表中的 content 子节点展示业务数据结构。实际响应的 content 可能是 JSON 序列化字符串或密文；完成本指南约定的处理后，再按这些节点读取。

区分两种顺序：示例的公共节点按参数表顺序展示；生成请求签名时，外层字段按名称的字典序排列。

04 · 加签与加密

请求处理

将业务对象或数组序列化为 UTF-8 JSON 文本。

3DES 模式使用约定密码加密，并将 Base64 密文写入 content。

除 sign 外，将实际外层字段按字段名的字典序排列；排除 null 值，以 key=value 形式用 & 连接，不做 URL 编码。

使用企业私钥，以 SHA1WithRSA 对 UTF-8 签名串签名；将 Base64 结果写入 sign 后发送。

本项目请求包含 encryptType，它参与签名。签名使用实际发送的 content 原文，不重新排版、不增加空格。

content=<实际密文>&encryptType=3DES&signType=RSA&timestamp=<本次请求时间>

3DES 参数：跨语言接入采用 3DES/ECB/PKCS5Padding，密码为 24 字节原值，不做摘要，不使用 IV，密文采用 Base64。

响应处理

保留原始 content 字符串。

RSA 模式使用服务端公钥验证原文签名；验签失败时停止处理业务数据。

验签通过后，按当前协议解密，再解析 UTF-8 JSON。

检查外层响应码与业务结果；批量接口逐条检查返回记录。

响应签名只覆盖原始 content，不拼接 code、message 等外层字段，也不先解密或重新序列化。明文 content 为 JSON 字符串时再次解析；已是对象或数组时直接读取。版式文件等 Base64 文件内容保持字符串。

完整 Java 示例和旧版兼容说明见本页代码参考与兼容说明。

05 · 明文与密文示例

普通接口的请求和响应各保留“示例（明文）”与“示例（密文）”。按 sjlx 或 sblx 区分业务结构的接口，明文样例分别标明数据类型；返回结构相同的类型共用响应样例。每个接口的请求和响应各只保留一个“示例（密文）”，对应第一份明文样例。实际调用时使用企业的接入配置和本次请求时间重新生成签名与密文。

企业名称、税号、联系方式、银行账户和企业账号凭据等信息使用脱敏示例。

枚举、年月、日期等普通业务字段保留有效值，外层 message 按响应码的真实描述展示。

密文示例使用独立演示密钥与固定时间，不能作为真实企业请求直接发送；未定义业务响应的接口仅展示已知公共层结构。

以下是查询退税率文库的明文请求结构，仅在部署明确允许 none/none 时使用。实际调用时重新生成 timestamp。

{
  "sign": "",
  "signType": "none",
  "encryptType": "none",
  "timestamp": "2026-10-10 10:00:00",
  "content": {
    "spdm": "0101101010",
    "current": 1,
    "size": 20
  }
}

接口入口：查询退税率文库。请求路径：POST /qst/enterprise/{socialCreditCode}/tslwk。未使用的可选条件直接省略，不用空字符串替代有效枚举。

核对文档密文样例时，使用本页演示签名核对中的演示密码与公钥。

06 · 业务结果与异常定位

分别判断三个层次：HTTP 200 表示请求已得到 HTTP 响应；外层 code=0000 表示外层处理成功；业务是否完成仍需检查 content。批量接口还需检查 total、success、failed 及 records 中的逐条结果。

响应码	`message`	排查方向
`0000`	成功	继续核对业务结果
`9000`	系统异常	记录请求信息并联系服务方
`9001`	验签失败	核对密钥、签名原文和处理顺序
`9002`	参数异常	核对类型、必填项、格式与枚举
`9003`	套餐异常	核对当前企业的套餐与权限
`9004`	业务异常	结合业务返回内容定位原因
`2001`	未备案或套餐已过期	核对备案及套餐有效期
`2010`	服务可行，但套餐余量不足	核对可用套餐余量
`9999`	服务处理异常	记录请求信息并联系服务方
`3000`	电局登录失效	按电局流程恢复登录状态

响应码与接口特有的业务错误分别处理，接口页面有更具体定义时以其业务约定为准。

场景	处理要点
分页与日期	`current` 从 1 开始；`size` 按接口上限填写。退税率文库上限 500，进项发票查询上限 1000；日期和金额类型按节点定义填写
提交或报送超时	先核对是否已受理，再按约定重试；幂等键、重试次数与间隔由业务协议确认
退税状态或反馈未就绪	按业务状态跟踪，不将外层成功码当作申报已完成；轮询频率与终态由接口提供方确认
单点登录	`GET /login` 的 token 来源、有效期、type 及跳转行为按当前部署确认
联调日志	保留时间、接口、HTTP 状态、响应码和业务错误，避免记录私钥、密码及完整敏感报文

上线前确认服务地址、企业权限、允许的签名与加密组合、时间偏差、测试向量、业务状态、超时核对及重试规则。尚未确认的约定在联调时明确后执行。

07 · 接入前待确认

范围	当前可用定义	需补充资料
AI 问数（如当前部署提供）	已维护请求字段和明文示例；新会话可省略 `Session-Id`	实际 JSON / 流式响应、会话返回方式，以及补充回答接口的完整请求协议
CRM 注册	已维护现有请求字段；套餐、企业类型和 `oss` 按部署约定填写	枚举、字段含义、实际成功及失败响应
单点登录	`GET /login` 通过 query 传 `token、type`	token 来源及有效期、完整 type 枚举、HTTP 状态与跳转结果
匹配台账 `lyxt`	当前模型约束为最少 50 个字符，示例符合现有约束	后端长度约束；确认前不将最小长度直接改成最大长度

以上项目按现有定义维护，真实响应和未确认的枚举以部署方提供的实现资料补齐。

08 · 代码参考与兼容说明

「接入指南 / 加签加密示例」提供完整代码：

文档	用途
`RSA_3DESDemo`	请求组装，以及响应验签、解密的调用示例
`RSAUtil`	RSA 签名、验签、密钥读取和签名串拼接
`SecurityUtil`	DESede 加解密工具类

代码通过环境变量读取配置，不包含企业密钥或密码。旧版 SecurityUtil 使用 Cipher.getInstance("DESede")，模式与填充由提供者确定，密码字节沿用默认字符集。旧版 RSAUtil 按原排序索引插入连接符，首项为 null 时可能产生前导 &，因此外层字段避免 null。跨语言接入应使用双方确认的签名串、密码字节、密文及签名测试向量核对实现。

09 · 演示签名核对

演示密码与公钥

接入指南

接入指南#

阅读导航#

01 · 快速开始#

02 · 接入配置#

03 · 公共报文#

请求字段#

响应字段#

04 · 加签与加密#

请求处理#

响应处理#

05 · 明文与密文示例#

06 · 业务结果与异常定位#

07 · 接入前待确认#

08 · 代码参考与兼容说明#

09 · 演示签名核对#

接入指南

阅读导航

01 · 快速开始

02 · 接入配置

03 · 公共报文

请求字段

响应字段

04 · 加签与加密

请求处理

响应处理

05 · 明文与密文示例

06 · 业务结果与异常定位

07 · 接入前待确认

08 · 代码参考与兼容说明

09 · 演示签名核对