关于协议

1 接口

1.1 接口地址

https://api-be.ele.me/

1.2 协议说明

HTTP/POST,数据类型为Content-Type: application/x-www-form-urlencoded,字符编码为UTF-8,数据结构如下,body字段为数据字段,其他字段为协议字段:

cmd: order.create
timestamp: 1429704178
version: 3
ticket: 8C7D975C-9E9B-F8AB-0D8A-D1B5E3ECF786
source: 001
sign: af2fe13af77263bab08901cbb11114f7
body: {"name":"\u6d4b\u8bd5\u5546\u6237","shop_id":"12345"}
encrypt: des.v1
fields: a|b
注意:数据传输为key=value格式,如body中的业务参数中含有特殊符号:如 +,%,需要进行urldecode。

1.3 签名计算

通过source及私钥计算出sign,双方校验sign的值是否正确即可,sign计算方法(伪代码):

ksort (
    array(
        cmd=’xx’ ,
        timestamp=>’xx’ ,
        version=>’xx’ ,
        ticket=>’xx’ ,
        source=>’xx’ ,
        body=>json_encode(array(‘xx’=>’xx’ ,…)),
        secret=>’xx’,
        encrypt=>’xx’,
        fields=>’a|b’,
    )
)

SIGN=md5(‘body={…}&cmd=xx&…&version=3’),拼接顺序为ksort之后key值顺序。

关于标红函数实现的说明:

ksort:关于协议数据的 key 进行排序;排序规则:按照 ASSIC 编码升序。
json_encode:所有非 ASSIC 码字符均转换为对应的 Unicode 表示。
md5:摘要计算函数(RFC 1321),计算结果为 32 个字符长度。
implode: 用&将一维数组转为字符串。

注意:body中的业务参数中含有特殊符号:如 +,%,无需进行urldecode。

示例:

① 原始数据:

Array
(
    [cmd] => shop.create
    [timestamp] => 1430719064
    [version] => 3
    [ticket] => CBB291F6-33BE-57CC-8FE3-441FE6E7BA6C
    [source] => test_source
    [body] => json_encode(Array
    	(
            [shop_id] => 123456
            [name] =>  测试商户
    	)
    )
    [secret] => test_secret
    [encrypt] => des.v1
    [fields] => a|b
)

② 对原始数据进行 ksort 处理,得到按照键升序排列的数据:

Array
(
    [body] => json_encode(Array
        (
            [shop_id] => 123456
            [name] =>  测试商户
        )
    )
    [cmd] => shop.create
    [encrypt] => des.v1
    [fields] => a|b
    [secret] => test_secret
    [source] => test_source
    [ticket] => CBB291F6-33BE-57CC-8FE3-441FE6E7BA6C
    [timestamp] => 1430719064
    [version] => 3
)

③ 对步骤②数组转为字符串

body = {"name":"\u6d4b\u8bd5\u5546\u6237","shop_id":"12345"}&cmd=shop.create&encrypt=des.v1&fields=a|b&secret=test_secret&source=test_source&ticket=CBB291F6-33BE-57CC-8FE3-441FE6E7BA6C&timestamp=1430719064&version=3

④ 对步骤③所得的数据进行 md5 计算,即得到用于本次数据传输的签名 sign:

9CB895D005A4EC264688F110D533CB03	

1.4 接口返回状态码说明

所有操作如果成功则返回状态码0,如果失败状态码为非0

1.5 请求唯一标识ticket

ticket标识请求的唯一性,是由大写字母和0-9的数字及减号组成的36位字符串。 对于下行请求的响应,它的ticket可以直接赋值为下行请求的ticket。 上行请求中的ticket需要自行生成,生成方法:

① 根据当前时间生成一个字符串,其值可以是时间戳,为了尽可能保证这个字符串的唯一性,可以与随机数拼接在一起,同时时间精度越高越好,也能降低重复的概率。然后计算字符串的md5值,并把字符串的小写字母转换为大写,PHP代码示例:

mt_srand((double)microtime()*10000);
strtoupper(
    md5(
        uniqid(
            rand(), true
        )
    )
)

② 最后对① 的结果调整格式,在左起第8、12、16、20位字符后面添加减号:

CBB291F633BE57CC8FE3441FE6E7BA6C => CBB291F6-33BE-57CC-8FE3-441FE6E7BA6C

测试流程

  • 1.测试账号创建成功后,平台会为此合作方账号(source)自动创建一个测试门店,可在商户列表中查看平台商户ID、合作方商户ID
  • 2.开发者使用测试账号(source)、密钥和测试门店,分模块进行接口开发测试
  • 3.下单测试说明:开发者需使用平台商户ID,更换以下链接中的商户ID进店下单(需将定位地址改成门店位置附近)
    • (1)饿了么门店链接:https://h5-newretail.faas.ele.me/static/h5_newretail/pages/shop.html?id=2187921973&isTransfer=1,将链接中ID更换成开发者测试门店的平台商户ID后,使用链接和二维码生成工具生成门店二维码,打开支付宝或饿了么app扫码进店下单
    • (2)饿了么星选门店链接:https://h5.ele.me/newretail/starshop/?shop_id=2235648582,将链接中shop_id更换成开发者测试门店的平台商户ID后,将链接复制到浏览器可打开门店,按照页面提示下单测试
    • (3)门店位置:北京市海淀区上地信息路嘉华大厦
    • (4)修改定位地址方法:
      • a.支付宝扫码修改定位:打开支付宝,顶部搜索“饿了么”,进入饿了么后选择左上角定位,将当前定位地址改成门店所在位置。然后退回到支付宝首页,打开扫一扫扫描店铺二维码,下单测试
      • b.饿了么app修改定位:打开饿了么app,首页左上角定位,将当前定位改成门店所在位置,然后返回饿了么app首页扫码进店下单测试
      • c.饿了么星选app修改定位:打开饿了么星选app,首页左上角定位,将当前定位改成门店所在位置,然后在收藏店铺中进店下单测试

注意事项:

  • 1.门店营业会校验资质、合同、配送范围信息是否齐全
  • 2.当前不支持平台配送方式的订单流程测试
  • 3.建议测试单使用手机端测试,PC端下单不支持测试售后流程
  • 4.如开发者想登陆新商家端,可在邮箱查看测试门店的账号密码或联系门店对应的销售经理设置门店手机号,使用新账号登陆此门店商家端

开发者规范

开发者规范是指开放平台对开发者的官方指导建议,是对以往对接经验的历史总结,对开发者有重大参考意义,请各位开发者仔细阅读,并把相关建议融入到自己系统里面,使系统更加强壮、完善。如若发现开发者系统不遵循开发者规范,经常发生严重问题,将会对开发者作降级并记录在案处理,作为以后合作评估的重要参考依据,严重违规者将终止合作,详情如下所示:

  • 1.接收平台推送订单
    • (1)平台向开发者系统推送订单时,第一次调用失败,会重试两次,重试失败将不再推送此订单,并取消订单。
    • (2)开发者接收推送订单的接口,建议部署多台服务器,其中一台服务器发生宕机,可快速分发至另外一台服务器,避免单服务器部署宕机风险。
  • 2.通知平台接单
    • (1)开发者通过“order.create”接口接收到推送的订单后,需要调用“order.confirm”接口告知平台是否接受订单。
    • (2)在调用“order.confirm”接口时,系统可能会返回失败结果,比如用户在商户接单前取消订单或者系统发生故障导致接单失败等,此时订单在平台已经被取消,如果继续让商户出餐,可能导致餐损,并且餐损需要由商户侧承担。因此,务必在返回成功结果时,才能让用户出餐。
    • (3)如果“order.confirm”第一次调用失败,请进行重试,建议重试3次,每次间隔几秒钟。
  • 3.推送订单至门店
    • (1)需要对接方做好重试机制,多次重试之间要有一定时间间隔。
    • (2)经过重试机制后依然推送失败,如果是个案,则通知平台取消订单,并告知取消原因。
    • (3)如果出现连续订单推送失败,则需要视原因考虑将门店暂停营业,并将问题通过工单的方式上报。如果门店能够使用商家端,则需要提醒商户去饿百零售商家端接单。
  • 4.取消订单
    • 取消订单需要如实返回取消原因。详细真实的取消原因,可以帮助平台运营人员和商家快速找准问题,及时解决因取消带来的不必要的损失,同时减少双方不必要的沟通

SDK和DEMO

- API3.0 PHP版DEMO点击查看

- API3.0 JAVA版DEMO点击查看