点评到家与服务方对接接口

1. 整体介绍

1.1 对接方案v1.0

1. 服务方离线将服务产品提供给点评，点评为用户提供产品列表、详情展示。（注意：目前点评到家禁止出现引导至其他APP或微信号下单的内容）
2. 用户选择服务时间、服务份数及服务地点，点评向第三方查询可用技师列表。
3. 用户选择技师，点评将订单信息同步给服务方用于创建服务方订单，同时生成服务方orderId，后续订单信息同步均以服务方orderId为准。
4. 用户在点评完成支付后，点评通知服务方支付完成。后续服务及订单状态变更由服务方同步给点评。

1.2 时序图

1.3 接口列表

1.3.1 服务方提供接口

备注:技师和产品列表变化不大,每天离线定期同步。

1.3.2 点评提供接口

备注:接口中所有经纬度，均为火星坐标系（火星坐标与高德、腾讯坐标一致，跟百度之间需要转换）

1.3.3 车类服务商接口（可选）

1.3.4 城市及状态码

点评城市 ID 编码:

更多城市ID

点评到家服务项目编码:

如果服务方提供多种类目服务(如美甲, 美容)，则需要设置serviceId，由点评提供。
服务方仅一种类目时，忽略serviceId即可。

点评订单状态码:

返回结果状态码定义:

msg:简单描述

1.4 签名

所有接口统一使用HTTP POST协议，返回结果为JSON。为安全考虑，请求需要做签名，以防止被伪造或串改，双方互相验证对方签名。联调测试阶段可以忽略签名，线上环境需验证。

测试环境AppKey统一为ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

1.4.1 基础请求字段

1.4.2 签名计算方法

例如,我们请求接口queryAvailableTechnicians（简化版）
POST /queryAvailableTechnicians
请求参数

• 第一步，将所有请求的数据按字段名进行字段升序排序。
• 第二步，将【字段名】和【值】（url编码前的）按照第一步的顺序进行拼接,得到字符串 methodNamequeryAvailableTechnicianspartnerIddianpingproductId4321serviceAddress北京市朝阳区version1.0
• 第三步，将【点评】提供的appKey，比如ABCDEFGHIJKLMNOPQRSTUVWXYZ123456，拼接在第二步中获得的字符串后面得到字符串: methodNamequeryAvailableTechnicianspartnerIddianpingproductId4321serviceAddress北京市朝阳区version1.0ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
• 第四步，将该字符串进行MD5计算结果为e15d48ce15536ca94c7e55d5e8963d99
• 第五步，将第四步得到的字符串全部upperCase，得到E15D48CE15536CA94C7E55D5E8963D99，这就是最后得到的签名。
• 备注： 请动态获取参数，接口中的参数有可能会增加减少，不要硬编码

服务方验证签名过程示例

服务方收到的请求为（urlencode使用UTF8编码）：  
curl -d "methodName=queryAvailableTechnicians&productId=4321&serviceAddress=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%9C%9D%E9%98%B3%E5%8C%BA&partnerId=dianping&version=1.0&sign=E15D48CE15536CA94C7E55D5E8963D99" api.{thirdparty.host}.com/dianping/queryAvailableTechnicians

服务方接收到的POST内容为paramsMap，签名计算过程如下： 

appKey='ABCDEFGHIJKLMNOPQRSTUVWXYZ123456' //点评提供的appkey
combinedStr=''   // 计算拼接字符串
keys = paramsMap.keys()
sortedKeys = keys.sort() // keys排序

for(key in sortedKeys)
    if key != 'sign' 
        combinedStr += ( key + urldecode(paramsMap[key]) ) // 这里注意要解码成原始字符串
combinedStr += appKey

sign = upperCase(md5(combinedStr))

2. 服务方提供接口

2.1 获取技师列表(queryTechnicianList)

接口说明:
获取技师列表（服务方所有技师，不区分城市），由点评离线每天调用。如果没有技师概念，需要同点评产品对接人确认后，可不需要提供该接口。

参数说明:

返回结果:

{
    "code": "0",
    "msg": "success",
    "body": {
        "totalSize": 15,
        "technicianList": [
            {
                "technicianId": "10010",
                "name": "苏三",
                "cityId": 1     // 点评城市ID，参考[1.3.3节](#1.3.3)
                "sex": "男",
                "age": 35,
                "photoURL": "http://xx.jpg",
                "workingAge": 5,
                "orderAmount":45, // 接单总量
                "level":3,         // 技师星级，1到5星
                "longitude": 121.134,
                "latitude": 31.54,
                "phone":"13456268429"
                "description": "描述",
                "tags":["90后","小清新"]
            },
            // ...
        ]
    }
}

无技师概念，返回`20003`
{
    "code": "20003",
    "msg": "该服务无技师列表",
}

2.2 获取服务产品列表(queryProductList)

接口说明:
获取产品列表，由点评离线每天同步。

参数说明:

返回结果:

{  
    "code": "0", 
    "msg": "success",  
    "body": { 
        "totalSize":15, 
        "productList":[ 
        { 
            // 这些为服务产品通用字段
            "productId":"10010", 
            "productName":"蝴蝶梦", 
            "orderAmount": 33,          // 产品销量
            "duration":120,             // 服务耗时，以分钟为单位
            "abstract":"产品简要描述，用于展现在产品列表页的一行内容（可选字段）",
            "description":"简要描述",
            "originalPrice":130,        // 原始价格
            "settlePrice":89,           // 真实价格
            "minOrders":1,              // 最小下单份数
            "maxOrders":1,              // 最大下单份数
            "imageUrls": [
                "http://a.jpg", "http://b.jpg" // 产品图片
            ],
            "thumbUrl": "http://a.min.jpg", // 产品预览图
            "details": [{   // 图文详情
                "type": 1,  //  1: 图片url, 2: 纯文本 
                "content": "http://a.big.jpg"
            }, {
                "type": 1,
                "content": "http://b.big.jpg"
            }, {
                "type": 2,
                "content": "描述文案..."
            },  // ... ],
            // 以下为可选字段
            "rank": 1,  // 排序，越小越靠前
            "packageList":[ 
                { 
                    "packageId":"1", 
                    "packageName":"基础套餐", 
                    "originalPrice":96,         // 套餐原始价格，以元为单位
                    "settlePrice":64,           // 套餐实际价格
                    "duration":30               // 服务时长，分钟为单位
                    // 可选字段，不提供则统一试用产品数据
                    "description":"简要描述",
                    "imageUrls": [
                        "http://b.jpg", "http://c.jpg", ...
                    ],  // 套餐图片
                    "details": [{   // 图文详情
                        "type": 1,  //  1: 图片url, 2: 纯文本 
                        "content": "http://a.big.jpg"
                    }, {
                        "type": 1,
                        "content": "http://b.big.jpg"
                    }, {
                        "type": 2,
                        "content": "描述文案..."
                    },  // ... ]
                }, 
                { 
                    "packageId":"2", 
                    "packageName":"基础套餐+半贴片", 
                    "originalPrice":126, 
                    "realPrice":126, 
                    "duration":30,
                    // ...
                },
                ....
            ]
            "style": "样式",
            "color": "花色", 
            "keptTime":25,              // 产品保持时间，以天为单位
        },
        // ... //更多product
        ] 
    }  
}

字段说明
备注：product字段不同频道可能会不同，从packageList以下均为可选字段，可根据频道特定做字段定制

details

展示具体效果见 点评app-上海市-到家-宠物-握爪-产品详情页，数据如下（不支持html标签）

[
    {
        "type":1,
        "content":"http://7oxer3.com2.z0.glb.qiniucdn.com/gougouliucheng1-1.png   "
    },
    {
        "type":1,
        "content":"http://7oxer3.com2.z0.glb.qiniucdn.com/gougouliucheng1-2.png  "
    },
    {
        "type":1,
        "content":"http://7oxer3.com2.z0.glb.qiniucdn.com/gougouliucheng1-3.png  "
    },
    {
        "type":2,
        "content":"【服务范围】：上海（郊县及边远地区除外)\n 【温馨提示】\n宠物不适宜情况：\n 1、疫苗未完成或完成一周内的幼犬猫；\n 2、怀孕、哺乳期间的犬猫；\n 3、高龄犬猫（10岁以上）；\n 4、10KG以上狗狗和8KG以上猫猫；\n 5、具有强烈攻击性的犬猫 \n 【下单提醒】\n请至少提前三天预约。\n 建议下单后第一时间拨打400-032-8170联系握爪客服，为您安排上门服务时间。\n如需取消或更改订单时间的，请提前一天以上拨打400-032-8170联系握爪客服"
    }
]

美甲/按摩/美睫等频道需要额外提供字段：

2.3 可预约时间列表(queryAvailableTimeslots)

接口说明:
给定服务项目、套餐类型、预约份数、服务地点，返回可服务的时间列表。点评在用户选择时间前调用。
timeslot为1的标记位表示可以提供服务。

备注：
1. 如果服务地址覆盖不到（比如过于偏远，没有服务点/技师）可返回code：20001。
2. 可选时间需考虑派单的处理时长。假设每天上班时间为8:00，派单需2小时处理完成，当前时间为中午12:00。那么用户仅可选择当天的开始时间在2小时之后的时间段（>= 14:00），以及当天以后的开始时间在上班时间2小时之后的时间段（>= 10:00）。

参数说明:

返回结果:

{ 
    "code":"0", 
    "msg":"success" 
    "body":{ 
        "timeList":[  
        { 
            "date":"2015-04-18",  // 预约日期
            "timeslot":"000000001111110000111100000000000011111100001111" 
            // 以30分钟为单位，共48位，表示时间是否可预约 
        }， 
        { 
            "date":"2015-04-19", 
            "timeslot":"000000001111110000111100000000000011111100001111" 
        } 
        ... 
        ] 
    } 
} 

2.4 获取可用技师(queryAvailableTechnicians)

接口说明:
用户选择服务产品、服务份数、服务地址及服务时间，点评调用服务方接口，获取可用技师列表。
服务方需要保证:
1. 判断服务地址是否在服务范围内；
2. 在用户选定时间是否有可用技师（如果不支持技师选择，可伪造技师id为”0”）。

参数说明:

返回结果:

成功：
{
    "code": "0",
    "msg": "success",
    "body": {
        "technicianIds": [
            "10000001",
            "10000002",
            ..] // 返回技师列表，默认用第一个 
    }
}

成功，伪造技师：
{
    "code": "0",
    "msg": "success",
    "body": {
        "technicianIds": [
            "0"] // 伪造技师id，使用0
    }
}

2.5 创建订单(createOrder)

接口说明:
用户确认技师后，进入支付页面，点击确认付款，点评调用服务方该接口，创建一个未支付订单。支付必须要10分钟内完成,否则订单过期，库存自动解锁。

参数说明:
备注：这些参数是基本信息，不同频道可能有特殊需求，可单独沟通

返回结果:

{
    "code": "0",
    "msg": "success",
    "body": {
        "orderId": "12345" // 服务方订单id，后续订单操作均以此id为标准
    }
}

2.6 订单已支付(orderPaied)

接口说明:
订单支付后,点评调用服务方该接口,通知订单已付款。

参数说明:

返回结果:

{
    "code": "0",
    "msg": "success",
}

幂等性: 如果第三方订单处于已支付状态，点评再次调用orderPaied接口，应该返回如下结果（原因：只要保证两边订单状态的最终一致性即可）

{
    "code": "0",
    "msg": "success",
}

2.7 取消订单并解锁库存(cancelOrder)

接口说明:
订单创建后,用户取消订单或订单过期未支付，点评调用服务方取消订单。建议服务方自己也做个监控，长时间未支付订单直接过期掉。

参数说明:

返回结果:

{
    "code": "0",
    "msg": "success",
}

{
    "code": "0",
    "msg": "success",
}

2.8 确认完成订单(confirmFinishOrder)

接口说明:
点评客户端支持用户自己来确认完成订单，用户确认后点评会把该状态同步给第三方（有重试机制）

参数说明:

返回结果:

{
    "code": "0",
    "msg": "success",
}

{
    "code": "0",
    "msg": "success",
}

3. 点评提供接口

3.1 更新订单状态(updateOrderStatus)

接口说明:
服务方接单后，更新状态进度。服务方更新状态目前只支持13（确认订单）、3（技师出发）、4（服务中）、5（服务已完成）四种状态。

参数说明:

返回结果:

{
    "code": "0",
    "msg": "success",
}

测试环境点评接口

curl -d "methodName=updateOrderStatus&orderId=0&status=3&sign=A9053F1E7FD0D38B2F3848A7E8D5FDCC" http://m.api.51ping.com/tohome/openapi/3rd/

orderId=0时仅验证签名

3.2 更新订单信息(updateOrderInfo)

接口说明:
服务方调用点评，更新订单信息。目前只支持更新服务的指派技师（确认后即可调用），后续视需要可开通更多信息更新。技师id用于做评价及再次预约入口。

参数说明:

返回结果:

{
    "code": "0",
    "msg": "success",
}

3.3 服务方取消订单(partnerCancelOrder)

接口说明:
服务方调用点评，取消订单并退款，不管当前订单状态（如果用户已支付）。目前默认全额退款，后续会支持服务方设置价格。安全考虑，除了签名验证，点评端会做ip白名单。

参数说明:

返回结果:

{
    "code": "0",
    "msg": "success",
}

3.4 查询已同步订单状态(loadOrderInfo)

接口说明:
服务方调用点评，查询已同步订单，安全考虑，除了签名验证，点评端会做ip白名单。

参数说明:

返回结果:

{
  "code": "0",
  "msg": "success",
  "body": {
    "cityId": 1,
    "productId": 1,
    "serviceTime": "2015-07-06 19:30",
    "price": 111,
    "latitude": 31.215377,
    "longitude": 121.420333,
    "serviceAddress": "长宁区安化路492号A6",
    "houseNumber": "长宁区安化路492号A6",
    "cellphone": "13564950570",
    "serviceId": 1,
    "packageId": "1",
    "quantity": 1,
    "status": 2
  }
}

测试环境点评接口

curl -d "methodName=loadOrderInfo&orderId=643&sign=9ACB6DB1DC74C2A5C7C6B80D06237E93" http://m.api.51ping.com/tohome/openapi/3rd/

orderId=0时仅验证签名

4. 车类服务商接口

4.1 车类服务商接口

接口说明:
服务方需要提供汽车品牌信息接口，接口返回json数据。
相应车类信息 ，会在 createOrder 中通过额外字段extraInfo={“carbrand” : “奔驰(进口)”,”carseries” : “A级系列”,”caryear”: “A160(W169) 1.6L 2009.04-2014”} 传回车型信息。

参数说明:

返回结果:

{
  "totalSize": 100,
  "brand_list": [
    {
      "brand_id": "1",
      "brand_name": "丰田(品牌名称)",
      "logo_url": "http://www.baidu.com",
      "brand_first_char": "F",
      "series_list": [
        {
          "series_id": "1",
          "series_name": "汉兰达（系列名称）",
          "status": 1,
          "carType_list": [
            {
              "type_id": "1",
              "type_name": "年款"
            },
            {
              "type_id": "2",
              "type_name": "年款2"
            }
          ]
        },
        {
          "series_id": "2",
          "series_name": "海狮（系列名称）",
          "status": 1,
          "carType_list": [
            {
              "type_id": "1",
              "type_name": "年款"
            },
            {
              "type_id": "2",
              "type_name": "年款2"
            }
          ]
        }
      ]
    },
    {
      "brand_id": "1",
      "brand_name": "丰田(品牌名称)",
      "logo_url": "http://www.baidu.com",
      "brand_first_char": "F",
      "series_list": [
        {
          "series_id": "1",
          "series_name": "汉兰达（系列名称）",
          "status": 1,
          "carType_list": [
            {
              "type_id": "1",
              "type_name": "年款"
            },
            {
              "type_id": "2",
              "type_name": "年款2"
            }
          ]
        },
        {
          "series_id": "2",
          "series_name": "海狮（系列名称）",
          "status": 1,
          "carType_list": [
            {
              "type_id": "1",
              "type_name": "年款"
            },
            {
              "type_id": "2",
              "type_name": "年款2"
            }
          ]
        }
      ]
    }
  ]
}

字段说明