商户接入

一.注册商户账号

1.访问商户首页(https://sso-e.gfn.cainiao.com)点击登录框右下角的注册按钮打开注册用户页面,如下图

2.填写详细信息,如下图:

二.登录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.如果审核不通过,则可根据提示信息修改后,重新提交审核。

五、生成公共参数签名

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.http请求方式: post
2.http地址 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加密
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=16081f05-e8fc-4250-b9c4-0660d1ecbb28&v=1.0&timestamp=1532592413187&format=json&sign=c4a41de412206ad4473c72f273082f92
注:
a. api域名,正式环境为open.gfn.cainiao.com
b. method, app_key参数要与生成参数签名一致。sign参数是生成参数签名步骤生成的md5加密后得到的
c. 请求和响应的消息主体使用json格式
d. 响应内容的json顶级结构是不变的,只有errors和data节点下的数据会变化
7.错误码列表
错误码 描述 说明
000012 签名验证错误 参考接口文档,请参考官网检查加签字符串是否符合规范
000004 JSON解析失败 请检查请求体是否符合JSON格式规范
000013 app_key校验失败 请检查app_key是否正确
000014 认证参数非法 参考接口文档,检查参数是否符合要求
000011 API接口不存在 请检查接口名称是否正确
000015 API接口不可用 请联系技术支持人员
000016 API接口未授权 请联系技术支持人员进行授权
000017 访问太过频繁,请一分钟后再试 请一分钟后再试
000018 APP不存在 请登录后台检查APP是否已创建
000019 限流策略未配置,请联系客服 请联系技术支持人员
000020 请求超时或异常 请稍后再试或联系技术支持人员
000021 用户和APP不匹配 请登录后台检查APP是否正确
000022 用户未授权,请联系技术支持人员 请联系技术支持人员进行授权
000023 用户不可用 请联系技术支持人员
000024 服务商接口404 请稍后再试或联系技术支持人员确认接口是否存在
000025 用户类型与接口不匹配,请联系客服 请联系技术支持人员

七.发布上线

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