# 丁香医生开放平台开发者文档

# 1. 概述

# 1. 阅读对象

本文档供接入合作方技术开发人员阅读，主要包含系统交互流程、详细接口文档等内容。

# 2. 接口使用场景

此文档上的所有接口仅供服务端之间调用，不能直接使用客户端直接调用丁香医生的开放接口(客户端调用存在接口密钥泄漏的风险)。

# 3. 接入方式

# 2. 系统交互流程

# 1. 用户授权流程

# 3. 接口规范说明

# 1. 接口交互方式

以 HTTPS(GET/POST)+JSON 方式进行数据交互，请求地址：https://ask.dxy.com/open/i/platform/${接口编号} 。 所有接口都只能在服务端之间调用，合作方不能通过客户端直接调用。

# 2. 参数类型及长度定义

# 3. 请求参数说明

当接口说明需要用户级鉴权时，需要设置请求头 ask-platform-sid:${userToken} ，获取userToken的方式见接口100010。

请求头User-Agent不建议使用工具包或者编程语言默认的值，如包含"Apache，HttpClient，Java，python"等关键字的User-Agent会被限流，可使用User-Agent: DXYS-Partner。

• GET请求：所有参数需要以URLEncode(UTF-8)格式发送(先签名再URL编码)，例如：key1=value1&key2=value2&key3=%E4%B8%AD%E6%96%87%E5%8F%82%E6%95%B0
• POST参数：request headers中的Content-Type设置为application/x-www-form-urlencoded;charset=utf-8 ,有文件上传时为 multipart/form-data 。

# 4. 签名方式

所有请求都需要包含的公共参数如下：

sign 的生成方式：除 sign 参数外，包括业务参数在内的所有参数都要参与签名，按字段名称 ASCII 码从小到大排序后，字段名和字段值都采用原始值使用 URL 键值对格式 key1=value1&key2=value2&key3=value3... 拼成字符串 string，然后对拼接后的字符串使用SHA-1算法生成签名 sign 。 注意: appSignKey 只参与签名，不作为请求参数。

Java版签名的例子 SignUtil.java：

public static void main(String[] args) throws IOException {
    String appId = "<appId>";
    String appSignKey = "<appSignKey>";
    String timestamp = String.valueOf(System.currentTimeMillis());
    String nonce = StringUtil.random(32);

    Map<String, Object> params = new HashMap<>();
    params.put("appId", appId);
    params.put("timestamp", timestamp);
    params.put("nonce", nonce);
    params.put("param1", "value1");//业务参数1
    params.put("param2", "value2");//业务参数2
    params.put("sign", getSign(params, appSignKey));

    //.发送请求
    String url = "https://ask.dxy.com/open/i/platform/130001";
    String responseBodyAsString = HttpClientUtil.post(url, params);
    System.out.println(responseBodyAsString);
}

/**
 * 获取签名
 *
 * @param params
 * @param appSignKey
 * @return
 */
public static String getSign(Map<String, Object> params, String appSignKey){
    TreeMap<String, Object> treeMap = new TreeMap<>();
    params.forEach(treeMap::put);
    treeMap.remove("sign");
    treeMap.put("appSignKey", appSignKey);
    StringBuilder signSb = new StringBuilder();
    treeMap.forEach((key, value) -> signSb.append(key).append("=").append(value).append("&"));
    if (signSb.length() > 0) {
        signSb.deleteCharAt(signSb.length() - 1);
    }
    return getSHA1(signSb.toString().getBytes());
}

/**
 * 用SHA1算法生成安全签名
 *
 * @param content 签名信息
 * @return 安全签名
 */
public static String getSHA1(byte[] content) throws NoSuchAlgorithmException {
    // SHA1签名生成
    MessageDigest md = MessageDigest.getInstance("SHA-1");
    md.update(content);
    byte[] digest = md.digest();
    StringBuffer hexstr = new StringBuffer();
    String shaHex = "";
    for (int i = 0; i < digest.length; i++) {
        shaHex = Integer.toHexString(digest[i] & 0xFF);
        if (shaHex.length() < 2) {
            hexstr.append(0);
        }
        hexstr.append(shaHex);
    }
    return hexstr.toString();
}

# 5. 返回结果示例

GET返回示例：

{
    "data": {
        "items": [
            {
                "order_id": 67000032,
                "question_id": 9800001,
                "status": 0,
                "merchant_fee": 1500,
                "create_timestamp": 1509372966000,
                "confirm_timestamp": 1509373966000
            }
        ]
    }
}

POST返回示例：

{
    "data": {
        "items": [
            {
                "updated": 1509419983789,
                "id": "6200001"
            }
        ]
    }
}

错误信息返回示例：

{
    "error": {
        "code": 10003,
        "message": "请求参数不正确"
    }
}

成功的请求返回结果会包含data节点，失败的请求返回结果会包含error节点。 接口返回为错误结构体时，code为错误码，message为错误信息。详细错误码定义见附录6.2。

分页数据结构示例：

{
    "data": {
        "items_per_page": 8, //每页包含元素个数
        "start_index": 9,   //当前页起始元素编号
        "page_index": 2,    //当前页码,从1开始
        "total_pages": 3,   //总页码
        "total_items": 20,  //总元素个数
        "current_item_count": 8,    //当前页元素个数
        "items": []
    }
}

其中：items_per_page表示每页包含元素个数，start_index表示当前页起始元素编号，page_index表示当前页码，total_pages表示总页码，current_item_count表示当前页元素个数。 注意应该通过判断page_index与total_pages的大小关系来确定是否有下一页。

# 4. 接口列表

# 1. 用户授权

# 100010-获取用户身份凭证

# 请求参数

# 返回结果

# 100011-获取免登录链接

# 请求参数

# 返回结果

# 2. 科室和医生信息

# 110001-快速提问搜索医生

# 请求参数

# 返回结果

# HospitalInfo数据结构

# 110002-科室列表

# 请求参数

# 返回结果

# 110003-科室下的医生列表

# 请求参数

# 返回结果

# HospitalInfo数据结构

# 110004-医生详细信息

# 请求参数

# 返回结果

# HospitalInfo数据结构

# 110005-通过提问内容推荐科室

# 请求参数

# 返回结果

# 3. 问诊相关

# 120001-创建问题

# 请求参数

# 返回结果

# 120002-获取问题详情

# 请求参数

# 返回结果

# Dialog数据结构

# VoiceDetail数据结构

# 120003-用户追问

# 请求参数

# 返回结果

# 120004-问题列表

# 请求参数

# 返回结构

同接口120002返回数据结构

# 4. 投诉处理

# 140001-发起投诉

# 请求参数

# 返回结构

# 140002-获取投诉

# 请求参数

# 返回结构

# 5. 订单相关

# 130002-订单查询

# 请求参数

# 返回结果

# 130001-订单确认

# 请求参数

# 返回结果

# 130003-关闭订单

# 请求参数

# 返回结果

# 5. 消息推送

除了通过调用API的方式与开放平台产生交互，还可以通过消息推送及时接收到新的状态信息。避免轮询API，大大提高API调用效率。 合作方接入时向丁香医生开发平台提供接口地址即可接收推送。

注意： 出于接口安全性的考虑，callback地址必须支持https，且必须是标准的443端口（即url格式为https://domain.com/xxx，不能带端口号）

为了保证系统安全，合作方作为服务端接收丁香医生发起的通知请求时，需要对请求参数进行验证签名。状态通知接口的业务参数不参与签名，仅对appId、appSignKey、nonce、timestamp参数按照上面「接口规范说明」-「签名方式」对数据进行签名得到签名字符串sign2。通过比较sign和sign2的相等与否来实现验签。

附上一段接收通知Java版示例供参考：

public class AskCallBackSample {

    private static final String APP_ID = "<appId>";
    private static final String APP_SIGN_KEY = "<appSignKey>";

    public String askCallback(HttpServletRequestMock httpServletRequest) throws Exception {
        Map<String, Object> params = new HashMap();
        params.put("nonce", httpServletRequest.getParameterValues("nonce")[0]);
        params.put("timestamp", httpServletRequest.getParameterValues("timestamp")[0]);
        String appIdParam = httpServletRequest.getParameterValues("appId")[0];
        params.put("appId", appIdParam);
        if (!APP_ID.equals(appIdParam)) {
            return "appId error";
        }
        String signLocal = SignUtil.getSign(params, APP_SIGN_KEY);
        if (signLocal == null || !signLocal.equals(httpServletRequest.getParameterValues("sign")[0])) {
            return "sign error";
        }
        //todo 业务处理...
        return "SUCCESS";
    }
}

/**
 * mock的Request类，实际情况应该使用{@link javax.servlet.http.HttpServletRequest}
 */
class HttpServletRequestMock {

    public String[] getParameterValues(String nonce) {
        return new String[]{""};
    }
}

具体的接口定义如下：

# 状态通知接口

# 请求参数

# 返回结果

# 6. 附录

# 1. 线下对账要素

附模版文件：商户订单模版.xls

# 2. 错误码定义

# 3. 投诉状态流转

# 7. 常见对接问题（Q&A）

# Q：问题详情中的音频、视频等资源文件的有效期是多长时间？

A：有效期为5min，合作方需要自行对资源文件进行本地化操作

# Q：如何进行测试？

A：目前丁香医生开放平台可以对接三种问诊类型

• 普通图文问诊
  • 向测试医生 小新（doctor_user_id：12196047） 提问即可，可以使用110004-医生详细信息接口获取医生信息
• 快速图文问诊&电话问诊
  • 需要双方商务商定好开通该服务，并提供一个已经调用过100010-获取用户身份凭证接口的uid添加到测试白名单

# Q：在110003-科室下的医生列表接口中找不到测试医生？

A：测试环境是沙盒模式，为防止正式用户问到测试医生产生不必要的麻烦，在这个接口中对测试医生进行了屏蔽。其他接口可以正常使用测试医生

# Q：如何进行联调？

A：为了节省双方的精力，丁香医生平台针对部分问诊流程测试进行了自动化操作

• 普通图文问诊&快速图文问诊医生接诊后，适用以下规则 （PS. 1和2仅适用于普通图文问诊） ，其中 x<=3,y<=9

  1. 回复【超时】问题被超时退回

  2. 回复【拒绝】医生拒绝当前问题

  3. 没有关键字（语音，图片，文字）

     医生回复：系统的测试文字

  4. 回复【文字】

     医生回复：患者的文字

  5. 回复【语音x】

     医生回复：语音x条，会分x次消息 发送

  6. 回复【图片y】

     医生回复：y张图片+默认的测试文字

  7. 回复【图片y】+【文字】

     医生回复：患者的文字+y张图片

  8. 回复【语音x】+【文字】

     医生回复：第一条：1条语音+患者发送的文字内容；x-1后面的语音都是单独发送

  9. 回复【语音x】+【图片y】

     医生回复：第一条：1条语音+y张图片；x-1后面的语音都是单独发送

  10. 回复【语音x】+【图片y】+【文字】

  医生回复：第一条：1条语音+y张图片+患者的文字；x-1后面的语音都是单独发送

• 电话问诊

  • 添加完测试白名单之后，联系丁香医生的测试

# Q：如何测试医生的语音回复？

A：针对每个平台，医生的语音回复功能默认是不开启的。若需要测试和使用，请联系丁香医生的技术或者测试开通后进行测试

# Q：联调过程中发现问题如何反馈？

A：丁香医生开放平台已经对接了多家合作方，一般情况下不会是平台方的错误，请反馈问题前先根据以下步骤进行自测

1. 仔细查看文档对比自己的代码是否存在遗漏的地方
2. 检查传递参数的编码格式以及请求方式
3. 检查签名的生成是否有误
4. 消息推送接口的返回值是否符合丁香医生平台方的规则

如果以上方法检查后依然无法排查出问题， 请携带以下俩种信息的一种进行反馈，以方便快速定位问题

• 【curl】

• 请求接口的详细参数，格式如下

  • 请求方法：POST/GET

  • 请求头：User-Agent: xxxx、ask-platform-sid: xxxxx

  • 请求参数(Json格式)：{"user_id": 12196047}

  • 请求接口返回值(Json格式)：{"error":{"code":10003,"message":"请求参数不正确"}}

# Q：测试医生小新，为什么经常停诊？停诊对用户有什么影响？

A：医生由于手术、忘记关诊等原因发生超时退回后，如果有新的提问，可能还会超时，用户体验不好。所以当月累计多个超时退回的问题后，将会自动停诊，测试医生由于大家经常测试超时退回，所以一有新的超时退回问题，就会停诊。停诊之后，已经提问的问题医生可以继续回复，只是接不到新的问题。小新医生只要测试了「超时未回复」的问题，就会停诊，测过这类问题以后就可以找我们开诊。

# Q：如何申请预发环境或者线上环境的APPID？

A：请向丁香医生商务这边申请，需要提供回调url，可以先给预发的回调，上线后再替换成线上的回调。

# Q：如何线上环境测试？

A：分为以下两种情况：

• 线上appId可以问线上和测试医生，测试appId只能问测试医生，线上appid测试的话，会走对账流程，会产生结算费用。如果线上对正式的医生进行提问，不要使用「测试」等语句，对医生造成不必要的困扰。请使用真实用户的问诊场景语句进行提问，且医生正常回复后，不予退款。

• 测试appId就是线上的数据，小新医生就是线上环境的医生，只是对权限进行了隔离，不能问正式医生。线上appId也可以提问测试医生小新，只不过不能在医生列表里找到小新医生，和测试环境流程一样向小新医生提问，需要手动指定，也可以自动回复，向小新医生提问，也会走结算流程。

# Q：医生响应时间出现0秒？

A：因为医生数据都是取的最近30天的数据，部分医生最近30天没有接诊问题，所以数据都是0，用户侧可以显示「暂无」。

# Q：快速图文如何自动回复？

小新医生属于儿科，请向儿科进行提问：

• 【接诊并回复】 小新接诊后立即回复。用户再问 就会走原来自动回复的逻辑

• 【接诊不回复】 小新接诊后不回复。 用户再问 就会走原来自动回复的逻辑