开放平台
文档中心
平台简介
软件服务商接入

一.注册OP账号

访问注册页面(https://user-p.gfn.cainiao.com/partner/register?redirectUrl=https://open.gfn.cainiao.com/login)

二.登录OP

访问登录页面(https://open.gfn.cainiao.com/login)使用商户账号，即可成功登陆OP，如下图

三.认证个人/公司信息

1.点击进入认证界面->完善基本信息->点击保存，如下图

备注:填写相关信息并提交，如下图

四.申请APP

1.在接入管理->我的APP页面点击新增，填写相关信息并提交，如下图

2.填写相关信息并提交，如下图

3.等待OP人工审核（大概3-5个工作日）

4.审核通过之后，点击APP名称将获取APP对应的app_key和app_secret(请妥善保管app_key和app_secret)，见下图：

5.如果审核不通过，则可根据提示信息修改后，重新提交审核。

五.用户授权

如果您的应用和平台对接时需要获取用户隐私数据（如商品、订单等），为保护用户隐私和数据安全，对用户数据进行操作需要授权， 即获取授权令牌authorization_code, 并用授权令牌获取访问令牌access_token。。这种情况下， 您的应用需要引导用户完成使用帐号“登录授权”的流程。该流程采用标准OAuth2.0协议作为用户身份验证与授权协议

授权流程图如下:

授权流程

1.取得授权码authorization_code

a) http请求方式：GET
b) http请求地址:https://open.gfn.cainiao.com/authorize/get
c) 请求参数

名称 类型 是否必须 描述
client_id String 是 注册App由系统生成的app_key
response_type String 是 response_type=code这个是Oauth的固定写法
redirect_uri String 是 授权成功后的回调地址，需要进行URL编码
d) 例如请求地址: https://open.gfn.cainiao.com/authorize/get?client_id=a3f9e3ac-7873-4686-92ef-e2cf57b5406f&response_type=code&redirect_uri=http%3A%2F%2Fwww.baidu.com 正常情况下授权服务器会回调客户端的redirect_url(以百度网址为例)并附加上code
e) 正常会重定向如下地址: https://www.baidu.com/?code=caec4037079b6b10bb0310e7a1da1874

2.根据authorization_code获取access_token

a)http请求方式:POST
b)http请求地址:https://open.gfn.cainiao.com/accessToken/get
c)ContentType:application/x-www-form-urlencoded
d)请求参数

名称 类型 是否必须 描述
client_id String 是 注册App由系统生成的app_key
client_secret String 是 注册App由系统生成的app_secret
grant_type String 是 默认值:authorization_code
code String 是 通过调用authorization_code接口返回的code值,一次有效
redirect_uri String 是 可填写应用注册时回调地址域名。redirect_uri指的是应用发起请求时，所传的回调地址参数，在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致
示例如下： d)响应参数
参数 类型 描述
expires_in Nubmer accessToken过期时间,单位为毫秒.
access_token String 授权码,有效期7天
refresh_token String 刷新码,有效期1年

3.根据refresh_token换取access_token

a)如果refreshToken有效并且accessToken已经过期，那么可以使用refresh_token换取access_token，不用重新进行授权，然后访问用户隐私数据。 refresh_token过期则需要重新走获取Oauth2.0令牌流程重新授权。
b)http请求方式:post
c)http请求地址:https://open.gfn.cainiao.com/accessToken/get
d)ContentType:application/x-www-form-urlencoded
e)请求参数

名称 类型 是否必须 描述
client_id String 是 注册App由系统生成的app_key
client_secret String 是 注册App由系统生成的app_secret
grant_type String 是 默认值:refresh_token
refresh_token String 是 上一步返回的refresh_token值
redirect_uri String 是 可填写应用注册时回调地址域名。redirect_uri指的是应用发起请求时，所传的回调地址参数，在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致
f)响应参数和获取accessToken的返回的相同,不再赘述

六、生成公共参数签名

1.公共请求参数

名称 类型 是否必须 描述
method String 是 API接口名称
app_key String 是 应用接入申请的AppKey
v String 是 API协议版本，参考接口版本号
timestamp Long 是 时间戳,取当前时间的毫秒数.例如日期2018-07-26 16:06:53:187,转换成毫秒数为1532592413187.
format String 是 提交的业务数据。默认为json格式，可选值：json
sign String 是 API输入参数签名结果; App Secret的加密签名。使用MD5加密算法
access_token String 是 通过OAuth授权方式获得，要求软件服务商必须传入，客户（B类客户）可不传或传空值
language String 否 响应信息的语言，支持cn（中文），en（英文）

2.按首字母升序排列, access_token和language不参与签名, 例如如下测试数据
app_key=16081f05-e8fc-4250-b9c4-0660d1ecbb28
format=json
method=ds.xms.order.create
timestamp=1532592413187
v=1.0

3.连接字符串(去掉所有=和&),连接参数名与参数值,并在尾加上body信息和appSecret，此处假设appSecret=7eebf328-8e5a-4030-904d-ec6e89174fbc， 假设body信息(Json压缩格式)如下:{"aa":"bb"}

那么拼接成的字符串如下：

app_key16081f05-e8fc-4250-b9c4-0660d1ecbb28formatjsonmethodds.xms.order.createtimestamp1532592413187v1.0{"aa":"bb"}7eebf328-8e5a-4030-904d-ec6e89174fbc

上面红色部分为请求body数据 将上面生成的字符串使用MD5加密生成32位小写签名值sign，下面要用到。 （签名算法统一采用MD5）参考签名网址:https://www.cmd5.com/hash.aspx?s=123456 上述字符串采用MD5加密后：32位签名值->ff4af77c062a9b97d98aa29777621c4a

七、调用openAPI平台接口

1.https请求方式: post
2.https地址 https://open.gfn.cainiao.com/router/api/service
3.ContentType:application/json
4.公共请求参数,放在url后面,使用&连接

参数 类型 是否必须 描述
method String 是 接口名称，参考API文档。比如获取包裹信息：method=fpx.dps.pkg.get
app_key String 是 应用接入申请的app key
v String 是 协议版本号。比如：1.0，2.0,目前默认1.0
timestamp Long 是 时间戳,取当前时间的毫秒数.例如日期2018-07-26 16:06:53:187,转换成毫秒数为1532592413187.
format String 是 提交的业务数据。默认为json格式，可选值：json
sign String 是 参数签名。MD5加密
access_token String 是 通过OAuth授权方式获得。
language String 否 响应信息的语言，支持cn（中文），en（英文）
4.body请求参数,放在请求体,使用json格式
5.响应参数
参数 类型 描述
result String 响应结果: 0:失败,1:成功, 2:部分成功
msg string 描述
data String 返回内容
6.用我们上面步骤生成的参数进行示例:
请求URL:https://open.gfn.cainiao.com/router/api/service?method=ds.xms.order.create&app_key=a3f9e3ac-7873-4686-92ef-e2cf57b5406f&v=1.0&timestamp=1532592413187&format=json&sign=9715c6172872252f3c59a8528e6873d6&access_token=20c7513b4222fd6acc1fe4e34ff9ba8d
注：
a. api域名，正式环境为open.gfn.cainiao.com
b. method, app_key参数要与生成参数签名一致。sign参数是生成参数签名步骤生成的md5加密后得到的
c. 请求和响应的消息主体使用json格式
d. 响应内容的json顶级结构是不变的，只有errors和data节点下的数据会变化

八.发布上线

在OP测试环境联调通过后，即可切换到生产环境正式发布上线

FAQ

有用 我要提问