ICS 03.100.01 A 02 DB13 河 北 省 地 方 标 准 DB 13/T 2709—2018 法人和其他组织统一社会信用代码数据库 访问服务接口技术规范 2018- 04 - 09 发布 河北省质量技术监督局 2018 - 05 - 09 实施 发 布 DB13/T 2709—2018 前 言 本标准按照GB/T 1.1-2009给出的规则起草。 本标准由河北省质量技术监督局提出。 本标准由河北省服务标准化技术委员会（SAHB/TC 264）归口。 本标准起草单位：河北省标准化研究院、石家庄宇邦软件科技有限公司。 本标准起草人：阎占辉、董世涛、李虓峰、高龙、于潇、闫志强、李英君、孙明立、李会、孙家 田。 I DB13/T 2709—2018 法人和其他组织统一社会信用代码数据库 访问服务接口技术规范 1 范围 本标准规定了法人和其他组织统一社会信用代码数据库访问服务接口（以下简称统一代码接口） 的术语、定义和缩略语、统一代码接口框架、统一代码接口要求、统一代码接口服务数据项和统一代 码接口调用状态信息。 本标准适用于政府部门以接口方式进行的统一社会信用代码数据库信息共享应用。 2 规范性引用文件 下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文 件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 GB/T 2260 中华人民共和国行政区划代码 GB/T 4754 国民经济行业分类 GB 32100 法人和其他组织统一社会信用代码编码规则 3 术语、定义和缩略语 3.1 术语和定义 下列术语和定义适用于本文件。 3.1.1 接口 interface 体现一个实体行为特征的具体名称的操作集。 3.1.2 请求 request 接口用户向接口发出的一次调用申请。 3.1.3 响应 response 接口向接口用户返回请求的操作结果。 3.1.4 包体 entity-body 数据传输中的实体主体部分。 3.2 缩略语 下列缩略语适用于本文件。 1 DB13/T 2709—2018 HTTPS 基于安全套接字的超文本传输协议（Secure hypertext transfer protocol） XML 可扩展标识语言（Extensible markup language） JSON JS对象标记(JavaScript object notation) 4 统一代码接口框架 4.1 许可和调用 4.1.1 接口用户向接口提供方提交使用申请，用户申请信息包括： a) b) c) d) e) 机构统一社会信用代码； 机构名称； 用于实现应用接口功能的设备的 IP 地址； 申请使用期限； 申请使用数据项。 4.1.2 接口提供方收到申请后，生成许可信息反馈给接口用户，许可信息包括： a) b) c) d) e) f) g) 机构统一社会信用代码； 机构名称； 用于实现应用接口功能的设备的 IP 地址； 申请使用期限； 用户账号； 用户密码； 接口地址。 4.1.3 接口用户在调用接口时，应提供被授予的许可信息。 4.1.4 接口在接收到请求后，校验接口用户许可信息中用于实现应用接口功能的设备的 IP 地址和申 请使用期限的有效性、用户账号和用户密码的合法性，检验通过后，执行请求，返回响应内容。 4.2 应用模型 统一代码接口应用模型见图1。 请求 接 口 用 户 接 口 响应 图1 2 统一代码接口应用模型 DB13/T 2709—2018 5 统一代码接口要求 5.1 接口定义 统一代码接口定义见表1。 表 1 统一代码接口定义 定义 String Tydm_sh_service (string licence, string cond_information, string repl_packagetype) 说明 1. 2. 3. 4. 5. Tydm_sh_service 为约定的接口名称。 license 为许可参数(见 5.3)。 cond_information 为条件参数(见 5.4)。 repl_packagetype 为返回结果数据包格式参数(见 5.5)。 接口返回结果见 5.6。 5.2 基本约定 5.2.1 传输协议 采用HTTPS作为传输协议。 5.2.2 地址格式 接口地址由接口提供方提供，格式为：https://xxx.xxx.xxx.xxx/services_path/service_name。 其中：xxx.xxx.xxx.xxx表示接口所在的服务器的有效地址；services_path表示接口的发布路径， 由接口提供方命名；service_name表示约定的接口名称，由接口提供方命名。 5.2.3 安全性 接口用户以接口提供方授权的许可为凭据调用接口。 5.2.4 调用方法 统一代码接口调用方法实例参见附录A。 5.3 许可参数 5.3.1 内容组成 许可参数由一组用户信息组成。 5.3.2 包体标记及含义 许可参数包体标记及含义说明见表2。 3 DB13/T 2709—2018 表 2 许可参数包体标记及含义 信息类别 用户信息 标记 字符类型及长度 含义 说明 tydm nvarchar(18) 机构统一社会信用代码 --- jgmc nvarchar(400) 机构名称 --- appkey nvarchar(8) 用户账号 --- appsecret nvarchar(10) 用户密码 --- ip nvarchar(15) 被授权应用接口的设备的 IP 地址 --- startdate nvarchar(10) 使用期限开始时间 授权起始日期 enddate nvarchar(10) 使用期限结束时间 授权终止日期 5.3.3 包体格式说明 许可参数包体采用JSON格式。 许可参数放置在标记{…}之间，见示例1。 示例1： { "tydm": "xxxxxxxxxxxxxxxx", "jgmc": "xxx", "appkey":"xxx", "appsecret":"xxx", "ip": "xxx", "startdate": "xxx", "enddate":"xxx" } 5.4 条件参数 5.4.1 内容组成 条件参数由条件逻辑关系、条件数据项集、返回结果数据项名称组成。见图2。 条件数据项集 条件逻辑关系 条件数据项 1 „„ 图 2 条件参数 5.4.2 包体格式说明 条件参数包体采用JSON格式。 4 返回结果数据项名称 条件数据项 n DB13/T 2709—2018 条 件 参 数 放 置 在 标 记 {"exp":"xxx","fields":[{"field":"xxx", "operation":"xxx", "value":"xxx"},…,{ "field":"xxx", "operation":"xxx", "value":"xxx"}], "result":"xxx"}之 间。 exp关键字为条件逻辑关系。其中与、或分别用*、+标识；为空时，默认为与；在逻辑关系中，第 一个条件数据项用[0]表示，第二个用[1]表示，以此类推，第n个用[n-1]表示，各条件之间可以用圆 括号运算符（）组合。 fields关键字为条件数据项集。其中field关键字为条件数据项；operation为条件数据项的关系 运算符，其表示及含义见表3；value为条件数据项的值。 result关键字为返回结果中用户要求的数据项名称，各数据项间以“,”分隔。 数据项标识应符合本标准第6章的规定。 表 3 关系运算符表示及含义 关系运算符 含义 = 等于 < 小于 > 大于 <= 小于或等于 >= 大于或等于 说明 字符型按字符编码顺序进行比较 数值型应转换成数值进行比较 日期型应转换成日期进行比较 日期时间型应转换成时间进行比较 <> 不等于 like 模糊匹配 仅可应用于字符型的数据项，从字符串任意位置进行匹配 left like 左匹配 仅可应用于字符型的数据项，从字符串起始端匹配 right like 右匹配 仅可应用于字符型的数据项，从字符串尾端匹配 is null 空值 --- is not null 非空 --- 条件参数包体格式见示例2。 示例2： { "exp":"[0]*([1]*[2])", "fields":[ { "field": "xzqh", "operation": "=", "value": "xxx" }, { "field": "jgmc", "operation": "like", "value": "xxx" }， { "field": "jgmc", "operation": "like", "value": "xxx" 5 DB13/T 2709—2018 } ] "result":"tydm,jgmc,xzqh" } 5.5 返回结果数据包格式参数 接口返回结果数据包格式参数由接口用户根据需要设定。该参数取值可为xml或json，不能为空。 5.6 返回结果 5.6.1 内容组成 返回结果包括接口调用状态信息、结果数据和结果集记录个数组成。接口调用失败时，只返回接 口调用状态信息。见图3。 接口调用状态信息 结果数据 结果数据记录 1 „„ 结果集记录个数 结果数据记录 n 数据项 1„数据项 n 图 3 返回结果 5.6.2 包体格式说明 5.6.2.1 XML 格式 XML格式采用标准DATAPACKET 2.0版本。 返回结果中的接口调用状态和结果集记录个数信息放置在标记<RESPDATA>„</RESPDATA>之间, 关键字status为调用状态代码，msg为接口调用状态描述，totalcount为结果集记录个数。接口调用状 态代码和描述应符合本标准第7章的规定。 结果数据置于标记<ROWDATA>„</ROWDATA>之间。结果数据不同记录间用<ROW…/>„<ROW…/>分 隔。数据项标识应符合本标准第6章的规定。 返回结果包体XML格式见示例3。 示例3： <?xml version="1.0" encoding="UTF-8"?> <DATAPACKET Version="2.0"> <RESPDATA> <RESP status="0" msg="调用成功" totalcount="2" /> </RESPDATA> <ROWDATA> <ROW tydm=" XXXXXXXXXXXXXXXXXX "j