到位商户合作接口文档

标签：接口文档

如果商家通过自己的服务器处理订单，到位平台可通过该接口和商家的服务器之间进行订单及人员信息同步，便于商家使用自有订单系统处理来自到位平台的订单。如果商家已通过到位平台内置的“上单”系统派单，则无需另行使用此接口对接。

合作接口简介

用户提交订单后，到位系统通过商家提供的创建订单接口将订单同步到商家系统中。商家在订单状态发生变化时通知给到位。状态变化包括：商家取消订单、商家接单、商家确认订单完成。用户可以取消状态为“未接单”的订单，如果商家已经接单，用户就不能自己取消订单，只能通过申请退款或者联系客服进行取消订单。

商家需要实现下面几个接口：

  • 创建订单：用户提交订单，由到位通知商家。
  • 取消订单：用户取消订单，由到位通知商家。
  • 支付通知：用户支付订单，由到位通知商家。
  • 补差价：用户订单创建完成后有补差价行为，由到位通知商家。
  • 用户申请退款：用户申请退款的请求会通过此接口发送到商家（可选）。
  • 评论同步：用户评论完订单后推送到合作伙伴（可选）。
  • 选择预约时间：用户创建订单的时候选择上门服务的时间（可选）。
  • 选择技师：用户创建订单的时候选择上门服务的技师（可选）。
  • 订单扩展信息：商家可通过一个自定义的H5页面收集需要用户填写的扩展信息、计算增项费用；扩展信息将通过创建订单接口提交给商家，以实现各种特殊的下单流程。该接口另行参见订单扩展信息文档（可选）。

到位平台提供的接口：

  • 订单状态通知接口：商家在订单状态变化时调用该接口来更新到位平台的订单信息和订单状态。
  • 技师信息同步接口：商家可定期将所有技师的个人信息、位置、可服务时间等信息通过该接口同步给平台，以便用户就近直约技师、平台向技师就近派单（可选）。

订单交互流程主要有三种情况：

  • 正常完整流程：用户提交订单，合作伙伴最终完成订单。
  • 用户取消订单：用户提交了订单，未支付时取消了订单。
  • 商家取消订单：用户提交了订单，但商家由于某种原因取消了订单。

这三种流程的交互图如下： 正常完整流程 用户取消订单 商家取消订单

接口安全

账号设置

为保证到位和商家的接口通信安全，需要对数据通信进行签名和验证。到位使用appkey和appsecret保证安全。appkey和appsecret由到位提供给商家，商家需妥善保管以防泄露。

appkey是商家身份的唯一标识，加密密钥appsecret用来对提交的数据和通知的数据进行签名，appkey会在网络上进行传输，而appsecret不会在网络上进行传输。

请联系到位技术接口人获取您的appkey和appsecret。

为方便演示,假设您的 appkey 为7323fb1fae8249659a08b0ab70022c2d, appsecret 为3c3ed7574654433bbdb14b39947d3ef9

接口调用规则

  • 所有请求都采用POST方式，字符集使用UTF-8。
  • 所有请求都需要附加上 appkey、oncestr、sign 三个字段，appkey为商家标识，oncestr为随机字符串，sign为签名，数据验签名需要用到appkey和appsecret，签名方法见下节，这三个字段都是32个字符。
  • 所有返回值都应该是JSON类型。

数据签名方法

生成 sign 字符串的方法是：

  1. 对所有参数(不包括 sign)按照字段名的 ASCII 码从小到大排序(字典序) 后,使用 URL 键值对的格式(即 key1=value1&key2=value2...)拼接成字符串 string1，注意：值为空的参数不参与签名,签名之前需要通过 URLEncode,
    • 例如，假如原参数只有一个id,值为21089397,则string1为 string1 = 'appkey=7323fb1fae8249659a08b0ab70022c2d&id=21089397&oncestr=8fa6b61dc33d4a848f79531037a0b9e2
  2. 在 string1 最后拼接上 secret=appsecret (加密密钥) 得到stringSignTemp
    • 例如,String stringSignTemp = "appkey=7323fb1fae8249659a08b0ab70022c2d&id=21089397&oncestr=8fa6b61dc33d4a848f79531037a0b9e2&secret=3c3ed7574654433bbdb14b39947d3ef9";
  3. 对stringSignTemp 进行 md5 运算,再将得到的字符串所有字符转换为大写,得到sign的值
    • 例如，String sign = md5(stringSignTemp).toUpperCase();sign = "67CE6E661DB75A14206A4BD7FC5DC45E";

Java参考代码实现见商家实现示例，类DaowayUtils提供了如下方法创建签名：
public static String sign(SortedMap<String,String> map, String appkey, String appsecret)

到位服务端提供的接口

订单状态通知接口

到位平台通过此接口接收商家的订单状态更新通知。

  • 方法为POST， 测试环境：http://test.daoway.cn:8080/daoway/rest/order_notify 正式环境：http://api.daoway.cn/daoway/rest/order_notify
  • 参数除了appkey、oncestr、sign外，还有：
    • orderId：订单id
    • status：订单状态, 值可以为ongoing(商家接单),canceled（商家取消）,completed（商家确认完成）,approve_refund（同意用户退款请求）、reject_refund（拒绝用户退款请求）、part_return（商家请求部分退款给用户）、set_diff（设置补差价金额）order_diff（在商家平台补差价）modify_tech(修改技师信息) ，以及order_track（更新订单进度）。当值为空时订单状态不做修改，只修改其它信息。
    • note：状态变化的原因（状态为取消订单或拒绝用户退款时必须有相应的原因用于显示给用户，其他情况下不要传递）
    • technicianId:当操作为商家接单（status为ongoing）或者需要修改技师信息（status为modify_tech）时，可以传递技师ID
    • technicianName:当操作为商家接单（status为ongoing）或者需要修改技师信息（status为modify_tech）时，可以传递技师姓名
    • technicianPhone:当操作为商家接单（status为ongoing）或者需要修改技师信息（status为modify_tech）时，可以传递技师电话
    • bill ：double类型，当操作是商家请求部分退款给用户（status为part_return）时传递部分退款金额，在商家平台进行了补差价（status为order_diff）时或者商家设置补差价金额（status为set_diff），传递补差价金额
    • appointTime; ：long类型，在商家平台修改了预约时间时，传递新的预约时间
    • ownerNote ：String 类型，在商家平台修改了商家备注，传递新的商家备注
    • orderTrackStatus ：String 类型，订单进度状态，需要更新订单进度时（status为order_track）传递提前约定好的状态值。
  • 返回格式为JSON
    • 成功返回 {"status":"ok"}
    • 失败返回: {"status":"error","msg":"失败原因"}

注意：状态为已接单（ongoing）的订单，用户未申请退款的情况下，商家再单方面通过该接口取消订单（将状态更新为canceled）视为商家爽约，将自动触发“商家爽约赔付”流程向用户赔付；如果是用户主动要求取消订单的，商家客服需引导用户在到位平台先发起退款申请，再取消订单或退款即无需赔付。

技师信息同步接口（可选）

到位平台通过此接口接收商家的技师信息更新通知。 

{
  "appkey": "appkey",
  "oncestr": "oncestr",
  "sign": "sign",
  "data": [
    {
      "id": "技师Id",//必填，其他都是可选的
      "real_name": "真实姓名",//添加技师时必填
      "nick_name": "昵称",//如指定了昵称，将向用户隐藏真实姓名
      "description": "个人简介",
      "gender": 0 (男)| 1 (女)  默认男,
      "phone": "手机", //添加技师时必填
      "city": "服务城市，不含市，比如 广州", //添加技师时必填
      "start_time": "上班时间，比如08:00", //如果未指定，默认为店铺上班时间
      "end_time": "下班时间，比如19:00", //如果未指定，默认为店铺下班时间
      "head_photo": "头像链接", 
      "available_days": "0,1,2,3,4,5,6", //每周哪几天可服务，0表示周一,6表示周日，如未指定，默认值为"0,1,2,3,4,5,6"表示一周七天均可服务
      "online": 0|1，//是否上架，0表示下架，1表示上架，默认为1
      "busy_time": {//每一条对应一天，该天的忙时会被覆盖，以半小时为单位
          "2018-03-22": "17:00,17:30,18:00,18:30"，
          ......
        },
      "location": {//技师位置
        "time":"2018-03-20 12:26:14" //获得最后位置的时间
        "lng": "经度",
        "lat" : "维度"
      }
    }, ......
  ]
}

添加技师： id在到位库中不存在，则添加新技师，此时real_name，phone，city，start_time，end_time，available_days,head_photo必填。

更新技师： id在到位库中存在，则更新技师，此时只有id是必填的，其他均可选，如果传递的信息不为空，则更新相应信息。phone不能与到位库中已有的冲突，否则返回错误。busy_time中的忙时按天设置，如果之前设置过该天的忙时，新的设置会覆盖旧的设置。

更新技师位置： 如果只是更新技师位置，只需要传递id和location，传递位置不要过于频繁，当技师位置变化时，建议每10分钟到半小时更新一次

数据签名： data节点下的数据不拆分，作为一个字符串参与签名。

需要商家提供的接口

到位需要商家提供下面这几个接口URL，分别用于创建订、取消订单、支付通知接口、补差价、用户申请退款（可选）、选择预约时间（可选）、选择技师（可选）等，接口需要符合以下规范。

创建订单

用户提交订单时，到位平台通过该接口通知商家创建订单

  • 方法为POST

  • 参数除了appkey、oncestr、sign外，还有：

    • contactPerson：联系人
    • userId：到位系统中的用户ID
    • orderId：到位系统中的订单ID
    • serviceId：到位系统中的店铺ID
    • phone：联系电话
    • address：地址
    • city：城市
    • street：街道
    • house：详细地址
    • addrLat：上述地址纬度
    • addrLng：上述地址经度
    • appointTime：预约时间，格式为yyyy-MM-dd HH:mm:ss，如2015-03-31 20:05:00
    • note：备注
    • technicianId：技师ID(可选，无技师时不传)
    • items：订单项目，items为URLEncode后的json数组，每一项为一个订单条目，订单条目包括项目名称(name)，价格(price)，单位(unit)、第三方ID（thirdId）和数量(quantity)
    • extraInfo：附加信息
    • extraFee：附加费用
    • distance：距离（单位：公里，当店铺开启了第二地址并启用了动态计价）
    • destinationMap：目的地信息（当店铺开启了第二地址后，主要用于搬家、货运、跑腿类店铺），为URLEncode后的json对象，对象包括dstAddr（地址），dstCity（城市），dstContact（联系人），dstHouse（门牌号），dstPhone（电话），dstStreet（街道），dstLng/dstLat（经纬度）

    附加信息参考

  • 返回格式为JSON

    • 成功返回商家系统中的订单id（不超过32个字节），例如：{"status":"ok","orderId":"201503251556235271894251"}
    • 失败的情况下返回错误原因，如果出现创建失败的情况， 请返回友好的用户提示信息 例如：{"status":"error","msg":"超出服务范围"} 不要返回模棱两可用户看不懂的消息例如：{"status":"error","msg":"创建失败"}

例如，订单信息为：

{
    "contactPerson": "张三",
    "userId": "da058ab4a72a42aab98512210f498a6f",
    "orderId": "331206de0ffa40ba8f10c7103d16bab1",
    "serviceId": "11d4ac24421f43eda3f2f7b6751a9ac0",
    "phone": "1383838438",
    "address": "北京市海淀区大钟寺华杰大厦B座215",
    "city": 北京,
    "street": 海淀区大钟寺华杰大厦,
    "house": B座215,
    "appointTime": "2015-09-15 12:32:12",
    "addrLat": 39.97006351299,
    "addrLng": 116.34805388544,
    "technicianId": "123",
    "items": [
        {
            "name": "驴肉火烧",
            "price": "5",
            "unit": "元/个",
            "thirdId": "80001",
            "quantity": 4
        },
        {
            "name": "驴杂汤",
            "price": "6",
            "unit": "元/碗",
            "thirdId": "80002",
            "quantity": 2
        }
    ],
    "note": "来之前请电话确认"
}

则网络中传输的POST请求实际内容如下： addrLat=39.97006351299&addrLng=116.34805388544&address=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%B5%B7%E6%B7%80%E5%8C%BA%E5%A4%A7%E9%92%9F%E5%AF%BA%E5%8D%8E%E6%9D%B0%E5%A4%A7%E5%8E%A6B%E5%BA%A7215%E5%AE%A4&appkey=7323fb1fae8249659a08b0ab70022c2d&appointTime=2015-09-15A%22%E9%A9%B4%E8&contactPerson=%E5%BC%A0%E4%B8%89&items=%5B%7B%22unit%22%3A%22%E5%85%83%2F%E4%B8%AA%22%2C%22price%22%3A%225%22%2C%22name%22%3A%22%E9%A9%B4%E8%82%89%E7%81%AB%E7%83%A7%22%2C%22quantity%22%3A4%7D%2C%7B%22unit%22%3A%22%E5%85%83%2F%E7%A2%97%22%2C%22price%22%3A%226%22%2C%22name%22%3A%22%E9%A9%B4%E6%9D%82%E6%B1%A4%22%2C%22quantity%22%3A2%7D%5D&note=%E6%9D%A5%E4%B9%8B%E5%89%8D%E8%AF%B7%E7%94%B5%E8%AF%9D%E7%A1%AE%E8%AE%A4&oncestr=e337cbf050d24dc2a2520462d062a0a8&phone=1383838438&sign=FD451F168920F76AD5F67FC9A2FB3F19

取消订单

用户取消订单时，到位平台通过该接口通知商家取消订单

  • 方法为POST
  • 参数除了appkey、oncestr、sign外，还有：
    • orderId：订单id
    • note：用户取消订单的理由
  • 返回格式为JSON
    • 成功的情况下返回{"status":"ok"}
    • 失败的情况下返回错误原因，例如：{"status":"error","msg":"请联系客服取消"}

注意：商家未确认接单的订单，必须要能直接取消成功；商家已确认接单的订单，需由商家自行决定是否可取消。

通常，商家可通过取消订单接口来处理已确认订单的退款申请（仅限全额退款）；也可通过单独实现“用户申请退款”接口来处理所有退款申请（支持部分退款）。

如果商家未实现“用户申请退款”接口，当用户申请全额退款时，到位平台将向商家的“取消订单”接口发起取消通知，商家返回status为ok表示同意取消订单并自动退款，否则表示暂不处理退款，但商家也需要记录下来用户的退款申请，尽快由人工跟进取消/退单操作。

支付通知

用户对已提交的订单支付成功时，到位平将台通过该接口通知商家

  • 方法为POST
  • 参数除了appkey、oncestr、sign外，还有：
    • orderId：订单id
    • daowayOrderId：到位订单id
    • bill ：支付金额（double,单位“元”,(指用户实际支付的金额)非必填）
    • daowayCouponBill ：到位代金券金额（double,单位“元”非必填）
    • shopCouponBill ：商家代金券金额（double,单位“元”非必填）
  • 返回格式为JSON
    • 成功的情况下返回{"status":"ok"}
    • 失败的情况下返回错误原因，例如：{"status":"error","msg":"通知失败原因"}

补差价

用户对已提交的订单补差价（二次支付）时，到位平将台通过该接口通知商家

  • 方法为POST
  • 参数除了appkey、oncestr、sign外，还有：
    • orderId：订单id
    • bill:补差价的金额
  • 返回格式为JSON
    • 成功的情况下返回{"status":"ok"}
    • 失败的情况下返回错误原因，例如：{"status":"error","msg":"相应的错误信息}

评论同步

用户对已完成的订单发表评论时，到位平将台通过该接口通知商家

  • 方法为POST
  • 参数除了appkey、oncestr、sign外，还有：
    • orderId：订单id
    • score:评分（5分制）
    • comment：评论的内容
  • 返回格式为JSON
    • 成功的情况下返回{"status":"ok"}
    • 失败的情况下返回错误原因，例如：{"status":"error","msg":"相应的错误信息}

选择预约时间

用户下单前，可通过该接口请求商家返回指定项目、指定地点、指定技师可服务的时间表

  • 方法为POST
  • 参数除了appkey、oncestr、sign外，还有：
    • priceName ：服务（产品）名称
    • thirdId： 第三方ID
    • quantity ：数量
    • lng ：经度
    • lat ：维度
    • city：城市名称
    • street ：街道
    • house ：门牌号
    • technicianId ：技师Id（扩展参数，如果传递了技师ID，应返回该技师的可预约时间列表；如果未传递技师ID，则应返回店铺的可预约时间列表）
  • 返回格式为JSON
    • 成功的情况下返回如下格式
    • 失败的情况下返回错误原因，例如：{"status":"error","msg":"获取失败"}
    {"status":"ok"，
       "body":{ 
        "timeList":[  
        { 
            "date":"2015-04-18",  // 预约日期
            "timeslot":"000000001111110000111100000000000011111100001111" 
            // 以30分钟为单位，共48位，表示时间是否可预约。0表示不可约，1表示可约。
        }， 
        { 
            "date":"2015-04-19", 
            "timeslot":"000000001111110000111100000000000011111100001111" 
        } 
        ... 
        ] 
    } }

选择技师

用户下单前，可通过该接口请求商家返回指定项目、指定地点可服务的技师列表

  • 方法为POST
  • 参数除了appkey、oncestr、sign外，还有：
    • priceName ：服务（产品）名称
    • quantity ：数量
    • serviceTime：服务时间 格式为2015-04-18 10:30
    • thirdId： 第三方ID
    • lng ：经度
    • lat ：维度
    • city：城市名称
    • street ：街道
    • house ：门牌号
  • 返回格式为JSON
    • 成功的情况下返回如下JSON
    • 若无可用技师的情况：{"status":"error","msg":"无可用技师"}
    • 失败的情况下返回错误原因，例如：{"status":"error","msg":"获取失败"}
     {"status":"ok"，
       "body": { 
        "technicianList": [
            {
                "technicianId": "10010",
                "name": "苏三",  //真实姓名，必填
                "nickName": "阿三",//可选，如无昵称将显示真实姓名
                "city": 北京     
                "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后" //多个用逗号分割
            },
            // ...
        ]
    }}

用户申请退款

当商家接单后，用户无法再直接取消订单， 只能通过申请退款进行退单。 到位将用户申请退款的请求推送到商家，由商家来审核是否予以退款并将审核结果通过“订单状态通知接口”反馈给到位。审核通过则予以退款；审核不通过，订单则进入待仲裁阶段，由到位的客服人员跟进。

  • 方法为POST
  • 参数除了appkey、oncestr、sign外，还有：
    • orderId：订单id
    • bill:申请退款的金额
    • note:申请退款的理由
  • 返回格式为JSON
    • 成功的情况下返回{"status":"ok"}
    • 失败的情况下返回错误原因，例如：{"status":"error","msg":"相应的错误信息}

说明：如果用户申请退款的金额bill和付款金额一致，表示用户申请全额退款，相当于用户要求取消订单；如退款金额小于付款金额，表示用户只申请部分退款，并非要取消订单。虽然通过“取消订单”接口能进行全额退款，但只有通过该接口才能实现部分退款。

计算附加费

搬家货运跑腿类的商家需要实现该接口，用来计算附加费

  • 方法为POST
  • 参数除了appkey、oncestr、sign外，还有：
    • fromAddress
    • toAddress
    • fromCity
    • toCity
    • appointTime //预约时间
    • fromLng
    • fromLat
    • toLng
    • toLat
    • thirdId 服务项目第三方ID
  • 返回格式为JSON
    • 失败的情况下返回错误原因，例如：{"status":"error","msg":"相应的错误信息}
    • 成功的情况下返回 { "status": "ok", "body": [ { "extraFeeBill": 11.11,//附加费金额 "distance ": 1000,//（米）超里程费该字段必须返回 "extraFeeName": "超里程费"//附加费名称 }, { "extraFeeBill": 11.11,//附加费金额 "extraFeeName": "溢价费"//附加费名称 } ] }

示例代码

到位提供了Java示例实现方便合作，下载示例代码。这是一个普通的Java Web Eclipse工程，下载后导入Eclipse就可以使用。

项目代码简单介绍：

  • OrderStatusNotifier：这是一个独立的Java Main程序，演示调用到位的订单通知接口。
  • OrderServlet：这是一个Java Servlet，提供了创建订单的接口和取消订单的接口，演示了如何验证到位签名、如何获取订单相关参数等。
  • DaowayConfig： 包括appkey和appsecret，这个需要联系到位商务获取并进行更改。
  • DaowayUtils：提供了签名验证和对请求数据做签名的接口
  • OrderStatus：订单状态的枚举类
  • OrderInfo和OrderItemInfo：订单信息类

合作流程

  1. 联系到位商务获取appkey和appsecret
  2. 根据到位文档和示例代码实现接口合作：
    • 实现创建订单接口，支付通知接口，取消订单接口， 补差价接口，用户申请退款接口
    • 在订单状态变化的情况下通知到位接口
  3. 使用到位开放平台测试双方接口的互调，测试地址，技术问题咨询（QQ：285565487）
  4. 经过上一步骤的基础测试通过后，将这创建订单接口，支付通知接口，取消订单接口， 补差价接口，用户申请退款等接口发给到位技术接口人。
  5. 双方技术验证整个流程，实现订单接口合作。

关于我们

  • 到位：高品质O2O上门服务直约平台
  • 北京邻家科技有限公司：创办于2014年6月，致力于打造中国最好的O2O上门服务推荐平台，让手机用户能更轻松、快捷、安全地享受身边的各种优质服务
  • 地址：北京市东城区和平里东街11号航星园4号楼2层
  • 客服电话: 4000-908-608
  • 商务合作: 010-64522010