注意事项
1. 请求方式: HTTP + JSON + POST / GET
2. 字段名均为小写
3. 统一使用UTF-8编码
4. 春雨测试服务地址 https://test.chunyutianxia.com/,正式服务地址 https://www.chunyuyisheng.com/
5. 第三方用户可以使用管理后台进行自测,该管理账户请联系相关春雨人员开通
6. 春雨所有环境的机房出口IP,如需增加到白名单,请使用:
7. 合作方需按照跟春雨商定的合作方式来开发,不能接入未合作的问诊方式
8. 关于医生总结:API渠道图文问题关闭后,医生仍可以发送总结消息(以医生文字回复形式)来通知患者(关闭后患者不可复),如存在医生在问题关闭后发总结情况,请确保可以接收到春雨推送信息并及时通知患者;
9. 相关服务开通权限后方可使用
签名校验机制
双方进行通信时,使用加密密钥(partner_key)进行安全校验, 签名密钥值用sign标识,需严格保密。
签名生成规则按使用场景分为两类:
非回调类型生成方式示例如下:
# PYTHON 版本 生成方法 import hashlib # 合作方 partner_key,注意不是 partner partner_key = 'XKBP1Oqut0r2LiGV' # UNIX TIMESTAMP 最小单位为秒 atime = '1467098815' # 第三方用户唯一标识,可以为字母与数字组合的字符串 user_id = 'A800130' # 获得签名: md5的32位结果取中间16位 sign = hashlib.md5(partner_key + atime + user_id).hexdigest()[8:-8] # 输出sign:5afda19c5d65a7a7 print sign
// PHP 版本 生成方法 // 合作方 partner_key, 注意不是 partner $partner_key = "XKBP1Oqut0r2LiGV"; // UNIX TIMESTAMP 最小单位为秒 $atime = "1467098815"; // 第三方用户唯一标识,可以为字母与数字组合的字符串。 $user_id = "A800130"; // 生成签名 5afda19c5d65a7a7 $sign = substr(md5($partner_key.$atime.$user_id), 8, 16); // 输出sign:5afda19c5d65a7a7 echo "sign: ".$sign;
// JAVA 版本 生成方法 import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import org.apache.commons.codec.binary.Hex; public class SignTest { // 计算 Sign private static String getSign(String partner_key, String atime, String user_id) throws NoSuchAlgorithmException{ String info = partner_key + atime + user_id; MessageDigest md5 = MessageDigest.getInstance("MD5"); byte[] srcBytes = info.getBytes(); md5.update(srcBytes); byte[] resultBytes = md5.digest(); String resultString = new String(new Hex().encode(resultBytes)); return resultString.substring(8, 24); } public static void main( final String[] args ){ try { // 合作方 partner_key, 注意不是 partner String partner_key = "XKBP1Oqut0r2LiGV"; // UNIX TIMESTAMP 最小单位为秒 String atime = "1467098815"; // 第三方用户唯一标识,可以为字母与数字组合的字符串。 String user_id = "A800130"; // 计算sign结果为: 5afda19c5d65a7a7 String sign = SignTest.getSign(partner_key, atime, user_id); System.out.println(sign); } catch (Exception ex) { ex.printStackTrace(); } } }
// C# 版本 生成方法 using System; using System.Security.Cryptography; using System.Text; public class Test { public static void Main() { // C#版本生成方法 string partner_key = "XKBP1Oqut0r2LiGV"; // UNIX TIMESTAMP 最小单位为秒 string atime = "1467098815"; // 第三方用户唯一标识,可以为字母与数字组合的字符串 string user_id = "A800130"; // 获得签名: md5的32位结果取中间16位 MD5 md5 = new MD5CryptoServiceProvider(); byte[] output = md5.ComputeHash(Encoding.UTF8.GetBytes(partner_key+atime+user_id)); string sign = BitConverter.ToString(output).Replace("-","").Substring(8, 16).ToLower(); // 输出sign:5afda19c5d65a7a7 Console.WriteLine(sign); } }
提问数据结构
JSONArray集合,格式: [contentItem 1, contentItem 2,..., contentItem n]
contentItem含义:
文字内容
图片内容
音频内容
视频内容
病人资料
生成content代码示例如下:
说明:
# PYTHON 版本 生成方法 import json # 创建对话内容 content = [ {"type": "text","text": "这是一段文本形式的内容"}, {"type": "image","file": "这是图片形式的内容,这里是图片的 url'"}, {"type": "audio","file": "这是语音形式的内容,这里是音频文件的 url"}, {"type": "video","file": "这是视频形式的内容,这里是视频文件的 url","duration": 10,"partner_cover_image": "视频封面图url"}, {"type": "patient_meta","age": "15岁","sex": "男","name": "张三"} ] # 获得json string 格式结果,接口中content字段使用该结果 content = json.dumps(content)
// 创建对话内容 import json // 创建对话内容 $content_list = array( array ('type'=>'text','text'=>'这是一段文本形式的内容'), array ('type'=>'image','file'=>'这是图片形式的内容,这里是图片的 url'), array ('type'=>'audio','file'=>'这是语音形式的内容,这里是音频文件的 url'), array ('type'=>'video','file'=>'这是视频形式的内容,这里是视频文件的 url','duration':10'), array ('type'=>'patient_meta','age'=>'15 岁', 'sex'=>'男'), ); // 获得json string 格式结果,接口中content字段使用该结果 echo json_encode($content_list);
// JAVA 版本 生成方法 import java.text.ParseException; import java.util.ArrayList; import java.util.HashMap; import java.util.Map; import net.sf.json.JSONArray; import net.sf.json.JSONException; public class JsonTest { public static void main(String[] args) throws JSONException, ParseException { ArrayList content_list = new ArrayList(); // 添加文本内容 Map c_text = new HashMap(); c_text.put("type", "text"); c_text.put("text", "这是一段文本形式的内容"); content_list.add(c_text); // 添加图片内容 Map c_image = new HashMap(); c_image.put("type", "image"); c_image.put("file", "这是图片形式的内容,这里是图片的 url"); content_list.add(c_image); // 添加音频内容 Map c_audio = new HashMap(); c_audio.put("type", "audio"); c_audio.put("file", "这是一段文本形式的内容,这里是音频文件的 url"); content_list.add(c_audio); // 添加视频内容 Map c_video = new HashMap(); c_video.put("type", "video"); c_video.put("file", "这是视频形式的内容,这里是视频文件的 url','duration':10'"); content_list.add(c_video); // 添加患者信息 Map c_patient_meta = new HashMap(); c_patient_meta.put("type", "patient_meta"); c_patient_meta.put("age", "15 岁"); c_patient_meta.put("sex", "男"); content_list.add(c_patient_meta); // 输出结果 JSONArray content_json = JSONArray.fromObject(content_list); String content = content_json.toString(); System.out.println(content); } }
科室划分
Postman调试工具
Postman接口测试套件使用说明
使用此工具,可以在开发未完成状态下,验证接口服务状态和业务的接入流程,同时在开发过程中,如果遇到问题,报错等,可以快速帮助定位问题。只需要考虑业务参数,而不需要关注签名,时间戳等。
注意:虽然可配置线上的请求,但请慎重使用,如随意测试线上接口可能会导致用户id被拉黑,多扣费等情况。
使用和配置
1.下载Postman > 7.0版本
2.下载Postman_config.zip并解压
3.Import->Folder 选择文件夹导入
在环境变量配置(1)->全局配置(2)中修改partner
在环境变量配置中的test(3)、online(4)中配置测试环境、线上环境的partner_key和当前环境的测试用户。
注意:线上测试必须添加user_id至白名单
在选择好测试环境后,选择需要测试的接口进行请求即可,测试过程中只需要修改业务参数如partner_order_id,problem_id等。不需要再关注签名、时间戳等验证字段
业务问题
1、问题交互次数定义
答:患者连续追问直至医生回答定义为一次交互。示意图(以下三种情况均定义为一次交互):
2、服务自动关闭逻辑?
图文问题医生首次答复后会重新计算时间,后续答复则不再重新计算。
3、健康档案需要提供哪些字段信息?
答:API对接方式下,健康档案包括:性别、年龄。具体可参考 开发前必读->提问数据结构
4、春雨平台侧能否提供科室信息?
答:目前春雨平台侧可以提供一级/二级科室信息,科室列表信息请参见:API接口->定向图文服务->找医生接口。
5、H5和API的对接方式下,收款流程都是什么样的?
答:如以H5形式对接,春雨直接收费。如以API形式对接,用户直接支付给合作方,合作方再和春雨平台定期结算。
6、API接入众包服务:用户提交问题后,用户对系统分配到的科室可以修改吗?
答:不可以修改。
7、允许用户进行评价的触发条件是什么?
答:医患交互后即可评价医生。
8、针对医生评价功能,不满意的原因是必填项么?
答:必填。
9、针对举报功能:被医生或系统举报的功能,有专门的接口么?用户被举报后,如何通知到合作方?
答:被医生或系统举报,无专门的接口通知。会通过【通用接口】的【问题关闭通知】发close或refund通知。春雨会返回对应的被举报文案,请参见【退款及举报逻辑】部分。同时被举报后会以特殊的问题状态进行标识,参见【问题详情接口】。
10、针对黑名单功能:当用户被列入黑名单时,用户再提问时,会如何提示?
答:用户被加入黑名单后,当该用户提问时,春雨平台会返回错误码12003来进行标识。具体请参见【黑名单逻辑】和【错误码】中的对应内容。
技术问题
1、为何在安卓客户端的webview中点击上传图片控件没反应?
答: 由于安全因素android webview屏蔽了文件上传控件,具体参考: https://www.oschina.net/question/23880_50205 安卓5.0及以上版本中,有修改,具体参考: http://blog.csdn.net/u012912435/article/details/51484211 在在Android5.0及以上版本中使用WebView加载https资源文件时, 如果认证证书不被Android认可,那么会出现无法成功加载对应资源问题。 具体解决参考: https://www.cnblogs.com/zhengshiqiang47/p/6220295.html
2、为何在H5页面点击创建问题无效?
答: H5页面不能在PC浏览器环境下直接使用,需要在手机或手机模拟器环境下使用。
3、为何在加载H5页面时候样式丢失?
答: H5页面所有资源URL为相对URL,请确认当前加载环境是否支持获取该资源。
4、什么是atime?
答: atime 为时间戳,是指格林威治时间1970年01月01日00时00分00秒(北京时间1970年01月01日08时00分00秒)起至现在的总秒数;atime需实时获取,前后15min有效。
5、为何在回调通知里面查不到相关参数?
答: 春雨发送第三方回调通知时采用POST方式,data为json格式,请确保接口符合要求。如果仍然未获取到相关参数,建议增加request请求内容的完整打印消息来排查原因。
6、每次API接口 创建/追问 问题前都需要先请求账号同步接口吗?
答: 不需要,新用户只要同步过一次即可。
7、H5不能直接返回到上级页面吗?
答: 由于H5是嵌入第三方APP的,所以返回栏需要由第三方来实现。
8、API付费款项是怎样处理的?
答: 第三方需要先在春雨服务器创建付费问诊记录,然后引导用户付费至第三方平台,成功后通知春雨服务器更新订单,后续问诊交互同API免费问诊一致。春雨公司定期与第三方公司结算相关款项。
9、接口返回"invalid_user"是为什么?
答: 首先 user_id 只可以包含大小写字母与数字、下划线的组合,其次在确认 user_id 符合格式时请检查是否是由于构建的数据类型(content或者assess_info)格式错误,导致参数乱码(可通过抓包的方式确认发出的数据是否正确)。
10、H5接入方式下,针对Android系统,填写病情描述后不能点击下一步的解决办法?
答: 参考如下代码进行解决 webSettings.setJavaScriptEnabled(true); webSettings.setDomStorageEnabled(true); // 前面俩个必须同时在 webView.setWebChromeClient(new MyWebChromeClient()); webSettings.setAllowFileAccess(true)
11、API对接众包升级服务:可以使用哪些接口?。
答:请查看【开发文档】中,【众包升级服务】目录下的所有接口,【通用接口】下的所有接口,和【第三方回调管理】的所有接口。