技术开发对接指南

本文档帮助合作伙伴快速理解数据接口服务的对接方式，掌握从参数封装、加密传输到数据解析的完整流程，轻松完成系统对接。

下载接口手册 下载示例代码 快速开始

一、快速入门

数据接口服务开放海量数据资源与服务，并通过接口形式提供给合作伙伴，帮助合作伙伴创建更具竞争力的应用。此文档是帮助合作伙伴快速理解数据接口服务的对接方式，并对合作伙伴可使用的服务内容做出了详细的描述。

1.1 开发前的准备工作

成为合作伙伴

联系服务商开通接口服务的账号和资源

确定开发语言

支持 Java、PHP、Python 三种开发语言对接

掌握加密逻辑

掌握基本的 RSA 和 DES 加解密逻辑

获取接入信息

用户ID、数字证书、示例代码、服务地址

1.2 专用术语

术语说明
用户ID 为每个用户分配的唯一标识，由 32 位的字母和数字组成
数字证书 也称为 RSA 密钥，是服务商为每个用户提供的数据加解密密钥文件，文件名为 public_用户ID.key
示例程序 服务商提供的调用接口 DEMO 示例代码
服务地址 调用接口时访问的 URL 域名地址
服务方法 详见服务商提供的接口服务方法列表，调用不同服务方法可获取不同结果集

1.3 了解示例代码

为了确保快速掌握数据接口的调用方法，示例程序文件包含 3 个主要文件：

文件名描述路径
AuthTest.java 测试类 \DEMO_java\src\test\java\
AuthUtils.java 加密解密类 \DEMO_java\src\main\java\com\quantum\entinfo\utils\
HttpRequest.java HTTP 请求类 \DEMO_java\src\main\java\com\quantum\entinfo\http\

Maven 依赖

示例程序文件的正常调用，需要额外依赖以下 Maven 包文件，这些文件在示例代码中已经包含：

文件版本
Auantum-auth1.0-SNAPSHOT
Lite1.0.0
Junit4.8.2
Log4j1.2.16

代码调试的必要参数

打开示例程序的 AuthTest.java 文件，用户需要在三个位置补充服务商提供的用户信息。本示例是调用的 getEntByKeyword 接口方法，返回名称中带有"查询关键字"的企业列表。

代码运行的正确结果

示例程序正常的运行结果应该如下所示（根据用户权限字段会有所不同），若没有返回正确结果，请根据返回的错误信息，到【错误代码】章节寻找错误代码解释并进行调整：

JSON 
{
    "UID": "00000000000000000000000000000000",
    "PAGEINFO": {
        "TOTAL_COUNT": 84,
        "TOTAL_PAGE": 9,
        "CURRENT_PAGE": 1
    },
    "ISUSUAL": "1",
    "ORDERINFO": {
        "ORDERDATE": "2019-01-29 00:44:23",
        "ORDERNO": "190129004423574013579"
    },
    "VERSION": "1.1.2",
    "RESULTDATA": [
        {
            "IS_JYZXGS": "",
            "DOM": "北京市海淀区北清路68号",
            "ENTSTATUS": "在营（开业）企业",
            "REGCAP": 146429.3443,
            "FRDB": "王文京",
            "EMAIL": "yonyou@yonyou.com",
            "OLDNAME": "北京用友软件股份有限公司,用友软件股份有限公司",
            "ESDATE": "1995-01-18",
            "REGNO": "110000005119254",
            "ENTNAME": "用友网络科技股份有限公司",
            "TEL": "86396688",
            "WEBURL": "http://www.yonyou.com",
            "PROVINCE": "",
            "SHXYDM": "91110000600001760P"
        }
    ],
    "ISMATCH": "1"
}

二、接口调用方法

接口服务的调用需要按照流程和规范封装参数信息，同时为了确保数据传输的安全性，与接口服务的所有通讯均采用 RSA2048 位加密。本节针对接口调用的多个环节进行详细介绍，让使用者能够掌握接口调用逻辑和要求。

2.1 接口调用流程

接口调用共分为 七个流程，按顺序执行即可完成数据查询：

参数封装
用户选择调用的接口，并将参数按要求格式封装为 JSON
消息加密
利用加密密钥对发送的信息进行 RSA+DES 双重加密
调用接口
向接口发送查询请求，并接收返回的结果（超时时间 30 秒）
消息解密
对返回的加密结果进行 RSA+DES 解密，获取原始 JSON
判断有效性
根据 ISUSUAL 和 ISMATCH 判断返回结果是否有效
解析数据集
从 RESULTDATA 中提取所需的业务数据
业务处理
将解析后的数据集成到自有业务系统中

2.2 参数封装

接口服务的调用需要将参数封装为 Json 格式，其中 uid 是服务商分配给用户的 32 位字符串，service 是需要调用的接口名称（具体参见【三、接口服务授权清单】），params 是调用的接口需要的参数，每个接口调用的参数是不同的。

下面我们以【企业名称检索（getEntByKeyword）】为例介绍参数封装规范：

JSON 
{
    "uid": "00000000000000000000000000000000",
    "service": "getEntByKeyword",
    "params": {
        "keyword": "用友网络",
        "type": "0"
    }
}
名称类型描述
uidString用户ID，由服务商分配的32位唯一标识
serviceString调用的接口服务名称，具体参见【三、接口服务授权清单】
paramsMap参数集合，格式为 "参数名":"参数内容"

2.3 消息加密

为确保通讯过程中的数据安全，接口服务要求通讯内容采用 RSA + DES 加密。服务商会为每个用户单独分配一个 RSA2048 位密钥，且每个用户的密钥是唯一的。

加密后的格式如下：

JSON 
{
    "key": "P/uAcIy70iG9e7agCB45LTBwcmpJzUzI0Av7Sspcpru+V9MWmMi0dituTytH2a6L0xMA1NG7RvuumKE9H6LJQHd75b7QC2xKNI=",
    "value": "3146gHTujY98ISIbPA1lRbNnZLGNwPH+tKOGiL9wcSKPRMACU1VYeGMBbQ1RhmgmF4Bh4FRuEKvPIypQjjMjAXMuVmu0qc9T5qWxHVloVejkjiHIP/CXW5TED0vE7SOAHtkZpthkwKnYHg0zG1Y9YFIFwnaDGMiWNcca3F5z"
}

由于使用了 DES+RSA 双重加密的方式，即使相同的查询内容，每次加密的结果都不相同。加密结果包括 key 和 value 两个节点，加密流程分别为：

生成 DES 密码
生成一个 32 位随机字符串，作为对称加密（DES）的密码。
加密 Value 节点
将封装的参数 Json 通过 UrlEncode(UTF-8) 进行编码，再用 32 位随机字符串密码对编码后的 Json 进行 DES 加密，加密结果保存在 value 节点下。
加密 Key 节点
使用非对称加密（RSA2048）对 32 位随机字符串密码进行加密，加密后的结果保存在 key 节点下。

2.4 调用接口

加密后的结果通过 sendPost 方法发送至服务器，服务器会实时将查询结果进行反馈。接口调用的超时时间是 30 秒，超过则会自动中断。

注意事项
请确保服务地址正确，且网络环境可以正常访问服务商提供的域名。若调用超时，建议检查网络连接或联系服务运维人员。

2.5 消息解密

接口服务返回的查询结果采用加密形式，返回的加密结果包含 value 和 key 两个节点，需要用户采用 RSA+DES 方式解密，解密流程分别为：

解密 Key 节点
使用非对称解密（RSA2048）解密获取 32 位字符串密码。
解密 Value 节点
将上一步解密获取的 32 位字符串密码，作为对称解密（DES）的密码对 value 节点内容进行解密，获取原始 Json 信息。

解密后的结果如下所示：

JSON 
{
    "UID": "00000000000000000000000000000000",
    "PAGEINFO": {
        "TOTAL_COUNT": 84,
        "TOTAL_PAGE": 9,
        "CURRENT_PAGE": 1
    },
    "ISUSUAL": "1",
    "ORDERINFO": {
        "ORDERDATE": "2019-01-29 00:44:23",
        "ORDERNO": "190129004423574013579"
    },
    "VERSION": "1.1.2",
    "RESULTDATA": [
        {
            "ENTNAME": "用友网络科技股份有限公司",
            "SHXYDM": "91110000600001760P",
            "...": "..."
        }
    ],
    "ISMATCH": "1"
}

2.6 判断有效性

解密后的 Json 包含订单信息、数据信息和状态信息，其中状态信息中的 ISUSUAL 和 ISMATCH 用于判断返回的结果是否有效。

字段描述
ISUSUAL订单有效性标志，1 有效，0 无效；接口服务接受请求并正确返回结果，该查询有效，执行计数操作。
ISMATCH企业有效性标志，1 匹配，0 未匹配；接口服务根据用户传入的企业名称，会对企业有效性进行判断，若查询的企业不存在，则返回 0。

如果接口调用失败则会收到错误说明，错误说明的格式如下，其中 ERRORCODE 为错误代码，ERRORVALUE 为错误描述：

JSON 
{
    "UID": "00000000000000000000000000000000",
    "ISUSUAL": "0",
    "ORDERINFO": {
        "ORDERDATE": "2019-02-13 00:00:00",
        "ORDERNO": "190213000000050034382"
    },
    "RESULTDATA": {
        "ERRORVALUE": "数据参数格式错误",
        "ERRORCODE": "0010040002"
    },
    "ISMATCH": "0"
}

2.7 解析数据集

解密后的 Json 包含订单信息、数据信息和状态信息，下表对解密后的 Json 结构进行详细说明，以便开发人员理解和解析数据。

名称类型描述
UIDString用户ID
PAGEINFOMap分页信息，仅分页接口使用
TOTAL_COUNTNumber数据信息记录总数
TOTAL_PAGENumber数据信息分页数
CURRENT_PAGENumber数据信息当前页码
ISUSUALString订单有效性标志，1有效，0无效
ORDERINFOMap订单信息
ORDERDATEString订单生成时间（YYYY-MM-DD HH:MM:SS）
ORDERNOString订单编号
VERSIONString接口版本号
RESULTDATAList/Map数据信息（若多个数据集则采用 {……},{……} 格式）
ISMATCHString企业有效性标志，1匹配，0未匹配

2.8 公共参数索引

接口调用过程中，输入过程或输出过程会依赖部分公共参数，下表列举了所有输入和输出过程需要的所有参数，并对参数的具体用途作出详细解释。

参数名类型描述
UIDString用户编码，由服务商分配，每个用户唯一
PAGEINFOMap分页信息，仅分页接口使用
TOTAL_COUNTNumber数据信息记录总数
TOTAL_PAGENumber数据信息分页数
CURRENT_PAGENumber数据信息当前页码
ORDERINFOMap订单信息集
ORDERNOString订单编号
ORDERDATEString订单生成时间（YYYY-MM-DD HH:MM:SS）
VERSIONString接口版本号
RESULTDATAList/Map数据信息（若多个数据集则采用 {……},{……} 格式）
ERRORCODEString错误代码
ERRORVALUEString错误中文解释
ISUSUALString订单有效性标志，1有效，0无效
ISMATCHString企业有效性标志，1匹配，0未匹配
KEYString加密结果中，用于存放被 RSA 加密后的字符串
VALUEString加密结果中，用于存放被 DES 加密后的参数集或结果集
SERVICEString调用的接口服务名称，具体参见【三、接口服务授权清单】
PARAMSMap提交查询参数的集合

四、错误代码

当接口调用失败时，系统会返回对应的错误代码及错误描述。请根据下表定位问题原因并进行调整。

错误代码描述
0010010001未传入服务名称
0010010002服务不存在
0010010003提供者执行错误
0010010004调用服务超时
0010010005查询队列已满
0010010006未传入参数
0010010007底层服务无响应
0010010008未知错误
0010010009接口查询，未知错误，请联系服务运维人员！
0010010010用户信息核验超时，请联系服务运维人员！
0010010011接口查询超时，请重新查询或联系服务运维人员！
0010010012用户信息核验节点出现问题，请联系服务运维人员！
0010010013接口查询节点出现问题，请联系服务运维人员！
0010020001RSA(2048)私钥未找到
0010020002RSA(2048)解密错误
0010020003RSA密文为空
0010020004RSA(2048)加密错误
0010020101DES解密错误
0010020102DES加密错误
0010020103DES密文为空
0010020104URL转码失败
0010030001用户ID错误
0010030002用户IP授权错误
0010030003用户权限信息错误
0010030004用户状态为无效
0010030005用户已过期
0010030006用户并发超时
0010030007用户ID不一致
0010030008校验权限服务调用超时
0010040001POST参数格式错误
0010040002数据参数格式错误
0010040003输入参数为空
0010040004输入参数非法
0010060001该接口访问已达到上限
0010060002当天访问已达到上限
0010060003当月接口访问已达到上限
00100600041秒内访问超量
0010080001没有权限访问此接口
0010080002权限不足
0010100001接口查询错误
0010100002接口查询超时

示例代码下载

我们提供了多种语言的示例代码，帮助您快速完成系统对接。下载后请根据文档说明补充您的用户 ID 和数字证书即可运行。

SDK & 示例代码

包含 Java、Python 等主流语言的完整 Demo 工程及依赖包

Download
Java Demo
Download
Python Demo

提示：示例代码中包含 Maven/PIP 依赖配置及详细的注释说明，建议结合本文档一起使用。