体检

腾讯体检接口方案

修订历史

日期	作者	版本	备注
2018-12-29	曾志明	V0.1	初始版本
2019-01-02	曾志明	V0.2	1.package/list，细化reportTypes2.package/detail，增加reportTypes3.order/list，增加statusName4.order/detail，增加cardTypeName, marriageStatusName, sexName
2019-01-11	曾志明	V0.3	1.order/list删除了status，统一用code及codeName，枚举补充在附录2.order/detail，orderInfo增加createTime及expireTime；删除了timePass字段；code及codeName含义补充在附录4.1.7
2019-01-15	曾志明	V0.4	/order/detail接口的patientInfo增加birthday字段
2019-01-22	曾志明	V0.5	1.修正/package/list接口返回，orgInfo与packageList为平级结构2.修正/package/detail接口，返回增加data
2019-01-22	曾志明	V0.6	1./package/list增加createTime，salesVolume, tags字段2.增加/package/tag套餐标签接口3./order/list增加3个字段：createTime, countDown, orderPrice
2019-02-25	lyndonlin	V0.7	增加获取机构列表接口/org/list
2019-03-07	lyndonlin	V0.8	套餐详情接口新增tag字段
2019-03-11	ligangtang	v0.9	1. /package/schedule接口增加返回时段2. 增加医院标签tag列表接口/org/tag
2019-03-12	ligangtang	v1.0	1、order/apply添加订单套餐时段 2、/order/detail 返回订单套餐时段
2019-04-08	chadwang	V1.1	1、/order/list 增加优惠信息2、/order/detail 增加优惠信息3、/order/apply 增加优惠信息以上接口中orderPrice字段语义变更为：实际支付金额 4、/order/conirm fee字段语义变更为：实际支付金额

• 体检
  • 腾讯体检接口方案
  • 1 接入须知
  • 2 合作方提供的接口
    • 2.1 查询套餐列表 /package/list
    • 2.2 查询套餐详情 /package/detail
    • 2.3 查询套餐排期 /package/schedule
    • 2.4 创建订单 /order/apply
    • 2.5 结算订单 /order/confirm
    • 2.6 取消订单 /order/cancel
    • 2.7 查询订单列表 /order/list
    • 2.8 查询订单详情 /order/detail
    • 2.9 查询报告详情 /report/detail
    • 2.10 查询套餐标签 /package/tag
    • 2.11 查询机构列表 /org/list
    • 2.12 查询医院标签 /org/tag
  • 3 腾讯提供的接口
    • 3.1 退款接口 refund
    • 3.2 报告通知接口 report
  • 4 附录
    • 4.1 错误码和枚举
      • 4.1.1 错误码 code、message
      • 4.1.2 报告领取方式 ReportType
      • 4.1.3 体检机构类型 OrgType
      • 4.1.4 婚姻状态 MarriageStatus
      • 4.1.5 证件类型 CardType
      • 4.1.6 性别 Sex
      • 4.1.7 体检状态 Code、CodeName

1 接入须知

1. 传输协议：HTTPS

2. 数据格式：JSON

3. 请求方法：POST或GET

4. POST报文示例： Headers :

   Content-Type: application/json

   god-portal-signature: a3f0f977e7141bd57ceca62b0edb7605a1599735911692afa8747967a8e59a44

   god-portal-timestamp: 1498553651000

   god-portal-request-id: 9b501e56-8026-4d7d-96cc-4594742acd71

   Body :（具体参照各个接口的定义）

   {
   ......
   }
   备注：GET报文Headers一样，只是没有Body，参数放在URL。

5. 请求头报文参数：

   参数名	类型	必填	备注
   god-portal-signature	string	是	签名，参见签名算法
   god-portal-timestamp	string	是	当前生成的时间戳,毫秒数
   god-portal-request-id	string	是	用来双方查询日志,建议使用一个uuid

6. 签名算法：

   变量	说明
   partnerId	合作方ID,由腾讯分配
   timestamp	当前生成的时间戳,毫秒数,等于header的god-portal-timestamp
   partnerSecret	合作方密钥,由腾讯分配

   god-portal-signature = hmac_sha256(partnerSecret, partnerId + timestamp)

   备注：partnerId + timestamp的含义为字符串拼接。

7. 密钥及签名示例：

   以另一独立文档提供

2 合作方提供的接口

查询类接口为GET请求；变更类接口为POST请求。

2.1 查询套餐列表 /package/list

接口含义：根据机构ID查询套餐列表及机构详情。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

?orgId=xxx

请求参数：

字段	名称	类型	必填	备注
orgId	机构ID	string	是

响应示例：

{ "code": 0, "message": "成功", "data": { "orgInfo": { "orgId": "机构ID", "orgName": "机构名称", "orgAddress": "机构地址", "orgPicture": "http://机构图片", "orgLevel": { "id": 3, "name": "公立医院" }, "reportTypes": [ { "id": 1, "name": "电子报告" }, { "id": 2, "name": "门店自取" }, { "id": 3, "name": "邮寄到家" } ] }, "packageList": [ { "packageId": "183126", "packageName": "套餐名称", "packagePrice": 235800, "description": "套餐描述", "smallPicture": "http://套餐小图", "createTime": "创建时间，格式如：2019-01-01 23:59:59", "salesVolume": 888, "tags": { "tagGender": [{"text": "男", "code": "101"}], "tagGroup": [{"text": "应酬族", "code": "201"}, {"text": "久坐办公族", "code": "202"}], "tagItem": [{"text": "眼科", "code": "301"}, {"text": "糖尿病", "code": "302"}] } } ] }}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	object	否
reportTypes	报告类型	array	否	参考4.1.2 报告领取方式 ReportType
createTime	套餐创建时间	string	否	格式如：2019-01-01 23:59:59
salesVolume	套餐销售量	string	否	会用于套餐排序
tags	标签	object	否	参考/package/tag接口

2.2 查询套餐详情 /package/detail

接口含义：根据套餐ID查询套餐详情。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

?packageId=xxx&orgId=xxx

请求参数：

字段	名称	类型	必填	备注
packageId	套餐ID	string	是
orgId	机构ID	string	否

响应示例：

{ "code": 0, "message": "成功", "data": { "packageInfo": { "packageId": "183126", "packageName": "体检套餐(男士)", "packagePrice": 58440, "description": "套餐描述", "bigPicture": "http://套餐大图", "tags": { "tagGender": [{"text": "男", "code": "101"}], "tagGroup": [{"text": "应酬族", "code": "201"}, {"text": "久坐办公 族", "code": "202"}], "tagItem": [{"text": "眼科", "code": "301"}, {"text": "糖尿病", "code": "302"}] }, }, "orgInfo": { "orgId": "机构ID", "orgName": "机构名称", "orgAddress": "机构地址", "orgPhone": "机构电话", "reportTypes": [ { "id": 1, "name": "电子报告" }, { "id": 2, "name": "门店自取" }, { "id": 3, "name": "邮寄到家" } ] }, "items": [ { "label": "基础检查", "data": [ { "itemName": "眼科常规", "itemDesc": "眼科常规检查", "sort": 1 }, { "itemName": "耳鼻喉科", "itemDesc": "检查有无中耳炎、鼻炎、慢性扁桃体炎、鼻中隔偏曲、咽炎等疾病。", "sort": 2 } ] } ] }}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	object	否
reportTypes	报告类型	array	否	参考4.1.2 报告领取方式 ReportType

2.3 查询套餐排期 /package/schedule

接口含义：根据套餐ID查询套餐排期。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

?packageId=xxx&orgId=xxx

请求参数：

字段	名称	类型	必填	备注
packageId	套餐ID	string	是
orgId	机构ID	string	否

响应示例：

{ "code": 0, "message": "成功", "data": [ { "date": "2019-01-03", "leftNum": "45", "period": [{"time":"8:00-8:30","left":"10"}] }, { "date": "2019-01-04", "leftNum": "50", "period": [{"time":"8:00-8:30","left":"10"}] } ]}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	array	否	如果有时段带上period字段

2.4 创建订单 /order/apply

接口含义：创建体检订单，此时为未支付状态。

    此为POST请求。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

{ "userId": "openId", "bookingName": "预约人", "bookingPhone": "13800138000", "orgId": "420", "orgName": "体检机构", "packageId": "62707", "packageName": "体检套餐", "medicalTime": "2019-03-01", "name": "体检人", "cardType": 1, "cardId": "身份证号码", "sex": 1, "birthday": "1992-03-16", "age": 20, "marriageStatus": 2, "reportType": 2, "phone": "13800138000", "reportReceiver": "可选：邮件纸质报告收件人", "reportAddress": "可选：邮件纸质报告地址", "time":"8:00-8:30","usedCoupon": 1,"couponFee":10,"couponInfo":[{id: "a123",type: "discount",fee:10}]}

PS:1、设计上要支持使用多张优惠券；

2、couponFee = 优惠信息中，所有fee的总和

请求参数：

字段	名称	类型	必填	备注
usedCoupon	是否使用优惠券	int	是	1:使用优惠券 0:不使用优惠
couponFee	优惠总金额	int	否	usedCoupon为1时，总是有值
couponInfo	优惠信息	Json数组	否	usedCoupon为1时，总是有值id:优惠券idtype:优惠券类型, 折扣优惠券: discount, 满减优惠券:fullReduction等fee:折扣金额

响应示例：

{ "code": 0, "message": "成功", "data": { "orderId": "订单ID","orderPrice": 2001, //订单实际支付金额 "orderCountPrice": 2001, "receiptNo": "收据号" }}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	object	否
orderId	订单ID	string	否
orderPrice	订单实际支付价格	int	否	分
orderCountPrice	订单总价格	int	是	分
receiptNo	收据号	string	否	若系统没有这一项，则跟orderId一致

PS：1、当使用优惠券时，实际支付金额orderPrice = orderCountPrice订单总金额 - couponFee优惠金额

2、不使用优惠券时orderCountPrice 总金额 和orderPrice 实际支付金额，值一样的

2.5 结算订单 /order/confirm

接口含义：进行订单结算，将订单状态变更为已支付。

    此为POST请求。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

{ "userId": "openId", "orderId": "订单ID", "payId": "微信支付交易流水号", "receiptNo": "100218121917314171199", "fee": 2001, //实际支付金额"usedCoupon": 1, "orderCountPrice":2002, "couponFee":1, "couponInfo":同/order/apply }

请求参数：

字段	名称	类型	必填	备注
userId	用户ID	string	是	openId
orderId	订单ID	string	是
payId	支付流水号	string	是
receiptNo	单据号	string	是
fee	实际支付金额	int	是	分
usedCoupon	是否使用优惠券	int	是
orderCountPrice	订单总价格	int	否
couponFee	优惠金额	int	否
couponInfo	优惠码	Json数组	否

响应示例：

{ "code": 0,"message": "成功"}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是

2.6 取消订单 /order/cancel

接口含义：进行订单取消，不管此时订单为已支付或者未支付。若订单为已支付，需要调用腾讯侧退款接口。

    此为POST请求。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

{ "userId": "openId", "orderId": "订单Id"}

请求参数：

字段	名称	类型	必填	备注
userId	用户ID	string	是
orderId	订单ID	string	是

响应示例：

{ "code": 0,"message": "成功"}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是

2.7 查询订单列表 /order/list

接口含义：查询订单列表。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

?userId=xxx

请求参数：

字段	名称	类型	必填	备注
userId	用户ID	string	是

响应示例：

{ "code": 0, "message": "成功", "data": [ { "orderId": "177903", "packageId": "64633", "packageName": "套餐名称", "packagePrice": 2001, "smallPicture": "http://套餐小图", "orgId": "机构ID", "orgName": "机构名称", "medicalTime": "2019-01-31", "examName": "体检人", "code": 2, "codeName": "待支付", "createTime": "2019-01-31 23:59:59", "countDown": 3600, "orderPrice": 2001, //实际支付金额 "usedCoupon": 1, "couponFee":10, "orderCountPrice":2010, "couponInfo":[{id: "a123",type: "discount",fee:10}] } ]}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	object	否
code	状态码	int	否	参考4.1.7 code 状态码
createTime	订单创建时间	string	否	格式如：2019-01-31 23:59:59
countDown	未支付订单失效倒计时	int	否	比如1小时会失效，则countDown从3600开始递减到0
orderPrice	订单实际支付金额	int	否	单位：分。有可能跟packagePrice 不一样。
usedCoupon	是否使用优惠券	int	是	0：不使用1：已使用
orderCountPrice	订单总金额	int	是	单位：分
couponFee	优惠总金额	int	否	单位：分
couponInfo	优惠信息描述	Json数组	否	id:优惠券idtype:优惠券类型,折扣优惠券: discount, 满减优惠券:fullReduction等fee:折扣金额

2.8 查询订单详情 /order/detail

接口含义：查询订单详情。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

?userId=xxx&orderId=xxx

请求参数：

字段	名称	类型	必填	备注
userId	用户ID	string	是
orderId	订单ID	string	是

响应示例：

{ "code": 0, "message": "成功", "data": { "orderInfo": { "orderId": "299197", "orderPrice": 58440,"usedCoupon": 1,"couponFee":10,"orderCountPrice":2010,"couponInfo":[{id: "a123",type: "discount",fee:10}] "packageId": "套餐ID", "packageName": "套餐名称", "orgId": "机构ID", "orgName": "机构名称", "orgAddress": "机构地址", "medicalTime": "2019年03月01日 星期五", "code": 10, "codeName": "待支付", "createTime": "2019-01-01 22:59:59", "expireTime": "2019-01-01 23:59:59", "time":"8:00-8:30" }, "patientInfo": { "name": "体检人", "cardType": 1, "cardTypeName": "证件类型名称，比如：身份证", "cardId": "证件号", "age": 26, "marriageStatus": 2, "marriageStatusName": "婚姻状态名称", "sex": 1, "sexName": "性别名称", "birthday": "1992-03-16", "phone": "18566760316" }, "reportInfo": { "reportType": 2, "reportTypeName": "纸质报告(门店自取)", "reportReceiver": "可选：报告收件人", "reportAddress": "可选：报告地址", "reportState": "待邮寄"}, "countDown": 3590 }}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	object	否
code	状态码	int	否	参考4.1.7 code 状态码
createTime	订单创建时间	string	否	格式如2019-01-01 22:59:59
expireTime	未支付订单失效时间	string	否	格式如2019-01-01 23:59:59
countDown	未支付订单失效倒计时	int	否	比如1小时会失效，则countDown从3600开始递减到0

2.9 查询报告详情 /report/detail

接口含义：查询报告详情。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

?userId=xxx&orderId=xxx

请求参数：

字段	名称	类型	必填	备注
userId	用户ID	string	是
orderId	订单ID	string	是

响应示例：

{ "code": 0, "message": "暂无报告", "data": "base64"}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	string	否	base64

2.10 查询套餐标签 /package/tag

接口含义：查询某机构下的筛选标签列表，包括性别、人群、项目等。该接口的返回，应与/package/list接口返回的tags字段相对应。

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

?orgId=xxx

请求参数：

字段	名称	类型	必填	备注
orgId	机构ID	string	是

响应示例：

{ "code": 0, "message": "成功", "data": [ { "text": "性别", "code": "tagGender", "options": [ { "text": "男", "code": "101" }, { "text": "女未婚", "code": "102" }, { "text": "女已婚", "code": "103" } ] }, { "text": "人群", "code": "tagGroup", "options": [ { "text": "老年", "code": "201" }, { "text": "应酬族", "code": "202" }, { "text": "久坐办公族", "code": "203" } ] }, { "text": "项目", "code": "tagItem", "options": [ { "text": "基因检测", "code": "301" }, { "text": "眼科", "code": "302" }, { "text": "糖尿病", "code": "303" } ] } ]}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	object	否

2.11 查询机构列表 /org/list

接口含义：查询合作伙伴在指定城市支持的所有机构的列表

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

?cityId=440300

请求参数：

字段	名称	类型	必填	备注
cityId	行政区划代码，例如深圳440300	string	是

响应示例：

{ "code": 0, "message": "成功", "data": [ { "id": "123456", "name": "深圳市南山医院", "addr": "地址", }, { "id": "287894", "name": "北大医院", "addr": "地址", }, ]}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	object	否

2.12 查询医院标签 /org/tag

接口含义：查询合作伙伴在指定城市支持的医院标签列表

测试环境URL：请合作方提供

正式环境URL：请合作方提供

请求示例：

?cityId=440300

请求参数：

字段	名称	类型	必填	备注
cityId	行政区划代码，例如深圳440300	string	是

响应示例：

{ "code": 0, "message": "成功", "data": [ { "id": "123456", "name": "深圳市南山医院", "tag": ["settag001", "settag002", "settag003", "settag004", "settag005", "settag006"], }, { "id": "287894", "name": "北大医院", "tag": ["settag001", "settag002", "settag003", "settag004"], }, ]}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	请合作方提供错误码枚举
message	返回信息	string	是
data	返回对象	object	否	tag为套餐体检类型列表，目前定义有settag001:"入职体检"、 settag002:"青年女性"、settag003:"青年男性"、settag004:"父母体检"、settag005:"白领体检"、settag006:"婚检孕检"6种类型

3 腾讯提供的接口

退款接口及报告通知接口皆为POST请求。

3.1 退款接口 refund

接口含义：合作方发起退款。

    此为POST请求。

发起退款的场景：

1. 用户在界面上点击取消订单，则腾讯侧会调用合作方的/order/cancel接口。若未订单未支付，则直接取消即是。若已经支付，则合作方有可能需要审核。审核成功后，合作方再调用腾讯侧refund接口。
2. 用户没有在界面上主动发起，而是由于某些原因，合作方需要退款，也可以调用该refund接口（退款须慎重）。

测试及正式URL：以另一独立文档提供

请求示例：

{ "userId": "用户ID", "orderId": "订单ID", "orgId": "机构ID", "packageId": "套餐ID", "refundNo": "退款内部流水号", "refundFee": "退款金额，单位分"}

请求参数：

字段	名称	类型	必填	备注
userId	用户ID	string	是
orderId	订单ID	string	是
orgId	机构ID	string	是
packageId	套餐ID	string	是
refundNo	退款内部流水号	string	是	可能有多次退款的场景
refundFee	退款金额	string	是	单位分

响应示例：

{ "code": 0, "message": ""}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	0为成功，非0为失败
message	返回信息	string	是

3.2 报告通知接口 report

接口含义：合作方电子报告生成时调用。

    此为POST请求。

测试及正式URL：以另一独立文档提供

请求示例：

{ "userId": "用户ID", "orderId": "订单ID"}

请求参数：

字段	名称	类型	必填	备注
userId	用户ID	string	是
orderId	订单ID	string	是

响应示例：

{ "code": 0, "message": ""}

响应参数：

字段	名称	类型	必填	备注
code	返回码	int	是	参考附录中错误码
message	返回信息	string	是

4 附录

4.1 错误码和枚举

4.1.1 错误码 code、message

值	说明
0	成功
非0	失败

4.1.2 报告领取方式 ReportType

值	说明
1	电子报告
2	门店自取
3	邮寄到家

4.1.3 体检机构类型 OrgType

值	说明
2	专业体检中心
3	公立医院
4	民营医院

4.1.4 婚姻状态 MarriageStatus

值	说明
0	未知
1	已婚
2	未婚
3	离异

4.1.5 证件类型 CardType

值	说明
1	身份证
2	护照
3	回乡证
4	台胞证
5	其他

4.1.6 性别 Sex

值	说明
1	男
2	女

4.1.7 体检状态 Code、CodeName

值	说明
10	订单取消
12	体检爽约
13	补检失败
14	支付超时
18	申请退款
19	已退款
2	待支付
31	已支付，待体检
32	待取报告
33	待评价
41	已完成