海管家海外舱单对接文档

# 接口调用凭证

# AccessToken

获取全局唯一接口调用凭据（AccessToken）。

注意

调用绝大多数接口时都需使用 AccessToken，开发者需要进行妥善保存。

# 请求地址

POST https://beta-callback.hgj.com/ingress-ng/aci/openapi/token/accesstoken
Content-Type: application/json

{
  "appKey": "G5QR9b8T",
  "appSecret": "485477b1c1264db695a3994be29e90b3"
}

# 请求参数

属性 类型 必填 说明
appKey string 是 API用户标识 (对接时由海管家分配)
appSecret string 是 获取凭证的密钥 (对接时由海管家分配)

# 返回值

属性 类型 说明
accessToken string 获取到的凭证
expiresIn number 凭证有效时间，单位：秒。目前是7200秒之内的值。

# 返回数据示例

{
  "accessToken": "d92e51286719425bbd80b5eb6a94087b",
  "expiresIn": 7200
}

# AccessToken 的存储与更新

  • AccessToken 的有效期目前为 2 个小时，需定时刷新，重复获取将导致上次获取的 AccessToken 失效；

  • 建议开发者使用中控服务器统一获取和刷新 AccessToken，其他业务逻辑服务器所使用的 AccessToken 均来自于该中控服务器，不应该各自去刷新，否则容易造成冲突，导致 AccessToken 覆盖而影响业务；

  • AccessToken 的有效期通过返回的 expireIn 来传达，目前是7200秒之内的值，中控服务器需要根据这个有效时间提前去刷新。在刷新过程中，中控服务器可对外继续输出的老 AccessToken，此时在5分钟内，新老 AccessToken 都可用，这保证了第三方业务的平滑过渡；

# Timestamp + Nonce

防止重放攻击

Sign 虽然解决了请求参数被篡改的隐患，但是还存在着重复使用请求参数伪造二次请求的隐患

Timestamp = 当前系统的毫秒值 ,系统可以过滤掉那些超时请求 (timestamp-now>timeOut)

Nonce 指唯一的随机字符串，用来标识每个被签名的请求。通过为每个请求提供一个唯一的标识符，服务器能够防止请求被多次使用.

Nonce 需要保证在一定时间内不会重复即可 可以使用 Timestamp + 随机数 生成

# Staff

Staff 是用户在海管家平台注册时留存的手机号码，并不是企业号码

# Sign

防止篡改

使用 Sign (参数签名) 来防止请求数据被恶意篡改

# Sign 生成方式

  1. 将 AccessToken Timestamp Nonce Staff 和 Body 中参数 按照 key=value 方式拼接
Access-Token=61c3f82784e14a22aec696240611bea9
Timestamp=1592377523990
Nonce=1272803502673977345
Staff=18036094790

// 这里Body是指请求体中的值
Body=xxx
  1. 以key名升序排序 并以 & 将参数 拼接起来
Access-Token=61c3f82784e14a22aec696240611bea9&Body=xxx&Nonce=1272803502673977345&Staff=18036094790&Timestamp=1592377523990
  1. 参数尾部拼接AppSecret(这里密钥仅用于生成签名,请不要在请求中携带)
Access-Token=61c3f82784e14a22aec696240611bea9&Body=xxx&Nonce=1272803502673977345&Staff=18036094790&Timestamp=1592377523990&AppSecret=485477b1c1264db695a3994be29e90b3
  1. 对最终参数进行MD5加密即可得到32位小写 Sign
7543cc3757676c1d88ca951822cf8e57

# 携带方式

AccessToken Timestamp Nonce Staff Sign 支持以下2种携带方式:

注意

参数按照命名规范在不同的位置命名不同,具体请参考下方示例

  1. QueryString
https://beta-callback.hgj.com/ingress-ng/aci/openapi/em/send?_accessToken=f6645125abaa4e0ab12d1b638843ff5b&_timestamp=1592364092493&_nonce=1272856656035713026&_staff=18036094790&_sign=d72bfe24c25f0d19dc8e8df81b10798e
  1. Header
https://beta-callback.hgj.com/ingress-ng/aci/openapi/em/send
Access-Token: 61c3f82784e14a22aec696240611bea9
Timestamp: 1592377523990
Nonce: 1272803502673977345
Staff: 18036094790
Sign: e0eedd4efada8db4a653a009f9b00934

← EM发送接口 →