T_SIOT 326-2022 智慧健康养老 为老服务“一键通”系统接口要求.docx

ICS 35.240.80CCS L 67团体标准T/SIOT 326-2022智慧健康养老为老服务“一键通”系统接口要求Smart health and elderly care- System interface requirement of "One-Press-Done" system2022 - 12-16 发布2022 -12 -30 实施上 海 市 物 联 网 行 业 协 会发 布T/SIOT 326-2022目次前言 . II1范围 . 12规范性引用文件 . 13术语和定义 . 14缩略语 . 25接口总体要求 . 25.1对接范围 .5.2接口要求 .225.2.1概述 . 25.2.2协议 . 25.2.3接口类型 . 25.2.4接口版本要求 . 25.2.5接口方式 . 35.2.6接口参数 . 35.2.7信息过滤 . 35.2.8返回参数 . 35.2.9其他要求 . 36接口接入要求 . 46.16.26.36.46.56.66.7接口开发 . 4存量数据处理 . 4接口确认 . 4接口测试 . 4接口服务注册 . 4接口上线 . 4接口变更 . 4附录 A（资料性）为老服务“一键通”数据平台通信报文消息实例 . 5附录 B（资料性）打车订单状态定义 . 18附录 C（资料性）异常码参照表 . 19参考文献 . 20IT/SIOT 326-2022智慧健康养老 为老服务“一键通”系统接口要求1范围本文件规定了为老服务“一键通”信息化平台对于上下级平台的系统接口要求。本文件适用于为老服务“一键通”信息化平台的开发和实施，和为老服务“一键通”进行业务对接的服务机构系统以及其他第三方为老服务子系统对接为老服务“一键通”信息化平台的开发依据。以及第三方测评机构进行接口对接测试和验证的依据。本文件的使用者包括为老服务行业信息化软件企业、独立软件测试机构、为老服务信息化产品的软件开发组织、实施及咨询服务机构等。与为老服务信息化开发有关的其他领域亦可参考使用。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T 18894 电子文件归档与电子档案管理规范GB/T 25058 息安全技术 网络安全等级保护实施指南GB/T 28452 息安全技术应用软件系统通用安全技术要求GB/T 35273 信息安全技术 个人信息安全规范GB/T 35279 息安全技术 云计算安全参考架构3术语和定义下列术语和定义适用于本文件。3.1智慧健康养老 smart health and elderly care面向居家老年人、社区及养老机构的传感网系统与信息平台，并在此基础上提供实时、快捷、高效、低成本的，物联化、互联化、智能化的养老服务。T/SIOT 310-2020 定义3.13.2数据服务 data service通过一定的技术手段，对外提供为老服务“一键通”相关信息资源。3.3应用程序接口 application programming interface预先定义的接口（函数、HTTP接口），或指软件系统不同组成部分衔接的约定。注：用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而有无需访问源码，或理解内部工作机制的细节。通过程序调用接口，通常用于查询或核验信息。3.4基础服务系统 basic service system通过对系统对接不同类别的数据进行存储、计算、挖掘分析的加工处理，生成具有语义和格式统一的数据的系统。3.5为老服务“一键通” “One-Press-Done” for old service1T/SIOT 326-2022借助为老服务“一键通”信息化平台，并通过多终端（固话终端、电视终端、自助终端、移动终端等）的多路径覆盖，为广大老年人提供紧急救援、助医、出行、政策、生活、家政、社交等高频急难服务。4缩略语下列缩略语适用于本文件。API：应用程序接口（Application Programming Interface）APP：程序（Application）IP：网络互联协议（Internet Protocol）JSON：JavaScript对象简谱（JavaScript Object Notation）SOAP：简单对象访问协议（Simple Object Access Protocol）XML：可扩展标记语言（Extensiable Markup Language）5接口总体要求5.1对接范围为老服务“一键通”信息化平台应对接：a)  上级平台；b)  第三方为老服务子系统，服务机构子系统以及其他独立为老服务子功能系统。5.2接口要求5.2.1概述接口应能让资源提供方开放自己的资源访问权限来提供数据基础服务系统，又能确保数据安全性让资源提供方继续握有控制权。资源提供方要根据业务情况描述接口功能，并且按照API规范进行开发接口，能让数据服务使用者更好的使用应用程序接口，高效的对接为老服务“一键通”信息化平台，提供更好的智慧健康养老服务。5.2.2协议为老服务“一键通”信息化平台的通信协议，宜采用HTTP超文本传输协议和HTTPS安全超文本传输协议两种且可扩展，本协议在标准HTTP和HTTPS协议上做了扩展完成，形成了三层协议标准，如图1所示。HTTP Header扩展协议头Payload（Data）图1三层协议5.2.3接口类型接口宜采用以下两种：a)HTTP API接口：请求报文格式为Key-Value形式，返回报文为JSON串，可采用GET和POST方法；b)WebService接口：报文通常走SOAP协议通过HTTP传输，请求报文和返回报文都是XML格式（助医挂号目前采用此方式）。5.2.4接口版本要求2T/SIOT 326-2022应该将API的版本号放入URL扩展协议头部，标记为Ver：XX.XX。协议应采用多版本API并存、增量发布的方式，对于一个API或者服务，应在生产中最多保留3个最详细的版本。版本号分为整数型和浮点型，整数型：大功能版本，如V1、V2；浮点型：补充功能版本，例：V2.1、V10.0。5.2.5接口方式接口宜采用以下两种方式：a)  GET：主动获取对端服务资源（一项或多项）；b)  POST：在对端服务上创建一个新的资源。如附录A中接口信息同步类的接口均采用POST方式。5.2.6接口参数接口接入参数宜采用：a)接口接入参数宜采用JSON格式、XML格式且可扩展，接入参数主要包括以下3种类型且可扩展：b)Params：URL后面跟参数，存放请求接口的参数数据；c)Header：消息头，根据需要存放公共参数、RequestId（请求者标识ID）、Token（验证令牌）、加密字段等；d)Body：消息体，存放请求接口的参数数据；e)资源提供方根据共享要求及相关安全考虑，建议在接口入参中增加调用IP、时间戳、随机数等字段。5.2.7信息过滤记录数量过多，服务方不可能一次性反馈所有数据给请求方，API应该提供数据分页参数及其他筛选参数，具体数据条目应采用参数控制，过滤返回结果。如附录A.13挂号工单分页查询。5.2.8返回参数返回参数包括：a)Code：接口响应状态代码，服务提供方应遵守标准HTTP协议返回码，超出HTTP标准返回码的可扩展定义；b)Message：对接口响应状态代码的具体解释；c)Data：接口返回的具体数据（Json或者XML）。如附录B.1定义了打车订单状态码表，附录B.2定义了订单取消原因码表。附录C定义了异常码参照表。5.2.9其他要求其他要求内容包括：a)设计接口应该考虑限流设计、熔断设计、降级设计等；b)设计接口应该考虑敏感数据保护或者脱敏处理，对敏感数据以特符号掩码处理。c)接口应保存调用日志记录，故障定位和日志统计分析；d)API应该提供分页参数及其他筛选参数，结果分页返回。e)接口应有接口说明文档，接口文档中应该包括以下内容：1)  接口地址：不包括接口的基础（BASE）地址；2)  请求方式：GET、POST 等；3)  请求参数：请求的数据格式，参数含义、参数类型、长度、精度等；4)  响应参数：参数含义、参数类型、取值范围等；3T/SIOT 326-20225)  错误代码说明表；6)  其他：如算法生成说明，如 Token 规则等；7)  当接口发生变化时，应及时更新接口文档并提供给使用方。6接口接入要求6.1接口开发服务提供方应根据接口需要开发相应的接口，并提供详细接口字段说明文档。6.2存量数据处理接口后台的数据应保证其实时性及全面性，并且数据有更新时应该保证接口的返回参数不发生变化，或者向下兼容。6.3接口确认为老服务“一键通”信息化平台需确认各服务提供的接口应符合智慧健康养老 为老服务“一键通”应用功能通用要求（T/SIOT 325-2022）。6.4接口测试确认接口符合要求后，服务提供方需要提供接口测试环境访问地址、接口参数等相关信息，由为老服务“一键通”信息化平台进行对接并进行联调，测试接口是否可以正常使用。6.5接口服务注册为老服务“一键通”信息化平台将对服务提供方的接口在平台上进行接口注册。6.6接口上线为老服务“一键通”信息化平台对服务接口进行测试并且能够正常使用后，可将服务接口发布上线。6.7接口变更发生如下接口变更情况，需要通知为老服务“一键通”信息化平台，并进行重新接口对接和调试：a)原始接口地址发生变化；b)原始接口返回参数发生变化；c)原始接口遇到如服务升级、网络异常导致接口不通，服务不可使用；d)接口删除或者使用新的接口替代。4接口名/base/person/v1/sync请求方式PostJSON格式请求体"data":"", /使用3倍长密钥DES加密,"timestamp": "" /请求时间戳时间戳位13位时间戳 例如 1663212611677“sign”:“”/签名业务参数(加密前的data)类型说明是否必须（Y/N）nameString姓名YidCardString身份证号Y输出参数类型说明备注codeint200 表示成功messageString返回消息accessTokenString授权访问tokenexpiryTimeStringToken 的过期时间接口响应示例"code": 200,"expiryTime": "2022-09-07 14:46:03","accessToken": "6AACC862E96A3542C9D2231DDAE95523"接口名http:/IP:port/auth/v1/getAccessToken请求方式PostJSON格式输入参数类型说明是否必须（Y/N）appIdString分配接入一键通的账号YsercetString分配接入一键通的sercetYT/SIOT 326-2022A                    A附录A（资料性）为老服务“一键通”数据平台通信报文消息实例A.1授权服务接口名称：获取AccessToken。接口功能：该接口提供后访问业务接口的授权token。接口协议：HTTP。表A.1  获取接口输入参数表A.2  接口返回参数A.2服务对象(老人)信息同步接口名称：服务对象（老人）信息同步。接口功能：服务对象(老人)信息到一键通。接口协议：HTTP。表A.3  同步接口输入参数5sexString性别：0、女      1、男YageInt年龄YphoneString手机号YcensusProvinceString户籍省YcensusAreaString户籍区YcensusStreetString户籍街道YcensusCommitteeString户籍居委YcensusAddressString户籍详细地址YresideProvinceString居住省YresideCityString居住市YresideAreaString居住区YresideStreetString居住街道YresideCommitteeString居住居委YresideAddressString居住详细地址YtargerString标签信息：1、独居                      2、纯老3、低保    4、残疾NstatusString服务对象状态：0、死亡              1、正常2、迁出YgpsFinalTimeDate设备最后定位时间NcreateTimeDate创建日期YcreateUserString创建人YupdateTimeDate更新日期YupdateUserString更新人Y接口名/base/servicePerson/v1/sync请求方式PostJSON格式请求体"data":"", /使用3倍长密钥DES加密,"timestamp": "" /请求时间戳时间戳位13位时间戳 例如 1663212611677“sign”:“”/签名业务参数(加密前的data)类型说明是否必须（Y/N）输出参数类型说明备注codeint1 表示成功msgString返回消息dataString返回信息"code": 1,"msg": "success","data": "新增: 100,更新:20, 异常数据:0"T/SIOT 326-2022表A.4  同步接口返回参数A.3服务人员信息同步接口名称：服务人员信息同步。接口功能：服务人员信息到一键通。接口协议：HTTP。表A.5  服务人员信息同步接口输入参数6接口名/base/person/v1/tagSync请求方式PostJSON格式请求体"data":"", /使用3倍长密钥DES加密,"timestamp": "" /请求时间戳时间戳位13位时间戳 例如 1663212611677“sign”:“”/签名业务参数(加密前的data)类型说明是否必须（Y/N）idCardString身份证YtargerString标签,多个标签用英文逗号分隔YnameString姓名YidCardString身份证号YsexString性别：0、女      1、男YageInt年龄YphoneString手机号YstatusString人员状态：1、在职        2、离职YcreateTimeDate创建日期YcreateUserString创建人YupdateTimeDate更新日期YupdateUserString更新人YservicePersonUuidString运营商或者第三方服务人员uuidY输出参数类型说明备注codeint1 表示成功msgString返回消息dataString返回信息响应示例结果"code": 1,"msg": "success","data": "新增: 100,更新:20, 异常数据:0"输出参数类型说明备注codeint1 表示成功msgString返回消息dataString返回信息响应结果示例T/SIOT 326-2022表A.6  服务人员信息同步接口返回参数A.4服务对象标签信息同步接口名称：服务对象标签信息同步。接口功能：服务对象标签信息到一键通。接口协议：HTTP。表A.7  服务对象标签信息同步接口输入参数表A.8  服务对象标签信息同步接口返回参数7接口名/base/person/v1/targetContactsSync请求方式PostJSON格式请求体"data":"", /使用3倍长密钥DES加密,"timestamp": "" /请求时间戳时间戳位13位时间戳 例如 1663212611677“sign”:“”/签名业务参数(加密前的data)类型说明是否必须（Y/N）idCardString服务对象身份证YcontactsNameString紧急联系人姓名YcontactsPhonestring紧急联系人手机号YcontactsRelationstring紧急联系人1关系：1 、丈夫2、妻子3、志愿者4、儿子/干儿子5、女儿/干女儿6、居委干部7、媳妇8、孙子9、女婿10、哥哥/弟弟11、姐姐/妹妹12、母亲13、父亲14、侄子/外甥15、侄媳16、邻居17、侄女/外甥女18、亲戚19、侄女婿20、亲家公21、朋友22、同事23、退管会24、社区专职社工25、学校退管专职干部26、钟点工27、师弟YT/SIOT 326-2022"code": 1,"msg": "success","data": "新增: 100,更新:20, 异常数据:0"A.5紧急联系人信息同步接口名称：紧急联系人信息同步。接口功能：紧急联系人信息到一键通。接口协议：HTTP。表A.9  紧急联系人信息同步接口输入参数8接口名/base/signUp/v1/sync请求方式PostJSON格式请求体"data":"", /使用3倍长密钥DES加密,"timestamp": "" /请求时间戳时间戳位13位时间戳 例如 1663212611677“sign”:“”/签名业务参数(加密前的data)类型说明是否必须（Y/N）idCardString服务对象身份证YdeviceNoString设备编号YstartTimeString签约开始时间 yyyy-MM-ddYendTimeString签约结束时间    yyyy-MM-ddYstatusString签约状态:0失效,1正常YcreateTimeDate创建日期YcreateUserString创建人YupdateTimeDate更新日期YupdateUserString更新人Y28、师妹29、师兄师姐30、孙女31、监护人32、助残员33、长护险联系人34、其他类别levelsint联系人优先级YcreateTimeDate创建日期YcreateUserString创建人YupdateTimeDate更新日期YupdateUserString更新人Y输出参数类型说明备注codeint1 表示成功msgString返回消息dataString返回信息响应结果示例"code": 1,"msg": "success","data": "新增: 100,更新:20, 异常数据:0"T/SIOT 326-2022表A.10  紧急联系人信息同步接口返回参数A.6服务对象签约信息同步接口名称：服务人员信息同步。接口功能：服务人员信息到一键通平台。接口协议：HTTP。表A.11  服务对象签约信息同步接口输入参数9接口名/base/evaluateOrder/v1/sync请求方式PostJSON格式请求体"data":"", /使用3倍长密钥DES加密,"timestamp": "" ,/请求时间戳时间戳位13位时间戳 例如 1663212611677“sign”:“”/签名业务参数(加密前的data)类型说明是否必须（Y/N）scopeString服务评价结果：1、非常满意2、满意        3、基本满意        4、不满意5、非常不满意YremarkString备注NreviewTimeDate评价时间yyyy-MM-dd HH:mm:ssYserviceOrderUuidString运营商或者第三方的工单编号YcreateTimeDate工单创建日期 yyyy-MM-dd HH:mm:ssYcreateUserString工单创建人YupdateTimeDate工单更新日期YupdateUserString工单更新人Y输出参数类型说明备注codeint1 表示成功msgString返回消息dataString返回信息响应结果示例"code": 1,"msg": "success","data": "新增: 100,更新:20, 异常数据:0"输出参数类型说明备注codeint1 表示成功msgString返回消息dataString返回信息响应结果示例"code": 1,表A.13  工单服务评价信息同步接口输入参数表A.14  工单服务评价信息同步接口返回参数10T/SIOT 326-2022表A.12  服务对象签约信息同步接口返回参数A.7工单服务评价信息同步接口名称：服务人员信息同步。接口功能：服务人员信息到一键通。接口协议：HTTP。接口名/base/order/v1/update请求方式PostJSON格式请求体"data":"", /使用3倍长密钥DES加密,"timestamp": "" /请求时间戳时间戳位13位时间戳 例如 1663212611677“sign”:“”/签名业务参数(加密前的data)类型说明是否必须（Y/N）serviceNo运营商或者第三方工单编号uuidYstatus工单状态：0、进行中      1、完成YcreateTimeDate工单创建日期YcreateUserString工单创建人YupdateTimeDate工单更新日期YupdateUserString工单更新人Y输出参数类型说明备注codeint1 表示成功msgString返回消息dataString返回信息响应结果示例"code": 1,"msg": "success","data": "新增: 100,更新:20, 异常数据:0"T/SIOT 326-2022"msg": "success","data": "新增: 100,更新:20, 异常数据:0"A.8工单状态同步接口名称：工单状态信息同步。接口功能：工单状态信息到一键通。接口协议：HTTP。表A.15  工单状态同步接口输入参数表A.16  工单状态同步接口返回参数A.9区服务统计接口接口名称：区服务统计。接口功能：区服务统计接口。接口协议：HTTP。表A.17 区服务统计接口输入参数接口名/base/order/v1/update11输出参数类型说明备注codeint1 表示成功msgString返回消息dataList返回信息data.typeString类型1:服务对象;2:服务人员;3:一键通设备;4:叫车服务;5咨询服务;6:救援服务data.numString数量响应结果示例"code": 1,"msg": "success","data":"type":”1”,"num": “22”请求方式GetJSON格式请求体"data":"", /使用3倍长密钥DES加密,"timestamp": "" /请求时间戳时间戳位13位时间戳 例如 1663212611677“sign”:“”/签名业务参数(加密前的data)类型说明是否必须（Y/N）startTime开始时间（yyyy-mm）NentTime结束时间（yyyy-mm）N接口名order/car/v1/createCarOrder请求方式POSTJSON格式请求体"data":"", /使用DES加密,"timestamp": "" /请求时间戳时间戳位13位时间戳 例如 1663212611677“sign”:“”/签名T/SIOT 326-2022表A.18  区服务统计接口返回参数A.10一键通叫车接口接口名称：一键通叫车。接口功能：一键通叫车接口。接口协议：HTTP。表A.19  一键通叫车接口输入参数12输出参数类型说明备注codeint1 表示成功messageString返回消息data