T/SIOT 326-2022 智慧健康养老 为老服务“一键通”系统接口要求

ICS35.240.80

CCSL67

团体标准

T/SIOT326-2022

智慧健康养老

为老服务“一键通”系统接口要求

Smarthealthandelderlycare

-Systeminterfacerequirementof"One-Press-Done"system

2022-12-16发布2022-12-30实施

上海市物联网行业协会发布

T/SIOT326-2022

目次

前言.................................................................................II

1范围...............................................................................1

2规范性引用文件.....................................................................1

3术语和定义.........................................................................1

4缩略语.............................................................................2

5接口总体要求.......................................................................2

5.1对接范围.......................................................................2

5.2接口要求.......................................................................2

5.2.1概述.......................................................................2

5.2.2协议.......................................................................2

5.2.3接口类型...................................................................2

5.2.4接口版本要求...............................................................2

5.2.5接口方式...................................................................3

5.2.6接口参数...................................................................3

5.2.7信息过滤...................................................................3

5.2.8返回参数...................................................................3

5.2.9其他要求...................................................................3

6接口接入要求.......................................................................4

6.1接口开发.......................................................................4

6.2存量数据处理...................................................................4

6.3接口确认.......................................................................4

6.4接口测试.......................................................................4

6.5接口服务注册...................................................................4

6.6接口上线.......................................................................4

6.7接口变更.......................................................................4

附录A（资料性）为老服务“一键通”数据平台通信报文消息实例...........................5

附录B（资料性）打车订单状态定义....................................................18

附录C（资料性）异常码参照表........................................................19

参考文献.............................................................................20

I

T/SIOT326-2022

前言

T/SIOT326《智慧健康养老为老服务“一键通”系统接口要求》是上海市物联网行业协会制定的

智慧健康养老为老服务“一键通”规范系列团体标准之一，本系列标准结构如下：

——T/SIOT325智慧健康养老为老服务“一键通”应用功能通用要求；

——T/SIOT326智慧健康养老为老服务“一键通”系统接口要求；

——T/SIOT327智慧健康养老为老服务“一键通”智能电视终端技术规范。

本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》给出的

规则起草。

请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。

本文件由上海市物联网行业协会提出并归口。

本文件起草单位：上海仪电数字技术股份有限公司、上海市物联网行业协会、上海璧拓信息技术有

限公司、卫宁健康科技集团股份有限公司、上海镭达晶元智能科技有限公司、上海天与智慧养老服务有

限公司、上海全程玖玖健康服务有限公司、上海子归智能技术有限公司、上海迈动医疗器械股份有限公

司、上海友康信息科技有限公司、上海安康通健康管理有限公司、上海市爱护网健康管理有限责任公司、

上海软富信息技术有限公司上、海恩谷信息科技有限公司、上海仁微电子科技股份有限公司。

本文件主要起草人：李伟、毛继曙、颉小龙、彭召旺、葛健、叶骥岗、卢煦乐、叶晓华、袁江枫、

丛力群、周红波、王鸷、胡书芳、李刚、徐一涵、杨华刚、李鹏、王洋、陈帮贯、黎祥、陈健、黎祥、

王智斌、欧阳树生。

本文件首期承诺执行单位：上海仪电数字技术股份有限公司、上海璧拓信息技术有限公司、上海全

程玖玖健康服务有限公司、上海天与智慧养老服务有限公司、上海市爱护网健康管理有限责任公司、上

海安康通健康管理有限公司。

II

T/SIOT326-2022

智慧健康养老为老服务“一键通”系统接口要求

1范围

本文件规定了为老服务“一键通”信息化平台对于上下级平台的系统接口要求。

本文件适用于为老服务“一键通”信息化平台的开发和实施，和为老服务“一键通”进行业务对接

的服务机构系统以及其他第三方为老服务子系统对接为老服务“一键通”信息化平台的开发依据。以及

第三方测评机构进行接口对接测试和验证的依据。

本文件的使用者包括为老服务行业信息化软件企业、独立软件测试机构、为老服务信息化产品的软

件开发组织、实施及咨询服务机构等。与为老服务信息化开发有关的其他领域亦可参考使用。

2规范性引用文件

下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，

仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本

文件。

GB/T18894电子文件归档与电子档案管理规范

GB/T25058息安全技术网络安全等级保护实施指南

GB/T28452息安全技术应用软件系统通用安全技术要求

GB/T35273信息安全技术个人信息安全规范

GB/T35279息安全技术云计算安全参考架构

3术语和定义

下列术语和定义适用于本文件。

3.1

智慧健康养老smarthealthandelderlycare

面向居家老年人、社区及养老机构的传感网系统与信息平台，并在此基础上提供实时、快捷、高效、

低成本的，物联化、互联化、智能化的养老服务。

[T/SIOT310-2020定义3.1]

3.2

数据服务dataservice

通过一定的技术手段，对外提供为老服务“一键通”相关信息资源。

3.3

应用程序接口applicationprogramminginterface

预先定义的接口（函数、HTTP接口），或指软件系统不同组成部分衔接的约定。

注：用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而有无需访问源码，或理解内部工作机

制的细节。通过程序调用接口，通常用于查询或核验信息。

3.4

基础服务系统basicservicesystem

通过对系统对接不同类别的数据进行存储、计算、挖掘分析的加工处理，生成具有语义和格式统一

的数据的系统。

3.5

为老服务“一键通”“One-Press-Done”foroldservice

1

T/SIOT326-2022

借助为老服务“一键通”信息化平台，并通过多终端（固话终端、电视终端、自助终端、移动终端

等）的多路径覆盖，为广大老年人提供紧急救援、助医、出行、政策、生活、家政、社交等高频急难服

务。

4缩略语

下列缩略语适用于本文件。

API：应用程序接口（ApplicationProgrammingInterface）

APP：程序（Application）

IP：网络互联协议（InternetProtocol）

JSON：JavaScript对象简谱（JavaScriptObjectNotation）

SOAP：简单对象访问协议（SimpleObjectAccessProtocol）

XML：可扩展标记语言（ExtensiableMarkupLanguage）

5接口总体要求

5.1对接范围

为老服务“一键通”信息化平台应对接：

a)上级平台；

b)第三方为老服务子系统，服务机构子系统以及其他独立为老服务子功能系统。

5.2接口要求

5.2.1概述

接口应能让资源提供方开放自己的资源访问权限来提供数据基础服务系统，又能确保数据安全性让

资源提供方继续握有控制权。资源提供方要根据业务情况描述接口功能，并且按照API规范进行开发接

口，能让数据服务使用者更好的使用应用程序接口，高效的对接为老服务“一键通”信息化平台，提供

更好的智慧健康养老服务。

5.2.2协议

为老服务“一键通”信息化平台的通信协议，宜采用HTTP超文本传输协议和HTTPS安全超文本传输协

议两种且可扩展，本协议在标准HTTP和HTTPS协议上做了扩展完成，形成了三层协议标准，如图1所示。

HTTPHeader

扩展协议头

Payload（Data）

图1三层协议

5.2.3接口类型

接口宜采用以下两种：

a)HTTPAPI接口：请求报文格式为Key-Value形式，返回报文为JSON串，可采用GET和POST方法；

b)WebService接口：报文通常走SOAP协议通过HTTP传输，请求报文和返回报文都是XML格式（助

医挂号目前采用此方式）。

5.2.4接口版本要求

2

T/SIOT326-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)响应参数：参数含义、参数类型、取值范围等；

3

T/SIOT326-2022

5)错误代码说明表；

6)其他：如算法生成说明，如Token规则等；

7)当接口发生变化时，应及时更新接口文档并提供给使用方。

6接口接入要求

6.1接口开发

服务提供方应根据接口需要开发相应的接口，并提供详细接口字段说明文档。

6.2存量数据处理

接口后台的数据应保证其实时性及全面性，并且数据有更新时应该保证接口的返回参数不发生变化，

或者向下兼容。

6.3接口确认

为老服务“一键通”信息化平台需确认各服务提供的接口应符合智慧健康养老为老服务“一键通”

应用功能通用要求（T/SIOT325-2022）。

6.4接口测试

确认接口符合要求后，服务提供方需要提供接口测试环境访问地址、接口参数等相关信息，由为老

服务“一键通”信息化平台进行对接并进行联调，测试接口是否可以正常使用。

6.5接口服务注册

为老服务“一键通”信息化平台将对服务提供方的接口在平台上进行接口注册。

6.6接口上线

为老服务“一键通”信息化平台对服务接口进行测试并且能够正常使用后，可将服务接口发布上线。

6.7接口变更

发生如下接口变更情况，需要通知为老服务“一键通”信息化平台，并进行重新接口对接和调试：

a)原始接口地址发生变化；

b)原始接口返回参数发生变化；

c)原始接口遇到如服务升级、网络异常导致接口不通，服务不可使用；

d)接口删除或者使用新的接口替代。

4

T/SIOT326-2022

A

A

附录A

（资料性）

为老服务“一键通”数据平台通信报文消息实例

A.1授权服务

接口名称：获取AccessToken。

接口功能：该接口提供后访问业务接口的授权token。

接口协议：HTTP。

表A.1获取接口输入参数

接口名http://IP:port/auth/v1/getAccessToken

请求方式PostJSON格式

输入参数类型说明是否必须（Y/N）

appIdString分配接入一键通的账号Y

sercetString分配接入一键通的sercetY

表A.2接口返回参数

输出参数类型说明备注

codeint200表示成功

messageString返回消息

accessTokenString授权访问token

expiryTimeStringToken的过期时间

接口响应示例

{

"code":200,

"expiryTime":"2022-09-0714:46:03",

"accessToken":"6AACC862E96A3542C9D2231DDAE95523"

}

A.2服务对象(老人)信息同步

接口名称：服务对象（老人）信息同步。

接口功能：服务对象(老人)信息到一键通。

接口协议：HTTP。

表A.3同步接口输入参数

接口名/base/person/v1/sync

请求方式PostJSON格式

{

"data":"",//使用3倍长密钥DES加密,

"timestamp":""//请求时间戳

请求体

时间戳位13位时间戳例如1663212611677

“sign”:“”//签名

}

业务参数(加密前的data)类型说明是否必须（Y/N）

nameString姓名Y

idCardString身份证号Y

5

T/SIOT326-2022

sexString性别：0、女1、男Y

ageInt年龄Y

phoneString手机号Y

censusProvinceString户籍省Y

censusAreaString户籍区Y

censusStreetString户籍街道Y

censusCommitteeString户籍居委Y

censusAddressString户籍详细地址Y

resideProvinceString居住省Y

resideCityString居住市Y

resideAreaString居住区Y

resideStreetString居住街道Y

resideCommitteeString居住居委Y

resideAddressString居住详细地址Y

标签信息：1、独居2、纯老

targerStringN

3、低保4、残疾

服务对象状态：0、死亡1、正常

statusStringY

2、迁出

gpsFinalTimeDate设备最后定位时间N

createTimeDate创建日期Y

createUserString创建人Y

updateTimeDate更新日期Y

updateUserString更新人Y

表A.4同步接口返回参数

输出参数类型说明备注

codeint1表示成功

msgString返回消息

dataString返回信息

{

"code":1,

"msg":"success",