中国银行间市场交易商协会开放接口（iOpenAPI）系统总体技术规范

第1章引言

1.1 编写目的

本文档旨在通过建立统一的系统设计及功能开发规范，为开放接口系统功能建设、内部拟接入数据服务接口开发、外部机构接入接口开发过程提供规范、一致的技术指导。

1.2 阅读对象

本文档主要面向的读者和使用人员包括协会开放接口系统、外部接口接入系统及内部数据服务接口系统相关开发、测试及运维支持人员。

1.3 使用说明

1.4 术语定义

名称	定义
机构	与协会通过开放接口系统进行业务对接的机构。
报文	协会接口系统与机构系统之间交换的结构化信息。
协会开放接口系统（简称开放接口系统）	协会与外部机构进行业务数据交互、系统对接的统一入口及数据服务管控平台。

外部接口接入方

机构端应用系统，可按照接口接入管理办法要求与协会开放接口系统进行业务数据交互。
内部数据服务接入方	结合具体业务场景中数据交互需求，按照开放接口系统基础报文规范提供相关交互接口具体功能实现的内部组件

第2章总体方案

2.1 外部接口接入方案

发送事务确认请求

1) 若一次传输过程涉及多条业务数据记录，多条业务数据记录

可以通过多个报文进行发送。

2) 同一事务下各报文拥有相同的事务编号，并由报文头中

msgCnt 指定事务下报文总数量。

3) 各报文msgId 从编号"00000001"开始连续递增。

4) 接收端对各条报文发送反馈报文，反馈报文中事务编号及报

文编号与发送方各报文对应一致。

5) 对于同一事务下存在多条报文的情况，最后一条报文作为事务结束报文，事务状态须设置为 1，该报文不携带业务数据，仅作为事务结束确认。接收方将基于该报文反馈该次事务数

据完整性校验及执行结果。

涉及基础技术字段如下：

中文名称	英文名称	类型	必填	描述
报文状态	msgState	Number	是	枚举值： 0:正常报文 1：正常报文反馈 2：重发报文 3：重发报文反馈
事务编号	transUuid	str	是	该字段为技术约束，同一次传输使用相同的唯一事务编号， 64 位。各次传输需使用不同的事务编号。
事务下报文数量	msgCnt	Number	是	默认值为 1
事务状态	tranState	Number	否	当 msgCnt 大于 1 时，该字段必填。枚举值：

0:传输中

1：确认结束，最后一条报文使用该枚举值进行事务结束确认。

报文编号

msgUuid

str

是

8 位数字，由 8 位顺序码组成，顺序编码。

3.6 事务重发机制

为保障双方数据交互过程可靠性，本规范在消息交互过程设计如

下重发机制：

1) 接收方在接收完毕某某次事务过程所有报文后（以接收到本次正常传输过程结束报文为准），在结束报文反馈中明确是否需要重传全部或部分报文。接收方在结束报文反馈中以“反

馈状态”字段标示重传（取值 303）。

2) 发送方发送重传报文时，所有报文 msgState=2, 事务编号与初次发送事务编号一致，消息编号与初次发送时各报文编号

一致。

3) 接收方对重传报文进行反馈时，所有报文 msgState=3, 事务编号与初次发送时事务编号一致，消息编号与初次发送时各

报文编号一致。

涉及基础技术字段如下：

中文名称	英文名称	类型	必填	描述
报送机构代码	sendId	str	是	机构代码（北金所预先分配的 8 位代码）
报送机构全称	senderName	str	是	机构全称
报送机构用户名	userName	str	是	用户名

接收机构名称	targetName	str	是	接收方机构代码（北金所预先分配的 8 位代码）
报文状态	msgState	Number	是	枚举值： 0:正常报文（发送方使用） 1：正常报文反馈（接收方正常反馈时使用） 2：重发报文（发送方重发报文使用） 3：重发报文反馈（接收方对重发报文进行反馈时使用）
事务编号	transUuid	str	是	该字段为技术约束，同一次传输使用相同的唯一事务编号， 64 位。各次传输需使用不同的事务编号。
报文编号	msgUuid	str	是	8 位数字，由 8 位顺序码组成，顺序编码。

3.7 会话机制

3.8 Schema 机制

开放接口系统建立 Schema 校验机制，支持对 XML、JSON 报文进行格式校验。1. 服务请求方根据业务场景各接口报文规范构造分页查询服务请求，涉及分页请求字段如下：

中文名称	英文名称	类型	必填	描述
页码	pageNo	Number	否	本次拟查询页码; 默认返回第一页
每页记录数	pageSize	Number	否	本次查询每页拟显示记录数：默认一页返回所有记录
最大查询页数	maxPageNum	Number	否	拟查询最大页数

2. 内部数据服务方根据业务场景提供分页处理并返回分页结果。

中文名称	英文名称	类型	必填	描述
页码	pageNo	Number	是	本次返回数据页码
总页数	totalPageN um	Number	是	本次返回数据总页数
当前页记录数	currentPag eItemCnt	Number	是	当前页有效记录数

3.10 超时重发机制

第4章报文语法与结构

4.1 报文数据类型

数据类型用于定义报文域的取值类型，本协议使用的数据类型由几个基本的数据类型（数值、字符串、时间）和在此基础上扩展的数据类型组成。

4.1.1 数值

数值类型（number）可表示正负（ASCII 码字符“- ”，“0”至“9 ” 和“. ”组成），以及可选小数部分的数值。数值类型定义形式为(m.n)，m 表示整数位最大长度， n 表示小数位精度。

4.1.2 字符

字符类型（str）指由字母、数字以及符号组成的字符。字符类型定义形式为(n)，n 表示字符最大长度。字符类型域取值为空时用“”表示。

4.1.3 时间

时间类型（date）用来表示时间及符号组成的字符。时间类型定义形式为 (YYYYMMDD-HH:MM:SS.sss) 或其中节选部分如日期为（YYYYMMDD），其中，YYYY=0000-9999，MM=01-12，DD=01-31，HH=00-23，MM=00-59，SS=00-60(秒)，sss=000-999（毫秒）。

4.1.4 扩展数据类型

当数值、字符、时间类型无法满足数据类型的表示要求时，可自定义扩展数据类型。扩展数据类型需对取值的限定进行准确的说明。

4.2 报文结构

报文结构包括报文头和报文体，具体如图所示：

4.3 报文头

每个报文都应该包含报文头，用于说明报文发送方、身份认证信息、报文编号、报文发送时间、报文返回结果等内容。参考标准如下：

1. 发送方报文基础技术字段

中文名称

英文名称

类型

必填

描述

发送机构代码	sendId	str	是	机构代码（北金所预先分配的机构代码）
发送机构全称	senderName	str	是	机构全称
发送机构用户名	userName	str	否	用户名
接收机构代码	targetId	str	是	机构代码（北金所预先分配的机构代码）
接收机构全称	targetName	str	是	机构全称
服务功能代码	funcId	str	是	服务功能代码
服务功能版本	funcVer	str	否	服务功能版本， 0000 默认为最新版本
报文状态	msgState	number	是	枚举值： 0:正常报文 1：正常报文反馈 2：重发报文 3：重发报文反馈
事务编号	transId	str	是	该字段为技术约束，同一次传输使用相同的唯一事务编号， 64 位。各次传输需使用不同的事务编号。
事务下报文数量	msgCnt	Number	是	默认值为 1
报文编号	msgId	str	是	8 位数字，由 8 位顺序码组成，顺序编码。
报文发送时间	msgTimeStamp	str	是	如下格式的报文发送时间戳 "yyyy-MM-dd HH:mm:ss SSS"

2. 反馈报文基础技术字段

中文名称	英文名称	类型	必填	描述
反馈报文发送机构代码	sendId	str	是	机构代码（北金所预先分配的 8 位代码）
反馈报文发送机构全称	senderName	str	是	机构全称信息
反馈报文接收机构代码	targetId	str	是	机构代码（北金所预先分配的 8 位代码）
反馈报文接收机构全称	targetName	str	是	机构全称
服务功能代码	funcId	str	是	服务功能代码