简体中文

接入指南

1 请求结构

1.1 服务地址

1.2 通信协议

所有接口均通过 HTTPS 进行通信(仅支持TLS 1.2及以上版本),提供高安全性的通信通道。

1.3 请求方法

POST

1.4 字符编码

均使用UTF-8编码。

2 公共参数

2.1 请求参数

参数类型必填描述
HeaderContent-Typeapplication/json;charset=UTF-8
Headerappkey条件必填应用唯一标识 (认证方式为hmacsha256时,必填)
Headersign条件必填hmacSha256(body+timestamp) (认证方式为hmacsha256时,必填)
Headertimestamp条件必填时间戳/ms,请求有效时间为10分钟 (认证方式为hmacsha256时,必填)
HeaderAuthorization条件必填Bearer Token (认证方式为auth2时,必填)
Body(json)请求业务报文

2.2 返回结果

参数类型长度描述示例
trace_idstring64链路追踪ID8343e51a24f56f501bcc5380a321928e
codestring32响应码,参考《错误码》SUCCESS
messagestring128响应提示成功
successboolean--请求成功标识,当code等于SUCCESS为true,否则为falsetrue
dataobject--响应数据

2.3 请求示例

2.3.1 hmacsha256

shell |复制
curl --location --request POST 'https://logistic-op-gw-sandbox.myshoplinestg.com/v20210706/logistics/order/page'         --header 'appkey: 1354422552635342848'         --header 'sign: c28ea5c7295ddba3aaed27ad58aac7ab11de2d1da00af803f7f60b9c357f6e16'         --header 'timestamp: 1622031669000'         --header 'Content-Type: application/json'         --data-raw '{
            "platform":"E001",
            "timestamp":"16104497124622",
            "version":"1.0.0",
            "create_by":"苌楚",
            "logistics_no":"ERP01LST4873056047290915841"
        }'

2.3.2 auth2

shell |复制
curl --location --request POST 'https://logistic-op-gw-sandbox.myshoplinestg.com/v1/logistics/seller/authenticate' 
        --header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ5c291bCIsInNlbGxlcklkIjoiU0U0OTI1NzQ5NjA2MDM2ODkxNzE3Iiwic3RvcmVJZCI6bnVsbCwidXVpZCI6IjMwZGQ3YzZlLTE3OTMtNGI0NC05OTFhLWE5MGU3ZDMwNjhiOCIsImFwcElkIjoiMTY3MzciLCJkb21haW4iOm51bGx9.H5n-rdg-wC-a8QtObMEAFb6yENSZbb-PSEYbjlsLoHU1d7x8c5BFDh6BluZ4X5dl87sS4Trw7iz21JlrImzQaQ' 
        --header 'Content-Type: application/json' 
        --data-raw '{
            "platform": "E001",
            "seller_id": "SE4925749606036891717",
            "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJ5c291bCIsInNlbGxlcklkIjoiU0U0OTI1NzQ5NjA2MDM2ODkxNzE3Iiwic3RvcmVJZCI6bnVsbCwidXVpZCI6IjMwZGQ3YzZlLTE3OTMtNGI0NC05OTFhLWE5MGU3ZDMwNjhiOCIsImFwcElkIjoiMTY3MzciLCJkb21haW4iOm51bGx9.H5n-rdg-wC-a8QtObMEAFb6yENSZbb-PSEYbjlsLoHU1d7x8c5BFDh6BluZ4X5dl87sS4Trw7iz21JlrImzQaQ",
            "timestamp": "1616059909056",
            "version": "1.0.0",
            "create_by": "zhangsan"
        }'

3 签名方法

3.1 hmacsha256

3.1.1 申请安全凭证

参数凭证
测试环境
appKey: def6a9fc274b2552979a7a9a766f72288bd08bbd
appSecret: 9eac9154c1d716ffd272390dbf77b301345a5f03
生产环境
(线下申请,一经泄露需要马上申请替换)

3.1.2 生成签名

hmacSha256(body+timestamp), 如果body为空则不参与签名,针对GET等其它场景

签名示例代码
java |复制
String secret = "0393e944ee8108bb66fc9fa4f99f9c862481e9e0519e18232ba61b0767eee8c6";
        String message = "{
" +
            "    "platform":"E001",
" +
            "    "timestamp":"16104497124622",
" +
            "    "version":"1.0.0",
" +
            "    "create_by":"苌楚",
" +
            "    "logistics_no":"ERP01LST4873056047290915841"
" +
            "}1622031669000";
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256");
        sha256_HMAC.init(secret_key);
        byte[] bytes = sha256_HMAC.doFinal(message.getBytes("UTF-8"));
        return new String(Hex.encodeHex(bytes));

错误码

错误码描述
A0000001参数不合法
B0000001请求不合法,访问被拒绝!
B0000002业务接口访问失败!
B0000003请求超过阈值,已被限流!
G0000001无有效的第三方服务可用
G0000002第三方接口请求超时
G0000006业务接口异常
X0009999网关内部异常,请您稍后重试!