1. 文档概述

1.1. 文档目的

本文档描述“速递易开放平台”(下称:开放平台)的HTML形式接口的使用场景和接口使用方法。

1.2. 适用范围

速递易开放平台开发人员
商家系统开发人员
相关业务人员

1.3. 名词解释

HTML:超文本标记语言
Redirect(重定向):通过多种方法将各种网络请求重新转到其他位置,在本接口中主要使用网页重定向。

2. 接口适用场景

本接口是“速递易开放平台”现有接入方式的补充,为了让商家能容易的接入开放平台而提供。采用网页(HTML)形式将原本的接口进行封装,通过重定向的方式将用户从商家页面引导至开放平台页面,在完成箱格选择、预约等操作后,将页面重新定向回商家系统。 成功对接了速递易HTML形式接口后,在商家应用页面,点击配送方式“速递易”,即可跳转到速递易HTML5页面,速递易HTML5页面会推荐该用户常用和附近速递易设备,同时支持手动搜索设备,当用户选择了设备,将跳转到商家应用页面。页面跳转流程如下图:

img1
图1

注意:目前仅提供手机微信客户端中使用的HTML页面,暂不提供PC版本。

3. 接口说明

img2
图2

商家系统通过接口“3.1箱格预约”将用户引导至开放平台HTML页面,并附带参数。用户在开放平台HTML页面选箱格,选定箱格时,开放平台将会为商家预约该箱格并保留30分钟,同时会将预约订单编号通过接口“3.2预约结果”反馈给商家系统,并将用户重新引导回商家界面。在30分钟内,商家必须通过接口“3.3获取预约码”发送预约订单编号进行预约确认,并获取箱格预约码。注意:如果没有对预约进行确认,开放平台在30分钟后将自动取消。

3.1. 箱格预约

重定向地址:http://ip:port/v1/api_redirect?pid=x&data=x&timestamp=x&sign=x

3.1.1. 请求参数说明

pid=速递易开放平台为每一位注册的开放平台合作伙伴发放唯一标识符
data=箱格选择初始化参数,JSON格式字符串
timestamp=1970年至今的秒数
sgin=Hex(HMAC-SHA1(SDYPartnerSecret,pid=?&data=?&timestamp=? ))
data 字段说明
名称 类型 必填? 说明

auto_upgd

Boolean

是否可以自动升级箱格

box_t

Integer

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

callback

String

回调第三方系统地址

cust_n

String

用户手机号

cust_p

String

用户手机号

cust_u_t

Integer

当前用户类型:0 用户发货;1 用户收货

biz_n

String

商家相关快递员名称

biz_p

String

商家相关快递员手机

duration

Integer

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

pay

Integer

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

pay_t

Integer

超期付费方式:0 终端付费;1 从商户账户扣除

3.2. 预约结果

重定向地址: 商家在箱格预约中的callback地址参数中增加data字段,如:http://ip:port/xxx?value1=x&data=x 其中data为开放平台新增的字段,注意不要在商家的回调请求中出现。

data 字段说明
名称 类型 必填? 说明

resv_order_no

String

预约订单的编号

result

String

预约结果:success 预约成功, fail 预约失败, timeout 快递柜超时或未响应

3.3. 获取预约码

将参数组装为JSON格式,以POST方式发送到以下地址:http://ip:port/v1/confim_order_no/, 该接口需要进行认证签名,具体方式详见 《速递易开放API认证规范》

3.3.1. 请求参数说明

data 字段说明
名称 类型 必填? 说明

resv_order_no

String

预约订单的编号

order_no

String

实际商家订单编号

3.3.2. 响应参数说明

data 字段说明
名称 类型 必填? 说明

result

String

预约结果:success 预约成功

resv_order_no

String

预约订单的编号

order_no

String

商家订单编号

box_type

Integer

实际取得的相关类型

upgraded

Boolean

实际是否升箱

box_no

Integer

箱格序号

resv_code

String

预约码