1. 使用速递易

1.1. 注册速递易

进入 速递易开放平台注册页面 填写注册信息,提交成功后,我们将向你的注册邮箱发送一封注册确认邮件。

点击邮件中的链接,进入邮箱验证页面,点击确认邮箱激活邮箱。

confirm email
确认注册邮箱

验证邮件成功后重新登录,进入 填写认证信息页面 填写相应的信息,确认填写正确后提交,我们的工作人员将在一到两个工作日内进行相应的审核工作。

未验证邮箱和通过审核的用户可以登录并进行密码修改等操作,但不能使用箱格功能。

1.2. 使用网站管理订单

以下功能都需要首先通过认证

登录后点击网站右上方的用户名,选择进入后台

to backend
进入后台

在管理界面你会看到分为预约管理订单管理,其中订单管理预约订单普通订单

如果是通过预约接口产生的订单我们称之为预约订单,预约订单包含了预约投件人、取件人和预约时间等信息。而在订单管理中我们可以管理所有的投递信息,包括添加了投递员之后由投递员直接在快递柜上投递所产生的订单,这部分订单在订单管理管理中显示为普通订单;除了这一部分,预约订单在投件人投件之后也会产生一条投件记录,也就是预约订单。

换言之,预约投递在投件人投件之后,在预约订单和订单管理中都能查询到该订单的记录。而普通投递始终也只能在订单管理中查询得到。

1.2.1. 管理预约

管理预约界面如下

reserve manage
管理预约页面

在管理预约界面,我们可以:

  • 重新发送预约码(要求预约成功,未超过预约时间且预约尚未使用)

  • 重新预约,如果预约失败

  • 导出数据为Excel

  • 发起新的预约

1.2.2. 发起预约

网站提供了网页预约的功能,即可以帮助用户在零开发成本的情况下使用预约功能,又可以帮助开发者迅速熟悉预约流程。预约流程的解释详见 预约投递工作流

网页预约界面如下:

reserve
网页预约

首先需要选择城市,注意只有开通了投递权限的城市才会显示在列表中,选择城市后在搜索网点框中输入网点名称,根据自动补全选择性相应的网点,最后选择设备。在完成所有信息填写后点击提交,如果填写无误服务器将向快递柜发起一个预约请求,如果快递柜网络中断或者没有可能箱格,预约过程便会失败,界面上将由相应的提示;如果预约成功,预约码将通过短信发送到投件人手机上。

城市、网点和设备

在接口文档中我们将看到完全定位一台设备需要arealatticedevice。area代表行政区划,包括省、市和区三级。lattice代表一个网点,速递易可能会在一个点上部署多台设备,这些设备便组成了一个网点,注意同一网点下的设备也可能在位置上并不相邻。最后是设备,也就是智能快递柜。

1.2.3. 订单管理

在订单管理页面,你可以查看所有订单的信息,包括预约订单和普通投递,还可以查看订单的详细信息。

delivery
订单管理

2. 开放平台工作流

开放平台提供了两种使用方式——预约投递和直接投递。

2.1. 预约投递工作流

在预约投递中,第三方服务器首先向开放平台发起一个预约请求,预约请求的应当包含如下信息:

参数名

类型

是否必填

说明

device_id

String

速递易设备ID

box_type

Int

箱格类型 0:大箱 1:中箱 2:小箱 3:冰箱

notify_url

String

回调第三方系统的地址

auto_upgd

Boolean

是否可以自动升箱

sender_name

String

投递人姓名

sender_mobile

String

投递人手机

order_no

String

第三方订单号

consignee_mobile

String

取件人手机号

consignee_name

String

取件人姓名

payment

Integer

到付金额,如果不是到付件则为0

duration

Integer

预约时长,单位分钟,默认240分钟

pay_type

Integer

超期付费方式 0:快递柜付费 1:从商户账户扣除

更详细的信息参看API文档 发起预约请求

其中回调地址是预约成功或失败后回调消息发送的地址;是否可以自动升箱表示如果当前预约的箱格已满是否允许使用更大的箱格代替,注意更大的箱格价格也更贵;投递人是接收预约码并投件的人,而取件人则是接收开箱码并取件的人;到付金额选项当前不可用;预约时长表示快递柜预约成功后等待投件的时长,超过时长保留的箱格将被释放;超期付费方式如果是商家付费那么一旦取件超期费用将从商户账户中扣取。

如果是在开放平台网页上预约,预约码将直接通过短信发送到投件人手机上。如果使用接口的方式发起预约,预约码将通过回调的方式返回第三方服务器,第三方服务可以进行一些额外的操作,如等用户付费之后才将预约码发送给用户。

当开放平台收到合法的预约请求后,将向指定的快递柜发起预约请求,向快递柜发起的请求有几种可能结果:

  • 超时

  • 失败,可能是请求的箱格已满

  • 成功

不论哪一种结果,开放平台都将在20秒内回调第三方平台。如果预约成功,还将在回调中携带预约码和实际预约到的箱格类型。此时第三方需要将预约码发送到投件人手上——经过或不经过一些先决步骤。投件人拿到预约码之后,需要在预约的有效期内前往预约网点投件,如果投件成功,服务器将再次回调第三方服务器,这次回调我们将通知第三方投件事件的发生或取件码,同时取件码也将通过短信的方式发送到取件人手机上。取件人得到取件码后到指定快递柜取件,开放平台将再次回调第三方地址告知取件事件的发生,全流程结束。

发起预约的请求返回仅表示服务器已经收到预约请求,并不表示预约已经返回结果,具体的预约结果以回调结果为准。

2.1.1. 死信处理

开放平台回调第三方的过程中可能会收到错误,例如第三方程序离线维护或者发生内部错误。此时开放平台将进行一定次数的重试,如果超出重试次数,消息将被收入死信箱,第三方可以通过主动拉取的方式读取死信箱中的信息。详细信息请参看 获取死信

2.2. 普通投递

普通投递的工作流程和一般快递使用速递易快递柜的工作流程基本相同,只是用户主体从快递公司换成了开放平台用户。和快递员投递相比,开放平台的普通投递并不要求投递员账户充值,相反费用会以日结的方式从商家账户中扣取。

投递员登录快递柜时所使用的短信验证码长期有效,不需要每次分别获取。

3. Http接口

预约服务的核心工作流包括一次第三方的主动请求和若干次被调。一次主调也就是发起预约时的调用

详细的数据格式请参考接口文档

3.1. 认证

(TODO)

3.2. 预约接口

要使用预约,第三方首先使用 POST 方式向开放平台发起预约请求(参见预约投递工作流)。开放平台返回200状态码和预约号,表示已经成功收到预约请求,第三方此时应该保存该预约号并将其和自身的业务号做关联,预约号是一系列后续数据和操作的凭证。收到预约请求的20秒内,开放平台将以 POST 方法回调第三方提供的地址告知预约结果。

如果预约失败,流程结束。如果预约成功,开放平台将在快递柜发生事件时以 PUT 方法回调第三方接口,事件包括:

  • 用户投件

  • 用户取件

  • 超时未投件,保留箱格被释放

  • 值守取给投件人等其他事件

其中,在用户投件事件中,我们将把取件码一并发送给第三方。

3.2.1. 取消预约

如果不再需要预约,可以通过取消预约接口结束当前预约。取消预约后保留的箱格将被释放,同时预约服务费将立刻结算。注意取消预约并不会等待快递柜确认,因此可以保证费用准确结算,另一方面,如果快递柜处于网络断开的状态,可能无法及时收到取消预约的消息,被取消的预约可能继续有效,用户将可以继续使用预约码投件,第三方也可能继续收到之后事件的回调。因此,请不要把业务逻辑建立在取消一定会成功的基础上。

3.3. 其它接口

其它接口大致包括两类,一类是发起预约时需要获得的辅助信息,包括行政区划、网点和设备信息。这类信息变动比较小,建议第三方长期缓存。第二类则是对于箱格和预约状态的查询。

3.4. 接口调用限制

对于接口的调用我们可能会做一定限制,具体包括两类:

  • 调用频率的限制,以小时为单位有一定的调用次数上限

  • 保留箱格的限制,保留的箱格不能超出上限

超出以上限制将会返回420和421,请联系我们以获得账户具体的限制值。